| name | a11y-check |
| description | Accessibility audit against WCAG 2.1 AA. Checks semantic HTML, ARIA, keyboard navigation, color contrast, screen reader compatibility. |
Accessibility Audit
Evaluate user-facing work against WCAG 2.1 AA. Accessibility is a design constraint, not a polish step (Downe Principle 11).
WCAG 2.1 AA Checklist by Principle
1. Perceivable
2. Operable
3. Understandable
4. Robust
Automated Testing Tools (by stack)
| Stack | Tool | Command |
|---|
| React/Web | axe-core | npx axe <url> or axe-core in tests |
| Any web | Lighthouse | npx lighthouse <url> --only-categories=accessibility |
| Any web | pa11y | npx pa11y <url> |
| CI/CD | axe-linter | Add to CI pipeline |
Common Violations and Fixes
| Violation | Fix |
|---|
| Missing alt text | Add descriptive alt or alt="" for decorative |
| Low color contrast | Increase contrast ratio to 4.5:1 minimum |
| Missing form labels | Add <label for="id"> or aria-label |
| No focus indicator | Add :focus-visible styles, never outline: none |
| Non-semantic buttons | Use <button> not <div onclick> |
| Missing heading hierarchy | Use h1-h6 in order, don't skip levels |
| Auto-playing media | Add pause/stop controls, respect prefers-reduced-motion |
When to Run
- During development: after every UI component
- Before PR: full automated scan
- Before release: manual screen reader test of critical journeys
- After design changes: re-audit affected components