accessible-website-check

# Accessible Website Check Audit a web project for accessibility issues against the TeachAccess design and code checklists, propose a prioritized remediation plan in plan mode, and implement the plan after user approval. ## When to Use Run when the user asks to: - "Check accessibility" / "audit a11y" / "make this accessible" - Improve WCAG compliance, keyboard navigation, screen reader support - Fix color contrast, alt text, ARIA labels, focus indicators, form labels - Review a website or web component before launch ## Workflow 1. **Identify scope** — Determine which files/pages/components to audit. If unclear, scan the project root for `index.html`, `src/`, `pages/`, `components/`, or framework markers (React/Vue/Svelte/Astro/Next). 2. **Enter plan mode** — Use `EnterPlanMode` before investigating. All investigation is read-only and happens inside plan mode. 3. **Investigate** — Walk the codebase systematically against both checklists below. For each finding, capture: file path, line number, the checklist item it violates, severity (blocker/major/minor), and the concrete fix. 4. **Write the plan** — Group findings by checklist item. Prioritize blockers (keyboard traps, missing alt text on meaningful images, contrast failures on body text) above minor issues. Include a verification step. 5. **Exit plan mode for approval** — Use `ExitPlanMode`. The user reviews and approves. 6. **Implement** — After approval, apply fixes in priority order. Test each change. Run any available linters/a11y tools (see Tooling). 7. **Verify** — Re-run through the checklists on changed files. Report what was fixed and any items deferred. ## Design Checklist Source: https://teachaccess.github.io/tutorial/design/checklist - [ ] Sufficient contrast between text and background (WCAG AA: 4.5:1 normal, 3:1 large) - [ ] Sufficient contrast between UI elements (borders, icons, focus rings) and background (3:1) - [ ] No information conveyed by color alone — always pair with text, icon, or pattern - [ ] Written content is simple and easy to understand (plain language, short sentences) - [ ] No flashing/flickering content (>3 flashes/sec is a seizure risk) - [ ] Every mouse interaction has a keyboard-only equivalent - [ ] Captions included with any audio or audio/visual media - [ ] Timed responses / session timeouts are clearly communicated and extendable ## Code Checklist Source: https://teachaccess.github.io/tutorial/code/checklist - [ ] All images have meaningful `alt` text (decorative images use `alt=""`) - [ ] Every focusable element is operable by keyboard alone (Tab, Enter, Space, arrow keys where appropriate) - [ ] Consistent visible focus indicator when navigating by keyboard (no `outline: none` without replacement) - [ ] All controls, frames, and page titles are labeled meaningfully and uniquely (`<label>`, `aria-label`, `aria-labelledby`, `<title>`) - [ ] Custom controls expose correct name, role, state, value to assistive tech (ARIA roles/states match WAI-ARIA Authoring Practices) - [ ] Custom components verified with a screen reader (VoiceOver, NVDA, JAWS) - [ ] Error messages are interpretable by assistive tech (`aria-describedby`, `role="alert"`, `aria-invalid`) - [ ] Sufficient foreground/background contrast (re-check in code, not just design) - [ ] Captions on audio/video media (`<track kind="captions">`) ## Common Issues to Grep For | Pattern | Likely issue | |---|---| | `<img` without `alt=` | Missing alt text | | `outline: none`, `outline: 0` | Removed focus indicator | | `<div onClick`, `<span onClick` | Non-semantic interactive element (use `<button>`) | | `<a href="#"` or `<a>` without `href` | Non-navigable link (use `<button>`) | | `<input` without associated `<label>` | Unlabeled form field | | `tabindex="-1"` on interactive content, `tabindex` > 0 | Keyboard order issues | | `role="button"` without `onKeyDown` for Enter/Space | Missing keyboard handler | | `placeholder=` used as label | Placeholder is not a label | | `aria-hidden="true"` on focusable element | Hidden from AT but reachable | | Color-only state (`color: red` for error, no icon/text) | Color-only meaning | | `<h1>` skipping to `<h3>` | Broken heading hierarchy | | `<table>` without `<th>` / `scope` | Inaccessible data table | | `autoplay` on `<video>` / `<audio>` | Unexpected motion/sound | ## Tooling (suggest to user; do not auto-install) - **axe-core** / **@axe-core/cli** — automated rule checks - **Pa11y** — CLI a11y testing - **Lighthouse** (Chrome DevTools) — bundled a11y audit - **WAVE** browser extension — visual report - **eslint-plugin-jsx-a11y** — React/JSX lint rules - Screen readers: **VoiceOver** (macOS, built in), **NVDA** (Windows, free) If the project already has one of these configured, run it during the Verify step. ## Plan Format When exiting plan mode, structure the plan as: ``` ## Accessibility Audit — Findings ### Blockers (must fix) - [file:line] <issue> — <fix> ### Major - [file:line] <issue> — <fix> ### Minor / polish - [file:line] <issue> — <fix> ### Out of scope / deferred - <item> — <reason> ### Verification - <tool/command/manual step> ``` ## Common Mistakes - **Skipping plan mode** — User explicitly wants to approve before fixes land. Always `EnterPlanMode` first. - **Auto-installing a11y tooling** — Suggest, don't install, unless the user agrees. - **Adding ARIA where semantic HTML works** — `<button>` beats `<div role="button">`. First rule of ARIA: don't use ARIA. - **Removing `outline` without a replacement** — Every focus-removal needs a custom `:focus-visible` style. - **Treating contrast at design layer only** — Re-check final rendered colors, including hover/disabled states. - **Decorative vs meaningful images** — Not every image needs descriptive alt; purely decorative images need `alt=""` (empty, not missing). - **Claiming "done" without screen-reader verification** for custom widgets — note explicitly when manual AT testing is deferred to the user.