# Accessibility Review

> Review, audit, or fix the accessibility of web UI — HTML, CSS, JS/JSX, or any component that renders a visible or interactive surface. Use when the user asks to check accessibility / a11y / WCAG / ARIA compliance, or mentions screen readers, keyboard navigation, color contrast, focus management, or making something usable for people with disabilities. Covers ~30 WCAG 2.2 Level A & AA success criteria with detection and remediation guidance.

- Skill: `prostdev/accessibility-review` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add prostdev/accessibility-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prostdev/accessibility-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ProstDev (https://skillmd.com/u/prostdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prostdev/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 *mis*used 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](https://www.w3.org/WAI/WCAG22/quickref/).