Accessibility Audit

---
name: a11y-audit
description: |
  Trigger when the user asks to audit accessibility, check WCAG compliance,
  run a screen reader test, or verify keyboard navigation. Phrases: "a11y
  audit", "accessibility audit", "WCAG", "screen reader", "keyboard nav".
allowed-tools:
  - Read
  - Bash(npx axe *)
  - Bash(npx pa11y *)
  - Bash(npx lighthouse *)
  - Grep
  - Glob
---

# Accessibility Audit

Run a full WCAG 2.2 AA audit against a web UI. Cover the four pillars:
perceivable, operable, understandable, robust. Output a prioritized fix list
that engineers can work through without guesswork.

## Prerequisites

- App is running locally or a deployed URL is available
- Node + npx available for tooling (axe-core, pa11y, lighthouse)
- Target WCAG level agreed (AA is the default for most orgs)

## Steps

1. **Automated scan first.** Run the fast tools to catch the easy issues:
   ```bash
   npx @axe-core/cli http://localhost:3000 --save axe-report.json
   npx pa11y http://localhost:3000 --reporter json > pa11y-report.json
   npx lighthouse http://localhost:3000 --only-categories=accessibility \
     --output=json --output-path=lh-a11y.json
   ```
   Automated tools catch roughly 30 - 40% of issues. Useful for color
   contrast, missing alt text, form labels, landmark structure.

2. **Keyboard-only pass.** Unplug the mouse. Tab through every screen:
   - Is focus always visible?
   - Does tab order match visual order?
   - Can every interactive element be reached and activated?
   - Are modal traps correct? (focus stays in modal, Escape closes)
   - No keyboard traps anywhere on the page.

3. **Screen reader pass.** Use VoiceOver (macOS) or NVDA (Windows):
   - Page has one h1
   - Heading hierarchy is logical (no skipped levels)
   - Landmarks (main, nav, footer) are present
   - Images have meaningful alt text (or alt="" if decorative)
   - Form fields have labels, errors are announced, required marked
   - Dynamic content updates fire live regions (aria-live)

4. **Color + contrast pass.**
   - Text: 4.5:1 minimum for normal, 3:1 for large (18pt+ or 14pt bold)
   - UI components + graphics: 3:1 minimum
   - Do not rely on color alone to convey information

5. **Zoom + reflow.** Test at 200% zoom and at 320px viewport. Content
   should reflow without horizontal scroll or clipped content.

6. **Write the report.** Group findings by severity:
   - **Blocker:** prevents use (keyboard trap, missing label on required field)
   - **Major:** significant barrier (poor contrast, missing landmarks)
   - **Minor:** polish (redundant alt text, non-ideal heading levels)

## Common gotchas

- Div buttons without role="button" + keyboard handlers
- Custom selects that are invisible to screen readers
- Placeholder-only labels (disappear on input)
- Icons without accessible names (aria-label or sr-only text)
- Autoplay media with no pause control

## Output

- Prioritized fix list with file references and proposed code changes
- Before/after axe + lighthouse scores
- Manual testing checklist covering keyboard, screen reader, zoom
- Regression test plan so issues do not come back