Accessibility Skill

---
name: accessibility-review
description: Audit UI code for accessibility defects against WCAG. Use when building or changing components, forms, modals, or navigation, or when the user asks about accessibility, a11y, screen readers, or keyboard support.
---

# Accessibility Review

Judge the interface by whether a person can complete the task, not by whether an automated checker passes. Automated tools catch a minority of real barriers; the rest are found by walking the flow.

## Start with semantics

Most accessibility defects are one root cause: the wrong element. Check every interactive thing:
- A control that navigates is a link. A control that acts is a button. A `div` with a click handler is neither, and it is the single most common defect in generated UI.
- Form inputs have a real `<label>` associated with them, not placeholder text standing in for one.
- Headings are real headings in descending order with none skipped, because heading order is the main way screen reader users navigate a page.
- Lists are lists, tables have headers with scope, landmarks exist.

Reach for ARIA only when no native element expresses the meaning. A native element you did not use is a bug that ARIA cannot fully repair.

## Walk it with the keyboard

For each flow, in order:
1. Can every control be reached by Tab, in an order matching the visual order?
2. Is the focus indicator visible on every one, including on custom-styled controls?
3. Does each control operate with Enter or Space as its role implies?
4. Escape closes overlays, arrow keys move within composite widgets (menus, tabs, listboxes).
5. Focus moves into a dialog when it opens, is trapped inside while it is open, and returns to the trigger when it closes.
6. Nothing is reachable that should not be: hidden content, off-screen elements, and controls inside collapsed regions must be removed from the tab order, not just visually hidden.

## Check what a screen reader announces

- Icon-only buttons have an accessible name.
- Images have alt text that conveys the purpose, and decorative images have empty alt.
- State is programmatically exposed: expanded, selected, checked, current, disabled, invalid.
- Errors are associated with their field and announced, not only shown in red.
- Content that appears without a page change (validation messages, toasts, loading results) is announced through a live region.
- Nothing announces layout noise: no reading of styling elements or empty containers.

## Then check

- **Contrast**: text meets 4.5 to 1 (3 to 1 for large text), and interactive boundaries and focus indicators meet 3 to 1.
- **Color alone**: no meaning conveyed only by color.
- **Zoom and reflow**: usable at 200% text size and at 320 pixels wide with no horizontal scrolling.
- **Targets**: interactive areas large enough to hit reliably.
- **Motion**: animation respects reduced-motion preferences; nothing auto-plays or auto-advances without a control.
- **Time limits**: extendable, or absent.

## Report

Per finding: what is broken, `file:line`, **who it blocks and from doing what** (this is the sentence that gets it prioritized, not the rule number), the WCAG criterion, and the fix as code. Order by how completely it blocks a task, not by criterion number.

State plainly what you could not evaluate from code alone: actual contrast on rendered output, real screen reader behavior, and anything depending on runtime state. Recommend the manual check for each.