Accessibility Checker

---
name: accessibility-checker
description: |
  Trigger when the user asks to audit accessibility, check WCAG compliance,
  find a11y issues, or improve screen-reader support. Phrases: "a11y audit",
  "accessibility check", "WCAG", "screen reader", "aria", "keyboard nav".
allowed-tools:
  - Bash(npx axe-core *)
  - Bash(npx pa11y *)
  - Read
  - Grep
  - Glob
---

# Accessibility Checker

Run a deterministic a11y audit on the repo's rendered pages and surface issues
ranked by WCAG severity. Pairs automated tool output with hand-reviewed fixes
grouped by component.

## Prerequisites

- App runs locally on a known port (default http://localhost:3000)
- `axe-core` or `pa11y` available via npx
- Node 18+

## Steps

1. **Discover routes.** Grep the app directory for page/route files. For a
   Next.js app read `app/**/page.tsx` and `pages/**/*.tsx`. For other
   frameworks find the router config.

2. **Run axe-core headless** against each route:

   ```bash
   npx axe-core --browser chromium http://localhost:3000/<route>
   ```

   Output is JSON. Parse it and bucket issues by:
   - Impact (critical, serious, moderate, minor)
   - Rule ID (color-contrast, aria-required-attr, etc.)
   - Which component renders the offending node

3. **Review results alongside source.** For every rule violation, open the
   component file and propose a minimal fix. Prefer semantic HTML changes
   over ARIA patches.

4. **Produce a three-section report:**
   - Critical issues (block release)
   - Serious issues (fix this sprint)
   - Moderate/minor (backlog)

   Each issue includes file:line, the rule, and the proposed patch.

## Common rules worth fixing first

- `color-contrast`: body text under 4.5:1 against background.
- `button-name`: `<button>` without text or `aria-label`.
- `image-alt`: `<img>` missing `alt`. Decorative images should set `alt=""`.
- `label`: form inputs without associated labels.
- `landmark-one-main`: page missing `<main>`.
- `heading-order`: skipped heading levels (h1 -> h3).

## Output

Write the full report to `a11y-report.md` at repo root. Include axe version,
timestamp, and route list. Follow up with a PR that addresses the critical
and serious buckets.