1
---
2
name: accessibility-expert
3
description: Tests and remediates accessibility issues for WCAG compliance and assistive technology compatibility. Use when (1) auditing UI for accessibility violations, (2) implementing keyboard navigation or screen reader support, (3) fixing color contrast or focus indicator issues, (4) ensuring form accessibility and error handling, (5) creating ARIA implementations.
4
---
5
6
# Accessibility Testing and Remediation
7
8
## Configuration
9
10
- **WCAG Level**: ${wcag_level:AA}
11
- **Target Component**: ${component_name:Application}
12
- **Compliance Standard**: ${compliance_standard:WCAG 2.1}
13
- **Testing Scope**: ${testing_scope:full-audit}
14
- **Screen Reader**: ${screen_reader:NVDA}
15
16
## WCAG 2.1 Quick Reference
17
18
### Compliance Levels
19
| Level | Requirement | Common Issues |
20
|-------|-------------|---------------|
21
| A | Minimum baseline | Missing alt text, no keyboard access, missing form labels |
22
| ${wcag_level:AA} | Standard target | Contrast < 4.5:1, missing focus indicators, poor heading structure |
23
| AAA | Enhanced | Contrast < 7:1, sign language, extended audio description |
24
25
### Four Principles (POUR)
26
1. **Perceivable**: Content available to senses (alt text, captions, contrast)
27
2. **Operable**: UI navigable by all input methods (keyboard, touch, voice)
28
3. **Understandable**: Content and UI predictable and readable
29
4. **Robust**: Works with current and future assistive technologies
30
31
## Violation Severity Matrix
32
33
```
34
CRITICAL (fix immediately):
35
- No keyboard access to interactive elements
36
- Missing form labels
37
- Images without alt text
38
- Auto-playing audio without controls
39
- Keyboard traps
40
41
HIGH (fix before release):
42
- Contrast ratio below ${min_contrast_ratio:4.5}:1 (text) or 3:1 (large text)
43
- Missing skip links
44
- Incorrect heading hierarchy
45
- Focus not visible
46
- Missing error identification
47
48
MEDIUM (fix in next sprint):
49
- Inconsistent navigation
50
- Missing landmarks
51
- Poor link text ("click here")
52
- Missing language attribute
53
- Complex tables without headers
54
55
LOW (backlog):
56
- Timing adjustments
57
- Multiple ways to find content
58
- Context-sensitive help
59
```
60
61
## Testing Decision Tree
62
63
```
64
Start: What are you testing?
65
|
66
+-- New Component
67
| +-- Has interactive elements? --> Keyboard Navigation Checklist
68
| +-- Has text content? --> Check contrast + heading structure
69
| +-- Has images? --> Verify alt text appropriateness
70
| +-- Has forms? --> Form Accessibility Checklist
71
|
72
+-- Existing Page/Feature
73
| +-- Run automated scan first (axe-core, Lighthouse)
74
| +-- Manual keyboard walkthrough
75
| +-- Screen reader verification
76
| +-- Color contrast spot-check
77
|
78
+-- Third-party Widget
79
+-- Check ARIA implementation
80
+-- Verify keyboard support
81
+-- Test with screen reader
82
+-- Document limitations
83
```
84
85
## Keyboard Navigation Checklist
86
87
```markdown
88
[ ] All interactive elements reachable via Tab
89
[ ] Tab order follows visual/logical flow
90
[ ] Focus indicator visible (${focus_indicator_width:2}px+ outline, 3:1 contrast)
91
[ ] No keyboard traps (can Tab out of all elements)
92
[ ] Skip link as first focusable element
93
[ ] Enter activates buttons and links
94
[ ] Space activates checkboxes and buttons
95
[ ] Arrow keys navigate within components (tabs, menus, radio groups)
96
[ ] Escape closes modals and dropdowns
97
[ ] Modals trap focus until dismissed
98
```
99
100
## Screen Reader Testing Patterns
101
102
### Essential Announcements to Verify
103
```
104
Interactive Elements:
105
Button: "[label], button"
106
Link: "[text], link"
107
Checkbox: "[label], checkbox, [checked/unchecked]"
108
Radio: "[label], radio button, [selected], [position] of [total]"
109
Combobox: "[label], combobox, [collapsed/expanded]"
110
111
Dynamic Content:
112
Loading: Use aria-busy="true" on container
113
Status: Use role="status" for non-critical updates
114
Alert: Use role="alert" for critical messages
115
Live regions: aria-live="${aria_live_politeness:polite}"
116
117
Forms:
118
Required: "required" announced with label
119
Invalid: "invalid entry" with error message
120
Instructions: Announced with label via aria-describedby
121
```
122
123
### Testing Sequence
124
1. Navigate entire page with Tab key, listening to announcements
125
2. Test headings navigation (H key in screen reader)
126
3. Test landmark navigation (D key / rotor)
127
4. Test tables (T key, arrow keys within table)
128
5. Test forms (F key, complete form submission)
129
6. Test dynamic content updates (verify live regions)
130
131
## Color Contrast Requirements
132
133
| Text Type | Minimum Ratio | Enhanced (AAA) |
134
|-----------|---------------|----------------|
135
| Normal text (<${large_text_threshold:18}pt) | ${min_contrast_ratio:4.5}:1 | 7:1 |
136
| Large text (>=${large_text_threshold:18}pt or 14pt bold) | 3:1 | 4.5:1 |
137
| UI components & graphics | 3:1 | N/A |
138
| Focus indicators | 3:1 | N/A |
139
140
### Contrast Check Process
141
```
142
1. Identify all foreground/background color pairs
143
2. Calculate contrast ratio: (L1 + 0.05) / (L2 + 0.05)
144
where L1 = lighter luminance, L2 = darker luminance
145
3. Common failures to check:
146
- Placeholder text (often too light)
147
- Disabled state (exempt but consider usability)
148
- Links within text (must distinguish from text)
149
- Error/success states on colored backgrounds
150
- Text over images (use overlay or text shadow)
151
```
152
153
## ARIA Implementation Guide
154
155
### First Rule of ARIA
156
Use native HTML elements when possible. ARIA is for custom widgets only.
157
158
```html
159
<!-- WRONG: ARIA on native element -->
160
<div role="button" tabindex="0">Submit</div>
161
162
<!-- RIGHT: Native button -->
163
<button type="submit">Submit</button>
164
```
165
166
### When ARIA is Needed
167
```html
168
<!-- Custom tabs -->
169
<div role="tablist">
170
<button role="tab" aria-selected="true" aria-controls="panel1">Tab 1</button>
171
<button role="tab" aria-selected="false" aria-controls="panel2">Tab 2</button>
172
</div>
173
<div role="tabpanel" id="panel1">Content 1</div>
174
<div role="tabpanel" id="panel2" hidden>Content 2</div>
175
176
<!-- Expandable section -->
177
<button aria-expanded="false" aria-controls="content">Show details</button>
178
<div id="content" hidden>Expandable content</div>
179
180
<!-- Modal dialog -->
181
<div role="dialog" aria-modal="true" aria-labelledby="title">
182
<h2 id="title">Dialog Title</h2>
183
<!-- content -->
184
</div>
185
186
<!-- Live region for dynamic updates -->
187
<div aria-live="${aria_live_politeness:polite}" aria-atomic="true">
188
<!-- Status messages injected here -->
189
</div>
190
```
191
192
### Common ARIA Mistakes
193
```
194
- role="button" without keyboard support (Enter/Space)
195
- aria-label duplicating visible text
196
- aria-hidden="true" on focusable elements
197
- Missing aria-expanded on disclosure buttons
198
- Incorrect aria-controls reference
199
- Using aria-describedby for essential information
200
```
201
202
## Form Accessibility Patterns
203
204
### Required Form Structure
205
```html
206
<form>
207
<!-- Explicit label association -->
208
<label for="email">Email address</label>
209
<input type="email" id="email" name="email"
210
aria-required="true"
211
aria-describedby="email-hint email-error">
212
<span id="email-hint">We'll never share your email</span>
213
<span id="email-error" role="alert"></span>
214
215
<!-- Group related fields -->
216
<fieldset>
217
<legend>Shipping address</legend>
218
<!-- address fields -->
219
</fieldset>
220
221
<!-- Clear submit button -->
222
<button type="submit">Complete order</button>
223
</form>
224
```
225
226
### Error Handling Requirements
227
```
228
1. Identify the field in error (highlight + icon)
229
2. Describe the error in text (not just color)
230
3. Associate error with field (aria-describedby)
231
4. Announce error to screen readers (role="alert")
232
5. Move focus to first error on submit failure
233
6. Provide correction suggestions when possible
234
```
235
236
## Mobile Accessibility Checklist
237
238
```markdown
239
Touch Targets:
240
[ ] Minimum ${touch_target_size:44}x${touch_target_size:44} CSS pixels
241
[ ] Adequate spacing between targets (${touch_target_spacing:8}px+)
242
[ ] Touch action not dependent on gesture path
243
244
Gestures:
245
[ ] Alternative to multi-finger gestures
246
[ ] Alternative to path-based gestures (swipe)
247
[ ] Motion-based actions have alternatives
248
249
Screen Reader (iOS/Android):
250
[ ] accessibilityLabel set for images and icons
251
[ ] accessibilityHint for complex interactions
252
[ ] accessibilityRole matches element behavior
253
[ ] Focus order follows visual layout
254
```
255
256
## Automated Testing Integration
257
258
### Pre-commit Hook
259
```bash
260
#!/bin/bash
261
# Run axe-core on changed files
262
npx axe-core-cli --exit src/**/*.html
263
264
# Check for common issues
265
grep -r "onClick.*div\|onClick.*span" src/ && \
266
echo "Warning: Click handler on non-interactive element" && exit 1
267
```
268
269
### CI Pipeline Checks
270
```yaml
271
accessibility-audit:
272
script:
273
- npx pa11y-ci --config .pa11yci.json
274
- npx lighthouse --accessibility --output=json
275
artifacts:
276
paths:
277
- accessibility-report.json
278
rules:
279
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
280
```
281
282
### Minimum CI Thresholds
283
```
284
axe-core: 0 critical violations, 0 serious violations
285
Lighthouse accessibility: >= ${lighthouse_a11y_threshold:90}
286
pa11y: 0 errors (warnings acceptable)
287
```
288
289
## Remediation Priority Framework
290
291
```
292
Priority 1 (This Sprint):
293
- Blocks user task completion
294
- Legal compliance risk
295
- Affects many users
296
297
Priority 2 (Next Sprint):
298
- Degrades experience significantly
299
- Automated tools flag as error
300
- Violates ${wcag_level:AA} requirement
301
302
Priority 3 (Backlog):
303
- Minor inconvenience
304
- Violates AAA only
305
- Affects edge cases
306
307
Priority 4 (Enhancement):
308
- Improves usability for all
309
- Best practice, not requirement
310
- Future-proofing
311
```
312
313
## Verification Checklist
314
315
Before marking accessibility work complete:
316
317
```markdown
318
Automated:
319
[ ] axe-core: 0 violations
320
[ ] Lighthouse accessibility: ${lighthouse_a11y_threshold:90}+
321
[ ] HTML validation passes
322
[ ] No console accessibility warnings
323
324
Keyboard:
325
[ ] Complete all tasks keyboard-only
326
[ ] Focus visible at all times
327
[ ] Tab order logical
328
[ ] No keyboard traps
329
330
Screen Reader (test with at least one):
331
[ ] All content announced
332
[ ] Interactive elements labeled
333
[ ] Errors and updates announced
334
[ ] Navigation efficient
335
336
Visual:
337
[ ] All text passes contrast
338
[ ] UI components pass contrast
339
[ ] Works at ${zoom_level:200}% zoom
340
[ ] Works in high contrast mode
341
[ ] No seizure-inducing flashing
342
343
Forms:
344
[ ] All fields labeled
345
[ ] Errors identifiable
346
[ ] Required fields indicated
347
[ ] Instructions available
348
```
349
350
## Documentation Template
351
352
```markdown
353
# Accessibility Statement
354
355
## Conformance Status
356
This [website/application] is [fully/partially] conformant with ${compliance_standard:WCAG 2.1} Level ${wcag_level:AA}.
357
358
## Known Limitations
359
| Feature | Issue | Workaround | Timeline |
360
|---------|-------|------------|----------|
361
| [Feature] | [Description] | [Alternative] | [Fix date] |
362
363
## Assistive Technology Tested
364
- ${screen_reader:NVDA} [version] with Firefox [version]
365
- VoiceOver with Safari [version]
366
- JAWS [version] with Chrome [version]
367
368
## Feedback
369
Contact [email] for accessibility issues.
370
Last updated: [date]
371
```