Save as .claude/skills/accessibility-review/SKILL.md in a repository, or under ~/.claude/skills/accessibility-review/SKILL.md to have it everywhere. The copy button takes the whole file, frontmatter included.

---
name: accessibility-review
description: Review an interface for accessibility problems that actually block people, ranked by impact rather than by rule. Use when asked to check accessibility, a11y, WCAG compliance, screen reader support, keyboard navigation or colour contrast.
---

# Accessibility review

An automated checker finds perhaps a third of real accessibility problems, and
most of what it finds is minor. The things that genuinely stop someone using a
page are mostly invisible to it.

Review for people, then check the rules.

## Order of review, by how badly it blocks someone

### 1. Can it be used with a keyboard alone
The highest impact check and the most commonly broken.

- Every interactive element reachable by Tab, in an order that matches the
  visual layout.
- A visible focus indicator on every one. Removing the outline without
  replacing it is a serious fault, not a style choice.
- No keyboard trap: focus can always move on. Modals are where this breaks.
- Escape closes anything that opened over the page, and focus returns to what
  opened it.
- Anything clickable is a `button` or `a`. A `div` with a click handler is
  invisible to a keyboard and to assistive technology.

### 2. Is the structure real
Assistive technology navigates by structure, so fake structure is unusable.

- One `h1`, then headings in order with no skipped levels. Headings chosen for
  size are a fault.
- Landmarks: `header`, `nav`, `main`, `footer`. One `main`.
- Lists marked up as lists, tables as tables with real header cells.
- The page has a `title` that says what the page is, and `html` has a `lang`.

### 3. Do controls say what they are
- Every input has a label that is programmatically associated, not merely
  positioned nearby. Placeholder text is not a label; it disappears.
- Buttons with only an icon have an accessible name.
- Link text means something out of context. A page of "click here" is a page
  of nothing when read as a list of links.
- Images: meaningful ones have alt text describing the content, decorative
  ones have empty `alt=""`. Alt text on a decorative image is noise, not a
  bonus.

### 4. Errors and state changes
- Errors say what is wrong and how to fix it, in text, next to the field.
- An error is announced, not only coloured red.
- Content that appears without a page load is announced, or focus moves to it.
- Required fields are marked in text as well as colour.

### 5. Colour and motion
- Contrast: at least 4.5:1 for normal text, 3:1 for large text and for the
  boundary of interactive components. Check the real rendered colours,
  including on hover and in dark mode.
- Colour never the only signal. Add a label, an icon or a pattern.
- Respect `prefers-reduced-motion` for anything that moves.
- Text reflows at 200% zoom without horizontal scrolling.

## What not to do

- **Do not add ARIA to fix bad markup.** A `button` needs no role. ARIA on
  top of the wrong element usually makes things worse, and no ARIA beats
  wrong ARIA.
- **Do not report automated output as a review.** Say which findings came from
  a tool and which from reasoning about use.
- **Do not claim compliance.** You can say which criteria appear met and which
  appear failed. Conformance needs testing with real assistive technology and
  real people.
- **Do not rank by rule number.** Rank by who is blocked and how badly.

## Report back

1. Blockers: things that make a task impossible for someone. These first,
   always.
2. Barriers: things that make it harder but not impossible.
3. Minor issues.
4. For each: what is wrong, who it affects, and the specific fix.
5. What you could not assess without a real screen reader or a real user.