Accessibility Audit
Run a thorough accessibility audit and produce a remediation plan. Stack-agnostic. Anchored to WCAG 2.1 AA, with notes on AAA where relevant.
This skill goes deeper than the accessibility checks in qa-testing and design-standards. Use this when accessibility itself is the goal.
When to use
- Pre-launch accessibility verification
- Compliance preparation (ADA, EN 301 549, AODA, Section 508)
- Remediation after an audit finding or complaint
- Annual or quarterly accessibility health check
- Onboarding accessibility into a team that hasn't prioritized it before
When NOT to use
- General QA after deploys (use
qa-testing)
- Component-level accessibility implementation (use
frontend-component-build)
- Color contrast for design tokens (use
design-standards or brand-identity)
Required inputs
- The site or product under audit
- The scope (full site, specific section, specific user flow)
- The target standard (WCAG 2.1 AA is most common)
- Any specific concerns or known issues
- Tools available (automated scanners, screen readers, manual testing)
The framework: WCAG's 4 principles
WCAG organizes accessibility around four principles. The audit covers each in depth.
1. Perceivable
Information and UI must be presentable in ways users can perceive.
Audit checks:
- Text alternatives. All non-decorative images have descriptive
alt text. Decorative images use alt="". Complex images (charts, infographics) have long descriptions.
- Time-based media. Videos have captions. Pre-recorded audio has transcripts. Live audio has live captions where required.
- Adaptable. Content structure is conveyed through markup (semantic HTML), not just visual styling. Reading order makes sense when CSS is disabled.
- Distinguishable. Color is not the sole means of conveying information. Text contrast meets AA (4.5:1 normal, 3:1 large). UI element contrast meets 3:1. Audio can be paused, stopped, or muted.
2. Operable
UI components and navigation must be operable.
Audit checks:
- Keyboard accessible. All functionality available via keyboard alone. No keyboard traps. Focus visible.
- Enough time. Time limits can be adjusted, paused, or extended. Auto-updating content can be paused.
- Seizures and physical reactions. No content that flashes more than 3 times per second.
- Navigable. Skip links present. Pages have descriptive titles. Focus order is logical. Link purpose clear from text or context. Multiple ways to find pages (sitemap, search, navigation). Headings and labels are descriptive.
- Input modalities. Pointer gestures have keyboard alternatives. Pointer cancellation supported (mouse-up, not mouse-down for activation). Labels match accessible names. Motion-triggered functionality has alternatives.
3. Understandable
Information and operation must be understandable.
Audit checks:
- Readable. Page language declared (
<html lang="...">). Unusual words and abbreviations have definitions or expansions. Reading level appropriate to audience.
- Predictable. Focus does not change context unexpectedly. Input does not change context unexpectedly. Navigation is consistent across pages. Components that look similar behave similarly.
- Input assistance. Errors are identified clearly. Labels and instructions are provided for input. Error suggestions are given where possible. For pages handling legal commitments or financial transactions, errors can be reviewed and corrected before submission.
4. Robust
Content must be robust enough to work with current and future user agents.
Audit checks:
- Compatible. Markup is valid. Name, role, and value of UI components are programmatically determinable. Status messages can be programmatically determined and announced.
Audit methodology
Stage 1: Automated scan
Run automated scanners across the priority pages. These catch 30 to 50 percent of issues but miss the rest.
Tools:
- axe DevTools (browser extension)
- Lighthouse (Chrome DevTools accessibility audit)
- WAVE (browser extension)
- Pa11y (CLI for batch scanning)
Output: A list of automated findings, by page.
Stage 2: Manual keyboard testing
Unplug the mouse. Navigate the priority user flows using only keyboard.
Test:
- Tab and Shift+Tab move through interactive elements in logical order
- Enter activates buttons and links
- Space activates buttons (and toggles checkboxes)
- Arrow keys navigate within composite widgets (tabs, menus, listboxes)
- Escape dismisses modals, popovers, menus
- Focus is always visible
- Focus returns to a sensible place after modals or popovers close
- No keyboard trap (focus can always leave)
Document: Any flow where keyboard navigation breaks down.
Stage 3: Screen reader testing
Test with at least one real screen reader. Each combination has quirks.
Common combinations:
- VoiceOver + Safari (macOS / iOS)
- NVDA + Firefox or Chrome (Windows)
- JAWS + Chrome (Windows; commercial but common in enterprise)
- TalkBack + Chrome (Android)
Test:
- Page structure announced correctly (headings, landmarks)
- Form labels read with their inputs
- Errors announced when they appear
- Status changes announced (loading, success, error)
- Modal context announced when opened
- Images have meaningful alt text (or are correctly identified as decorative)
Stage 4: Visual testing
Verify the visual aspects of accessibility.
Test:
- Color contrast for all text/background pairs (use a contrast checker)
- UI element contrast (3:1 for icons, borders, focus rings)
- Color-blindness simulation (deuteranopia at minimum)
- Zoom to 200% - content remains usable, no horizontal scroll
- Reflow at 320px viewport
- Text spacing applied (line height, letter spacing) - no content cut off
- Motion can be reduced (
prefers-reduced-motion honored)
Stage 5: Cognitive accessibility
Often overlooked. Critical for inclusive products.
Test:
- Reading level appropriate
- Instructions clear
- Error messages explain how to fix the error, not just that one occurred
- Forms allow correction before submission
- Time limits avoidable or extendable
- Important content not dependent on memory of prior pages
Workflow
- Define scope. Full site? Specific flows? Specific page templates?
- Run automated scans. Document findings per page.
- Manual keyboard pass. Test all priority flows.
- Screen reader pass. Test with at least one combination.
- Visual checks. Contrast, zoom, color blindness, motion.
- Cognitive checks. Reading level, error handling, time limits.
- Score against WCAG. Per success criterion (level A, AA, AAA).
- Prioritize findings. Critical (blocks users), Important (degrades experience), Minor (polish).
- Write the report. Use the template in
references/audit-report-template.md.
- Build a remediation plan. Sequenced fixes with effort and impact estimates.
Severity classification
For prioritization:
Critical (P0):
- Blocks an entire user flow for an assistive-tech user
- Renders a key page completely inaccessible
- Examples: form with no labels, modal without focus management, primary CTA not keyboard-accessible
Important (P1):
- Significantly degrades the experience for assistive-tech users
- Examples: missing alt text on key images, low-contrast body text, error messages that don't announce
Minor (P2):
- Affects edge cases or specific assistive technology combinations
- Examples: minor focus order issues, missing decorative alt attributes, edge case keyboard handling
Polish (P3):
- Above-AA improvements that benefit accessibility but aren't compliance-blocking
- Examples: AAA contrast targets, additional reduced-motion variants, language attributes on inline foreign words
Failure patterns
- Automated scan only. Catches 30 to 50 percent of issues. The remaining 50 to 70 percent are in keyboard, screen reader, and cognitive testing.
- Testing only on the home page. The home page is usually the most accessible. Bugs hide in deeper flows.
- Treating accessibility as a one-time project. Accessibility erodes with every deploy. Bake it into the development cycle.
- Fixing without root cause. Patching individual issues without understanding why they happened means new ones keep appearing.
- Ignoring screen reader testing. Hard to do well, easy to skip. Single biggest source of "we thought we were accessible" surprises.
- Confusing AA and AAA. AAA is rarely the right target. AA is the practical baseline for most products.
- Treating accessibility as a designer or developer responsibility alone. Content, product, QA, and leadership all need to participate.
- Assuming compliance equals accessibility. WCAG conformance is a floor, not a ceiling. Real users may still struggle.
Output format
Default output is a comprehensive audit report at accessibility-audit.md.
Structure:
- Executive summary
- Methodology (tools used, pages tested, screen readers used)
- Findings by WCAG principle
- Critical findings (P0) with specific URLs and fixes
- Important findings (P1)
- Minor findings (P2)
- Polish (P3)
- Remediation roadmap (sequenced and prioritized)
- Appendices (full automated scan results, keyboard navigation notes, screen reader notes)
Plus a remediation tracking spreadsheet with one row per finding.
Reference files
references/audit-report-template.md - Full audit report template.references/wcag-quick-reference.md - Condensed WCAG 2.1 AA criteria with audit checks.references/aria-patterns.md - Decision-grade ARIA patterns. Semantic-HTML-first principle, common interactive widgets (accordion, tabs, modal, toggle, disclosure, navigation), live regions, hiding patterns, labeling, state indicators, anti-patterns.
1---2name: accessibility-audit-43description: Run a comprehensive WCAG accessibility audit covering perceivable, operable, understandable, and robust principles. Use this skill whenever the user wants to audit accessibility, review WCAG compliance, fix accessibility issues, prepare for accessibility certification, address an accessibility lawsuit risk, or systematically improve a site's accessibility. Triggers on accessibility audit, WCAG audit, a11y audit, accessibility compliance, ADA compliance, screen reader test, keyboard navigation, accessibility report, fix accessibility, axe scan. Also triggers when accessibility issues have been reported and need systematic remediation.4---5
6# Accessibility Audit
7
8Run a thorough accessibility audit and produce a remediation plan. Stack-agnostic. Anchored to WCAG 2.1 AA, with notes on AAA where relevant.
9
10This skill goes deeper than the accessibility checks in `qa-testing` and `design-standards`. Use this when accessibility itself is the goal.
11
12---
13
14## When to use
15
16- Pre-launch accessibility verification
17- Compliance preparation (ADA, EN 301 549, AODA, Section 508)
18- Remediation after an audit finding or complaint
19- Annual or quarterly accessibility health check
20- Onboarding accessibility into a team that hasn't prioritized it before
21
22## When NOT to use
23
24- General QA after deploys (use `qa-testing`)
25- Component-level accessibility implementation (use `frontend-component-build`)
26- Color contrast for design tokens (use `design-standards` or `brand-identity`)
27
28---
29
30## Required inputs
31
32- The site or product under audit
33- The scope (full site, specific section, specific user flow)
34- The target standard (WCAG 2.1 AA is most common)
35- Any specific concerns or known issues
36- Tools available (automated scanners, screen readers, manual testing)
37
38---
39
40## The framework: WCAG's 4 principles
41
42WCAG organizes accessibility around four principles. The audit covers each in depth.
43
44### 1. Perceivable
45
46Information and UI must be presentable in ways users can perceive.
47
48**Audit checks:**
49
50- **Text alternatives.** All non-decorative images have descriptive `alt` text. Decorative images use `alt=""`. Complex images (charts, infographics) have long descriptions.
51- **Time-based media.** Videos have captions. Pre-recorded audio has transcripts. Live audio has live captions where required.
52- **Adaptable.** Content structure is conveyed through markup (semantic HTML), not just visual styling. Reading order makes sense when CSS is disabled.
53- **Distinguishable.** Color is not the sole means of conveying information. Text contrast meets AA (4.5:1 normal, 3:1 large). UI element contrast meets 3:1. Audio can be paused, stopped, or muted.
54
55### 2. Operable
56
57UI components and navigation must be operable.
58
59**Audit checks:**
60
61- **Keyboard accessible.** All functionality available via keyboard alone. No keyboard traps. Focus visible.
62- **Enough time.** Time limits can be adjusted, paused, or extended. Auto-updating content can be paused.
63- **Seizures and physical reactions.** No content that flashes more than 3 times per second.
64- **Navigable.** Skip links present. Pages have descriptive titles. Focus order is logical. Link purpose clear from text or context. Multiple ways to find pages (sitemap, search, navigation). Headings and labels are descriptive.
65- **Input modalities.** Pointer gestures have keyboard alternatives. Pointer cancellation supported (mouse-up, not mouse-down for activation). Labels match accessible names. Motion-triggered functionality has alternatives.
66
67### 3. Understandable
68
69Information and operation must be understandable.
70
71**Audit checks:**
72
73- **Readable.** Page language declared (`<html lang="...">`). Unusual words and abbreviations have definitions or expansions. Reading level appropriate to audience.
74- **Predictable.** Focus does not change context unexpectedly. Input does not change context unexpectedly. Navigation is consistent across pages. Components that look similar behave similarly.
75- **Input assistance.** Errors are identified clearly. Labels and instructions are provided for input. Error suggestions are given where possible. For pages handling legal commitments or financial transactions, errors can be reviewed and corrected before submission.
76
77### 4. Robust
78
79Content must be robust enough to work with current and future user agents.
80
81**Audit checks:**
82
83- **Compatible.** Markup is valid. Name, role, and value of UI components are programmatically determinable. Status messages can be programmatically determined and announced.
84
85---
86
87## Audit methodology
88
89### Stage 1: Automated scan
90
91Run automated scanners across the priority pages. These catch 30 to 50 percent of issues but miss the rest.
92
93**Tools:**
94- axe DevTools (browser extension)
95- Lighthouse (Chrome DevTools accessibility audit)
96- WAVE (browser extension)
97- Pa11y (CLI for batch scanning)
98
99**Output:** A list of automated findings, by page.
100
101### Stage 2: Manual keyboard testing
102
103Unplug the mouse. Navigate the priority user flows using only keyboard.
104
105**Test:**
106- Tab and Shift+Tab move through interactive elements in logical order
107- Enter activates buttons and links
108- Space activates buttons (and toggles checkboxes)
109- Arrow keys navigate within composite widgets (tabs, menus, listboxes)
110- Escape dismisses modals, popovers, menus
111- Focus is always visible
112- Focus returns to a sensible place after modals or popovers close
113- No keyboard trap (focus can always leave)
114
115**Document:** Any flow where keyboard navigation breaks down.
116
117### Stage 3: Screen reader testing
118
119Test with at least one real screen reader. Each combination has quirks.
120
121**Common combinations:**
122- VoiceOver + Safari (macOS / iOS)
123- NVDA + Firefox or Chrome (Windows)
124- JAWS + Chrome (Windows; commercial but common in enterprise)
125- TalkBack + Chrome (Android)
126
127**Test:**
128- Page structure announced correctly (headings, landmarks)
129- Form labels read with their inputs
130- Errors announced when they appear
131- Status changes announced (loading, success, error)
132- Modal context announced when opened
133- Images have meaningful alt text (or are correctly identified as decorative)
134
135### Stage 4: Visual testing
136
137Verify the visual aspects of accessibility.
138
139**Test:**
140- Color contrast for all text/background pairs (use a contrast checker)
141- UI element contrast (3:1 for icons, borders, focus rings)
142- Color-blindness simulation (deuteranopia at minimum)
143- Zoom to 200% - content remains usable, no horizontal scroll
144- Reflow at 320px viewport
145- Text spacing applied (line height, letter spacing) - no content cut off
146- Motion can be reduced (`prefers-reduced-motion` honored)
147
148### Stage 5: Cognitive accessibility
149
150Often overlooked. Critical for inclusive products.
151
152**Test:**
153- Reading level appropriate
154- Instructions clear
155- Error messages explain how to fix the error, not just that one occurred
156- Forms allow correction before submission
157- Time limits avoidable or extendable
158- Important content not dependent on memory of prior pages
159
160---
161
162## Workflow
163
1641. **Define scope.** Full site? Specific flows? Specific page templates?
1652. **Run automated scans.** Document findings per page.
1663. **Manual keyboard pass.** Test all priority flows.
1674. **Screen reader pass.** Test with at least one combination.
1685. **Visual checks.** Contrast, zoom, color blindness, motion.
1696. **Cognitive checks.** Reading level, error handling, time limits.
1707. **Score against WCAG.** Per success criterion (level A, AA, AAA).
1718. **Prioritize findings.** Critical (blocks users), Important (degrades experience), Minor (polish).
1729. **Write the report.** Use the template in [`references/audit-report-template.md`](references/audit-report-template.md).
17310. **Build a remediation plan.** Sequenced fixes with effort and impact estimates.
174
175---
176
177## Severity classification
178
179For prioritization:
180
181**Critical (P0):**
182- Blocks an entire user flow for an assistive-tech user
183- Renders a key page completely inaccessible
184- Examples: form with no labels, modal without focus management, primary CTA not keyboard-accessible
185
186**Important (P1):**
187- Significantly degrades the experience for assistive-tech users
188- Examples: missing alt text on key images, low-contrast body text, error messages that don't announce
189
190**Minor (P2):**
191- Affects edge cases or specific assistive technology combinations
192- Examples: minor focus order issues, missing decorative alt attributes, edge case keyboard handling
193
194**Polish (P3):**
195- Above-AA improvements that benefit accessibility but aren't compliance-blocking
196- Examples: AAA contrast targets, additional reduced-motion variants, language attributes on inline foreign words
197
198---
199
200## Failure patterns
201
202- **Automated scan only.** Catches 30 to 50 percent of issues. The remaining 50 to 70 percent are in keyboard, screen reader, and cognitive testing.
203- **Testing only on the home page.** The home page is usually the most accessible. Bugs hide in deeper flows.
204- **Treating accessibility as a one-time project.** Accessibility erodes with every deploy. Bake it into the development cycle.
205- **Fixing without root cause.** Patching individual issues without understanding why they happened means new ones keep appearing.
206- **Ignoring screen reader testing.** Hard to do well, easy to skip. Single biggest source of "we thought we were accessible" surprises.
207- **Confusing AA and AAA.** AAA is rarely the right target. AA is the practical baseline for most products.
208- **Treating accessibility as a designer or developer responsibility alone.** Content, product, QA, and leadership all need to participate.
209- **Assuming compliance equals accessibility.** WCAG conformance is a floor, not a ceiling. Real users may still struggle.
210
211---
212
213## Output format
214
215Default output is a comprehensive audit report at `accessibility-audit.md`.
216
217Structure:
2181. Executive summary
2192. Methodology (tools used, pages tested, screen readers used)
2203. Findings by WCAG principle
2214. Critical findings (P0) with specific URLs and fixes
2225. Important findings (P1)
2236. Minor findings (P2)
2247. Polish (P3)
2258. Remediation roadmap (sequenced and prioritized)
2269. Appendices (full automated scan results, keyboard navigation notes, screen reader notes)
227
228Plus a remediation tracking spreadsheet with one row per finding.
229
230---
231
232## Reference files
233
234- [`references/audit-report-template.md`](references/audit-report-template.md) - Full audit report template.
235- [`references/wcag-quick-reference.md`](references/wcag-quick-reference.md) - Condensed WCAG 2.1 AA criteria with audit checks.
236- [`references/aria-patterns.md`](references/aria-patterns.md) - Decision-grade ARIA patterns. Semantic-HTML-first principle, common interactive widgets (accordion, tabs, modal, toggle, disclosure, navigation), live regions, hiding patterns, labeling, state indicators, anti-patterns.
majiayu000