agentleFS
SocialGouvSocialGouv/ultra11y/skills/review-a11y/SKILL.md

review-a11y

Skill5 starsChanged 4 months agoMITView on GitHub

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.

  • Commits and pushes

2 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 1

    1. stritar/skills★ 099% same

    Wrote their own version · 1

    1. gtrabanco/agentic-workflow★ 23same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repositoryOne other file it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Engine resolution: every command below is node scripts/ultra11y.mjs … where scripts/ultra11y.mjs lives next to this SKILL.md (the engine …

    line 20
  2. Very specific:

    Always pass --graph for JSX/TSX (real AST + cross-file rules: icon-only component used without a name, anchor target defined in another …

    line 54
  3. Very specific:

    Test/story markup (*.test.*, *.stories.*, __tests__/) is excluded by default.

    line 60
  4. Very specific:

    Keep the engine's remediation text as the base of each fix — it is already localized and criterion-grounded.

    line 107

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 »).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.