Accessibility review

Accessibility review

A structured accessibility review against WCAG 2.2, Level A and AA — the conformance target most teams and regulations aim for. Works on any web UI regardless of framework (plain HTML, React, Vue, Svelte, Astro, web components, etc.).

How to run a review

1. Triage — figure out which criteria even apply. Look at what the code renders: images? forms? links? custom widgets built from <div>s? color-coded states? drag interactions? A static paragraph engages almost nothing; a custom dropdown engages a dozen criteria. Don't run every check on every element — match checks to what's actually there.
2. Open the checklist for the applicable criteria. reference/wcag-checklist.md is the full per-criterion guide (grouped Perceivable / Operable / Understandable / Robust). Each entry has what it requires → common failures → how to check → the fix + a code example. Read the entries that apply; skip the rest.
3. Verify, don't eyeball. For anything measurable — contrast ratios, target sizes, keyboard reachability, zoom/reflow — follow reference/verification-guide.md. It has the actual contrast-ratio math (including the opacity trap), the keyboard/screen-reader walkthroughs, and the multi-theme rule. A guessed contrast ratio is not a finding.
4. Report findings and fix them (output format below).

Golden rules (apply throughout)

• A finding must be a direct, clear violation of a specific criterion. Cite the SC number. Don't report vague "could be more accessible" opinions or general code-style issues — that noise buries the real violations. If it doesn't clearly break a criterion, leave it out.
• Semantic HTML first; ARIA is the last resort. A native <button>, <a href>, <label>, <nav>, <h2>, or <input type> carries role, state, and keyboard behavior for free. Reach for ARIA only when no native element does the job. Incorrect or redundant ARIA is worse than none — role="button" on a real <button>, or aria-label that fights the visible text, actively breaks assistive tech. Prefer removing a <div onclick> in favor of a <button> over bolting ARIA onto the <div>.
• Trust well-implemented component libraries. Established, accessible libraries (the platform's own design system, mature UI kits) are accessible when used as documented. Don't re-audit their internals — only flag them when they're clearly misused against a criterion.
• Verify in every theme/mode the UI ships. Light, dark, high-contrast — the palette changes, so a contrast pass in one is not a pass in another. Same for RTL layouts and zoom states.
• Always give the fix, not just the finding. Every reported violation gets a concrete remediation — the corrected markup/CSS/handler, not "add a label."

Output format

Group findings by severity, then list each as:

• [SC number + name] — file:line
• What's wrong: the specific violation (what a user with a disability can't do).
• Fix: the concrete change, with a corrected code snippet.

Severity: Blocker (a whole task is impossible for some users — no keyboard access, unlabeled control, form with no error text) → Serious (usable but degraded — low contrast, poor focus order) → Minor (edge cases, enhancements toward AA robustness). If a criterion has no violation, don't mention it. End with a one-line note that any color/contrast fix must be re-verified in every theme via the real ratio, not by eye.

Scope notes

• Target is A + AA. AAA criteria (e.g. 7:1 contrast, 44×44 enhanced target size) are noted in the checklist as optional enhancements, not requirements — offer them, don't fail on them.
• This reviews the code's accessibility. It is not a general code review — stay on accessibility.
• WCAG 2.2 removed the old 4.1.1 Parsing criterion (obsolete); it is intentionally absent.
• Staleness check (do this once, not every run). This skill targets WCAG 2.2, a stable W3C Recommendation. Don't burn tokens re-researching it on every invocation — it changes on the order of years. But WCAG 3.0 is in development, so if a long time has clearly passed, do a quick check that 2.2 is still the current standard before trusting an exact threshold or criterion number, and refresh the checklist/verification-guide if it isn't. When in genuine doubt about a specific criterion, the authoritative source is w3.org/WAI/WCAG22/quickref.