1
---
2
name: accessibility-testing-superpower
3
description: |
4
Performs WCAG compliance audits and accessibility remediation for web applications.
5
Use when: 1) Auditing UI for WCAG 2.1/2.2 compliance 2) Fixing screen reader or keyboard navigation issues 3) Implementing ARIA patterns correctly 4) Reviewing color contrast and visual accessibility 5) Creating accessible forms or interactive components
6
---
7
8
# Accessibility Testing Workflow
9
10
## Configuration
11
12
- **WCAG Level**: ${wcag_level:AA}
13
- **Component Under Test**: ${component_name:Page}
14
- **Compliance Standard**: ${compliance_standard:WCAG 2.1}
15
- **Minimum Lighthouse Score**: ${lighthouse_score:90}
16
- **Primary Screen Reader**: ${screen_reader:NVDA}
17
- **Test Framework**: ${test_framework:jest-axe}
18
19
## Audit Decision Tree
20
21
```
22
Accessibility request received
23
|
24
+-- New component/page?
25
| +-- Run automated scan first (axe-core, Lighthouse)
26
| +-- Keyboard navigation test
27
| +-- Screen reader announcement check
28
| +-- Color contrast verification
29
|
30
+-- Existing violation to fix?
31
| +-- Identify WCAG success criterion
32
| +-- Check if semantic HTML solves it
33
| +-- Apply ARIA only when HTML insufficient
34
| +-- Verify fix with assistive technology
35
|
36
+-- Compliance audit?
37
+-- Automated scan (catches ~30% of issues)
38
+-- Manual testing checklist
39
+-- Document violations by severity
40
+-- Create remediation roadmap
41
```
42
43
## WCAG Quick Reference
44
45
### Severity Classification
46
47
| Severity | Impact | Examples | Fix Timeline |
48
|----------|--------|----------|--------------|
49
| Critical | Blocks access entirely | No keyboard focus, empty buttons, missing alt on functional images | Immediate |
50
| Serious | Major barriers | Poor contrast, missing form labels, no skip links | Within sprint |
51
| Moderate | Difficult but usable | Inconsistent navigation, unclear error messages | Next release |
52
| Minor | Inconvenience | Redundant alt text, minor heading order issues | Backlog |
53
54
### Common Violations and Fixes
55
56
**Missing accessible name**
57
```html
58
<!-- Violation -->
59
<button><svg>...</svg></button>
60
61
<!-- Fix: aria-label -->
62
<button aria-label="Close dialog"><svg>...</svg></button>
63
64
<!-- Fix: visually hidden text -->
65
<button><span class="sr-only">Close dialog</span><svg>...</svg></button>
66
```
67
68
**Form label association**
69
```html
70
<!-- Violation -->
71
<label>Email</label>
72
<input type="email">
73
74
<!-- Fix: explicit association -->
75
<label for="email">Email</label>
76
<input type="email" id="email">
77
78
<!-- Fix: implicit association -->
79
<label>Email <input type="email"></label>
80
```
81
82
**Color contrast failure**
83
```
84
Minimum ratios (WCAG ${wcag_level:AA}):
85
- Normal text (<${large_text_size:18}px or <${bold_text_size:14}px bold): ${contrast_ratio_normal:4.5}:1
86
- Large text (>=${large_text_size:18}px or >=${bold_text_size:14}px bold): ${contrast_ratio_large:3}:1
87
- UI components and graphics: 3:1
88
89
Tools: WebAIM Contrast Checker, browser DevTools
90
```
91
92
**Focus visibility**
93
```css
94
/* Never do this without alternative */
95
:focus { outline: none; }
96
97
/* Proper custom focus */
98
:focus-visible {
99
outline: ${focus_outline_width:2}px solid ${focus_outline_color:#005fcc};
100
outline-offset: ${focus_outline_offset:2}px;
101
}
102
```
103
104
## ARIA Decision Framework
105
106
```
107
Need to convey information to assistive technology?
108
|
109
+-- Can semantic HTML do it?
110
| +-- YES: Use HTML (<button>, <nav>, <main>, <article>)
111
| +-- NO: Continue to ARIA
112
|
113
+-- What type of ARIA needed?
114
+-- Role: What IS this element? (role="dialog", role="tab")
115
+-- State: What condition? (aria-expanded, aria-checked)
116
+-- Property: What relationship? (aria-labelledby, aria-describedby)
117
+-- Live region: Dynamic content? (aria-live="${aria_live_mode:polite}")
118
```
119
120
### ARIA Patterns for Common Widgets
121
122
**Disclosure (show/hide)**
123
```html
124
<button aria-expanded="false" aria-controls="content-1">
125
Show details
126
</button>
127
<div id="content-1" hidden>
128
Content here
129
</div>
130
```
131
132
**Tab interface**
133
```html
134
<div role="tablist" aria-label="${component_name:Settings}">
135
<button role="tab" aria-selected="true" aria-controls="panel-1" id="tab-1">
136
General
137
</button>
138
<button role="tab" aria-selected="false" aria-controls="panel-2" id="tab-2" tabindex="-1">
139
Privacy
140
</button>
141
</div>
142
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">...</div>
143
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>...</div>
144
```
145
146
**Modal dialog**
147
```html
148
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
149
<h2 id="dialog-title">Confirm action</h2>
150
<p>Are you sure you want to proceed?</p>
151
<button>Cancel</button>
152
<button>Confirm</button>
153
</div>
154
```
155
156
## Keyboard Navigation Checklist
157
158
```
159
[ ] All interactive elements focusable with Tab
160
[ ] Focus order matches visual/logical order
161
[ ] Focus visible on all elements
162
[ ] No keyboard traps (can always Tab out)
163
[ ] Skip link as first focusable element
164
[ ] Escape closes modals/dropdowns
165
[ ] Arrow keys navigate within widgets (tabs, menus, grids)
166
[ ] Enter/Space activates buttons and links
167
[ ] Custom shortcuts documented and configurable
168
```
169
170
### Focus Management Patterns
171
172
**Modal focus trap**
173
```javascript
174
// On modal open:
175
// 1. Save previously focused element
176
// 2. Move focus to first focusable in modal
177
// 3. Trap Tab within modal boundaries
178
179
// On modal close:
180
// 1. Return focus to saved element
181
```
182
183
**Dynamic content**
184
```javascript
185
// After adding content:
186
// - Announce via aria-live region, OR
187
// - Move focus to new content heading
188
189
// After removing content:
190
// - Move focus to logical next element
191
// - Never leave focus on removed element
192
```
193
194
## Screen Reader Testing
195
196
### Announcement Verification
197
198
| Element | Should Announce |
199
|---------|-----------------|
200
| Button | Role + name + state ("Submit button") |
201
| Link | Name + "link" ("Home page link") |
202
| Image | Alt text OR "decorative" (skip) |
203
| Heading | Level + text ("Heading level 2, About us") |
204
| Form field | Label + type + state + instructions |
205
| Error | Error message + field association |
206
207
### Testing Commands (Quick Reference)
208
209
**VoiceOver (macOS)**
210
- VO = Ctrl + Option
211
- VO + A: Read all
212
- VO + Right/Left: Navigate elements
213
- VO + Cmd + H: Next heading
214
- VO + Cmd + J: Next form control
215
216
**${screen_reader:NVDA} (Windows)**
217
- NVDA + Down: Read all
218
- Tab: Next focusable
219
- H: Next heading
220
- F: Next form field
221
- B: Next button
222
223
## Automated Testing Integration
224
225
### axe-core in tests
226
```javascript
227
// ${test_framework:jest-axe}
228
import { axe, toHaveNoViolations } from 'jest-axe';
229
expect.extend(toHaveNoViolations);
230
231
test('${component_name:component} is accessible', async () => {
232
const { container } = render(<${component_name:MyComponent} />);
233
const results = await axe(container);
234
expect(results).toHaveNoViolations();
235
});
236
```
237
238
### Lighthouse CI threshold
239
```javascript
240
// lighthouserc.js
241
module.exports = {
242
assertions: {
243
'categories:accessibility': ['error', { minScore: ${lighthouse_score:90} / 100 }],
244
},
245
};
246
```
247
248
## Remediation Priority Matrix
249
250
```
251
Impact vs Effort:
252
Low Effort High Effort
253
High Impact | DO FIRST | PLAN NEXT |
254
| alt text | redesign |
255
| labels | nav rebuild |
256
----------------|--------------|---------------|
257
Low Impact | QUICK WIN | BACKLOG |
258
| contrast | nice-to-have|
259
| tweaks | enhancements|
260
```
261
262
## Verification Checklist
263
264
Before marking accessibility work complete:
265
266
```
267
Automated Testing:
268
[ ] axe-core reports zero violations
269
[ ] Lighthouse accessibility >= ${lighthouse_score:90}
270
[ ] HTML validator passes (affects AT parsing)
271
272
Keyboard Testing:
273
[ ] Full task completion without mouse
274
[ ] Visible focus at all times
275
[ ] Logical tab order
276
[ ] No traps
277
278
Screen Reader Testing:
279
[ ] Tested with at least one screen reader (${screen_reader:NVDA})
280
[ ] All content announced correctly
281
[ ] Interactive elements have roles/states
282
[ ] Dynamic updates announced
283
284
Visual Testing:
285
[ ] Contrast ratios verified (${contrast_ratio_normal:4.5}:1 minimum)
286
[ ] Works at ${zoom_level:200}% zoom
287
[ ] No information conveyed by color alone
288
[ ] Respects prefers-reduced-motion
289
```