review-a11y

---
name: review-a11y
description: Use to REVIEW changed frontend code for accessibility: staged files, a working diff, branch, or PR; prompts such as 'review a11y', 'is this accessible?', or 'anything to fix before merge?'; and hook or CI findings on a change. Run the bundled install-free engine with cross-file JSX/TSX analysis, then adjudicate candidates and return a severity-ranked WCAG 2.2 AA review with file:line fixes, residual rendering risks, and a verdict. Use `ultra11y` instead for whole-repo audits, dated conformance reports, country standards, PRD backlogs, or authoring accessible markup.
license: MIT
---

# review-a11y — accessibility review of changed code

The review counterpart of the `ultra11y` skill: where `ultra11y` produces full audits and
compliance deliverables, **this skill reviews exactly the code under change** — a diff, a
branch, a PR — and reports like a code reviewer. Same division of labour: the
deterministic, install-free engine bundled with this skill does the *mechanical* work
(machine-checkable WCAG 2.2 AA non-conformities, each tied to a success criterion, cited
`file:line`), and **the AI agent** *adjudicates the judgment* — refute false positives, decide
alt relevance/link purpose/focus logic statically from the code, and route what needs a rendered
DOM to `scan`. A human is at most optional oversight.

**Engine resolution:** every command below is `node scripts/ultra11y.mjs …` where
`scripts/ultra11y.mjs` lives **next to this SKILL.md** (the engine ships inside the skill;
no install, no key). Run it with the reviewed project as the working directory. In the
ultra11y repository itself, the repo root's `scripts/ultra11y.mjs` is the same file.
On Claude Code that path is `${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs`; on Codex and
OpenCode it is the skill directory the plugin installed. If neither resolves — a harness
with no skill system — `npx -y ultra11y <command>` is the same engine. Per-harness deltas:
`references/harnesses.md` in the `ultra11y` skill.

> **Core rules** (shared with `ultra11y`):
> 1. **Never invent a non-conformity**: report only what the engine found or what you can
>    see and cite in the code under review.
> 2. **Review the change, not the world**: findings outside the reviewed scope are noted in
>    one line at most ("pre-existing, out of scope"), never mixed into the verdict.
> 3. **Residual is explicit, never silently conforming**: the *rendering* criteria (contrast,
>    focus visibility, zoom/reflow, content-on-hover) are named as residual risks for the changed
>    components — never asserted from source, resolved in the rendered page (`scan`). The
>    *judgment* criteria (alt relevance, link purpose, reading order) the AI agent adjudicates
>    from the code itself, recording a reason — no status without a justified verdict.
> 4. **Language**: write the review in the conversation's language, but technical tokens
>    stay in English even in French prose — `aria-live` stays `aria-live` (never
>    « région live »), same for `tabindex`, `alt`, `role="alert"`, landmark role names.

## 1. Scope — review what changed

Pick the FIRST that applies (ask only when genuinely ambiguous):

```
node scripts/ultra11y.mjs audit <files the user named> --jsx --json     # explicit files
node scripts/ultra11y.mjs audit --staged --graph --json                 # staged snapshot (pre-commit review)
node scripts/ultra11y.mjs audit --changed --graph --json                # working diff
node scripts/ultra11y.mjs audit --since origin/main --graph --json     # the whole branch (PR review) — use the repo's default branch
```

- Always pass `--graph` for JSX/TSX (real AST + cross-file rules: icon-only component used
  without a name, anchor target defined in another file…); it also suppresses a class of
  single-file false positives.
- Pass `--lang` matching the conversation so the engine's message/remediation strings are
  in the review's language (unset, the CLI auto-detects — a fallback, not a substitute).
- Whole-repo review is an **audit**, not a review — offer the `ultra11y` skill instead.
- Test/story markup (`*.test.*`, `*.stories.*`, `__tests__/`) is excluded by default; name
  such a file explicitly to include it, or pass `--no-default-excludes`.

## 2. Judge — the engine's findings are candidates, not verdicts

For each finding (`--json` gives `criteria`, `severity`, `file:line`, `message`,
`remediation`):

- **Confirm the occurrence**: open the cited line; the offending element must really be
  there in the change under review.
- **`preliminary: true` findings** (`.vue`/`.svelte`/`.astro` source, library components):
  the template parser cannot see slots, conditionals or provide/inject wiring. Confirm
  against the rendered DOM if captures exist (`.ultra11y/captures`, from the `ultra11y`
  skill's `render --setup` harvester), otherwise report them as **provisional** with that
  caveat — or refute them with evidence from the code.
- **Library-rendered JSX (DSFR, MUI…)**: a clean source review can still ship broken HTML
  (false negatives) — say so explicitly when the change touches such components, and
  recommend a rendered-DOM check (`scan`, or the `ultra11y` capture pipeline).
- **The judgment criteria are the AI agent's to adjudicate**: alt text relevance, link purpose
  in context, visible label vs accessible name, keyboard/focus logic of the changed component
  (read the full component source, not just the flagged line), recording a reason for each call.
- Refuting a finding requires **cited evidence** (the code that disproves it); silently
  dropping findings is forbidden.

## 3. Report — a review, not a compliance document

Render in the conversation's language (Core rule 4), grouped by severity:

```
## Accessibility review — <scope, e.g. branch feat/x vs main, 12 files>

### 🔴 Blocking
- `src/components/Form.tsx:42` — **3.3.2 Labels or Instructions** — input has no
  label and placeholder is its only hint → associate a real <label for>, keep the
  placeholder as an example only.

### 🟠 Major / 🟡 Minor
- …same shape…

### Residual risks (rendering-dependent — resolve in the rendered page via scan)
- contrast of the new button variants (1.4.3), focus visibility on the custom menu (2.4.7)

### Verdict
1 blocking, 2 major to fix before merge; 2 provisional SFC findings to confirm on the
rendered DOM; residual risks listed above.
```

- Keep the engine's `remediation` text as the base of each fix — it is already localized
  and criterion-grounded.
- Pre-existing issues spotted in passing go in ONE final line, out of the verdict.

**Running as a subagent.** This skill is often dispatched rather than typed: by the plugin
hook on a pending `git commit` / `git push` / `gh pr create`, or by the `ultra11y` skill once
its audit has produced fixes. When it is, the report above **is** the return value — it
becomes a tool result for the caller, not a message to a human. So return it whole and
nothing else: no preamble, no "I ran the engine and found…", no offer to fix. A caller that
receives a summary has to guess at the findings, which is the one thing this skill exists to
stop. Everything in §4 stays opt-in and belongs to the caller, not to you.

## 4. After the review (opt-in)

- **Safe mechanical fixes**: `fix --staged --write --safe` (auto-applies the safe codemods
  to staged files and re-stages them) or `node scripts/ultra11y.mjs fix <files> --write`;
  dry-run without `--write`.
- **Formal deliverables** (dated report, auditor conformance blocks, PRD backlog, GitHub
  issues, RGAA/country-standard vocabulary): that is the `ultra11y` skill — same engine,
  same findings (`report`, `prd`, `check`/`verify` gates).
- **Make it automatic**: installed as a **Claude Code plugin**, a `PreToolUse` hook stops a
  pending `git commit` / `git push` / `gh pr create` that carries findings and hands them
  over — that is what invokes this skill without anyone asking. It never fires twice for the
  same findings, so a retry lands. For a gate that does not need an agent at all, the
  `ultra11y` skill's `init --hook` installs a mechanical pre-commit run of this same staged
  audit.

## Do not

- Invent a non-conformity the engine did not find and you cannot cite.
- Assert contrast/focus/zoom from source — they are residual risks until rendered (resolve via `scan`).
- Mix pre-existing repo issues into the verdict on the change.
- Translate technical tokens in French prose (`aria-live`, never « région live »).