Accessibility Audit

---
name: accessibility-audit
description: Audit a web UI for accessibility problems and fix them. Use when asked to check or improve a11y, keyboard support, screen reader behavior, or WCAG compliance.
---

# Accessibility Audit

Test like a user who cannot use a mouse or see the screen.

## Manual checks (do these, automated tools miss most issues)

1. **Keyboard only.** Unplug the mouse mentally: Tab through the page. Can you reach every interactive element? Can you see where focus is? Can you escape modals with Esc and does focus return to the trigger? Is tab order logical?
2. **Semantic structure.** One `<h1>`, headings in order, landmarks (`main`, `nav`, `header`). Buttons are `<button>`, links are `<a>` — not clickable divs.
3. **Forms.** Every input has a visible `<label>` (not placeholder-only). Errors are announced and tied to fields with `aria-describedby`.
4. **Images.** Informative images have alt text; decorative ones have `alt=""`. Never alt="image.png".
5. **Contrast.** Text ≥ 4.5:1 (large text ≥ 3:1) against its background — check muted/secondary text especially.
6. **Motion.** Animations respect `prefers-reduced-motion`.
7. **Dynamic content.** Toasts, validation messages, and route changes are announced (aria-live / focus management).

## Automated pass

- `npx axe <url>` or the axe DevTools extension — fix every violation it finds, then do the manual pass anyway.
- `npx lighthouse <url> --only-categories=accessibility`

## Fixing rules

- Prefer native HTML over ARIA. A `<button>` beats `<div role="button" tabindex="0">` every time.
- Never use positive `tabindex` values.
- Do not hide focus outlines without a visible replacement.

## Output

Per issue: what is broken → who it blocks and how → the fix (with the element/code change) → how to verify. Group by severity: blockers (task impossible), major (task painful), minor (polish).