julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
167 lines
4.3 KiB
Markdown
167 lines
4.3 KiB
Markdown
# Accessibility Audit Workflow
|
|
|
|
**Purpose:** Agent-led accessibility review with explanations and suggestions
|
|
|
|
---
|
|
|
|
## How This Works
|
|
|
|
1. Agent reads the page specification and/or prototype code
|
|
2. Agent evaluates each area against WCAG 2.1 AA
|
|
3. Agent explains findings in plain language
|
|
4. Agent proposes specific fixes
|
|
5. User approves, rejects, or asks for alternatives
|
|
|
|
---
|
|
|
|
## Agent Instructions
|
|
|
|
### Step 1: Analyze Color Contrast
|
|
|
|
Read the design system colors and check:
|
|
|
|
```
|
|
For each text element:
|
|
- Calculate contrast ratio against background
|
|
- WCAG AA requires: 4.5:1 for normal text, 3:1 for large text (18px+)
|
|
|
|
Report:
|
|
"The button text (#FFFFFF) on primary background (#2563EB)
|
|
has a contrast ratio of 8.6:1 ✓ Passes WCAG AA
|
|
|
|
The helper text (#9CA3AF) on white (#FFFFFF)
|
|
has a contrast ratio of 2.9:1 ✗ Fails WCAG AA
|
|
→ Suggestion: Darken to #6B7280 (4.6:1) or #4B5563 (7:1)"
|
|
```
|
|
|
|
**Ask user:** "Should I darken the helper text to #6B7280?"
|
|
|
|
---
|
|
|
|
### Step 2: Analyze Keyboard Navigation
|
|
|
|
Read the page structure and determine logical tab order:
|
|
|
|
```
|
|
Looking at the page layout, the logical keyboard flow should be:
|
|
|
|
1. Skip to main content link (hidden until focused)
|
|
2. Logo (if clickable) → Home
|
|
3. Navigation items left to right
|
|
4. Main content, top to bottom
|
|
5. Form fields in visual order
|
|
6. Submit/action buttons
|
|
7. Footer links
|
|
|
|
Current spec has these interactive elements:
|
|
- `header-logo` ✓ Has behavior defined
|
|
- `nav-home` ✓ Link
|
|
- `form-email` ✗ Missing keyboard info
|
|
- `submit-btn` ✗ Missing focus state
|
|
|
|
→ Suggestion: Add to form-email:
|
|
| Keyboard | Tab to focus, type to enter |
|
|
| Focus | 2px blue ring (#2563EB) |
|
|
```
|
|
|
|
**Ask user:** "Should I add keyboard properties to these elements?"
|
|
|
|
---
|
|
|
|
### Step 3: Analyze Screen Reader Experience
|
|
|
|
Check each element has appropriate labels:
|
|
|
|
```
|
|
Reviewing interactive elements:
|
|
|
|
`booking-submit` - Button with text "Book"
|
|
→ Issue: "Book" alone may be unclear out of context
|
|
→ Suggestion: aria-label="Book this walk slot"
|
|
|
|
`booking-cancel` - Icon button with X
|
|
→ Issue: No text, screen reader says nothing
|
|
→ Suggestion: aria-label="Cancel booking"
|
|
|
|
`status-indicator` - Colored dot (green/red/gray)
|
|
→ Issue: Color only, no text alternative
|
|
→ Suggestion: Add aria-label="Status: Available" and visually hidden text
|
|
```
|
|
|
|
**Ask user:** "Should I add these aria-labels to the spec?"
|
|
|
|
---
|
|
|
|
### Step 4: Analyze Dynamic Content
|
|
|
|
Check state changes and notifications:
|
|
|
|
```
|
|
This page has dynamic content:
|
|
|
|
State changes (drawer opens/closes):
|
|
→ Need: aria-expanded on trigger, focus management
|
|
→ Suggestion: When drawer opens, move focus to drawer header
|
|
|
|
Loading states:
|
|
→ Need: aria-busy="true" on container, "Loading..." announcement
|
|
→ Suggestion: Add aria-live="polite" region for status updates
|
|
|
|
Error messages:
|
|
→ Need: aria-live="assertive" so errors are announced immediately
|
|
→ Suggestion: Link error to field with aria-describedby
|
|
```
|
|
|
|
**Ask user:** "Should I add these dynamic content specifications?"
|
|
|
|
---
|
|
|
|
### Step 5: Summary Report
|
|
|
|
```
|
|
## Accessibility Audit Summary
|
|
|
|
### Passes ✓
|
|
- Color contrast on primary buttons (8.6:1)
|
|
- Semantic HTML structure (header, main, nav)
|
|
- Form labels present
|
|
|
|
### Needs Attention ⚠
|
|
- Helper text contrast (2.9:1 → needs 4.5:1)
|
|
- 3 buttons missing aria-labels
|
|
- Tab order not documented
|
|
- Focus states not specified
|
|
|
|
### Recommendations
|
|
1. Darken helper text to #6B7280
|
|
2. Add aria-labels to icon buttons
|
|
3. Document keyboard flow
|
|
4. Specify focus ring style (2px #2563EB)
|
|
|
|
Implement these changes? [Yes to all / Review each / Skip]
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Reference for Agent
|
|
|
|
| Check | WCAG Rule | Requirement |
|
|
|-------|-----------|-------------|
|
|
| Text contrast | 1.4.3 | 4.5:1 normal, 3:1 large |
|
|
| Focus visible | 2.4.7 | Clear visual indicator |
|
|
| Labels | 1.3.1 | All inputs labeled |
|
|
| Keyboard | 2.1.1 | All functions keyboard accessible |
|
|
| Error ID | 3.3.1 | Errors identified and described |
|
|
| Name/Role | 4.1.2 | Interactive elements have accessible names |
|
|
|
|
---
|
|
|
|
## Agent Prompts
|
|
|
|
Use these to guide the conversation:
|
|
|
|
- "I found {N} contrast issues. Want me to explain each one?"
|
|
- "This button has no accessible name. Should I suggest one based on its purpose?"
|
|
- "The tab order seems unclear. Can you confirm the intended flow?"
|
|
- "Screen readers won't announce this status change. Should I add aria-live?"
|