Web accessibility (a11y) skills for Claude Code: audit a site for WCAG 2.2 conformance, scan a page with the rule engine, run hands-on keyboard and screen-reader checks, fix violations, and catch regressions in CI. Live-DOM audits auto-launch Chrome; no manual setup.

version
0.10.2
GitHub stars
122

Install

/plugin install accesslint@accesslint

Run it inside Claude Code after adding the marketplace with /plugin marketplace add AccessLint/skills.

Contents

Discovered from source

Skills 5

This is a full WCAG 2.2 accessibility audit using WCAG-EM. It defines scope, samples representative pages and flows, runs both evaluation tiers, and produces one conformance report:

  • Automated tier: accesslint:accessibility-scan (the rule engine).
  • Semi-automated manual tier: accesslint:accessibility-inspect (keyboard, focus, state, reflow, and the rest the engine can't decide).

Assess; don't fix (accesslint:accessibility-fix) or diff (accesslint:accessibility-diff). One page with no sampling is a accessibility-scan, not an audit. This skill delegates each sampled page to its own subagent (step 4), so it stays light on large samples.

The full doctrine — WCAG-EM in detail, the severity rubric with examples, the no-proxy boundary, grounding — is in ../shared/methodology.md. The rules needed to run this skill are below.

Grading

Each finding carries a severity and an evidence basis. Keep them separate.

  • Evidence basis: ● verified (deterministic, with cited proof) · ◐ flagged (evidence captured, a person decides) · ○ human-required (needs assistive technology or lived experience; handed off, not emulated).
  • Severity: critical (blocks a core task) · serious (major barrier) · moderate (friction, still completable) · minor (polish).

WCAG-EM steps

Run in order and state what you did at each.

  1. Scope. State the target and its boundary, the goal (default WCAG 2.2 AA; --level AAA adds AAA), the technologies in use, and the assistive-technology baseline the human handoff should cover. You scope that baseline; you don't test it.

  2. Explore. Use Glob/Grep to find routes, templates, and shared components. Note key flows, content types, and stateful UI (modals, wizards, empty and error states). accesslint.config.json targets are a starting point.

  3. Sample. Choose a structured set (entry page, each key flow end to end, every page with a new template or complex widget, and the important states) and a small random set. Say what's in each and why.

  4. Evaluate. Delegate each sampled page or state to its own Task so it runs in its own context and returns its findings; independent pages can run in parallel. Each Task:

    • runs accesslint:accessibility-scan (--format json) first, then accesslint:accessibility-inspect against the same rendered state — same URL, --selector, --wait-for — passing scan's results (or at least the list of SCs the engine covered) into the inspect run;
    • dedups by SC ownership before driving, not after: accessibility-scan owns rule-detectable criteria, accessibility-inspect owns interaction and judgment criteria; inspect never re-checks an engine-owned SC, and where both still cover the same SC at the same element, accessibility-scan's result wins;
    • returns a structured block: per finding, the SC, severity, evidence basis (●/◐/○), location, tier, evidence, and fix or handoff, plus this page's per-SC ledger (verified / flagged / engine-owned / N/A / not exercised).

    Aggregate the returned blocks in step 5. For a one- or two-page scope, run the tiers inline instead of spawning a Task.

    A shared browser is optional and improves selector matching across tiers, but it's a pre-wired precondition, not something this skill sets up at runtime: the browser MCP binds to its Chrome at server start (--autoConnect or --browser-url), with the engine pointed at the same port. Without it (the default), each Task runs both tiers against the same URL and --wait-for gate and dedups by SC ownership.

  5. Report. Aggregate into the format below. Conformance has three states: pass or fail only for ● findings; everything ◐ or ○ — and every SC no page exercised — is undetermined and goes to a human. One sampled page failing an SC fails it for the whole scope at that level. Don't report conformance you can't support, and don't let a not-exercised SC read as a pass. Keep the ledger to counts and bare SC lists — group undetermined SCs by shared reason, one clause per group — and spend the report's words on failures, flags, and handoffs: a pass is its SC number in the list, with at most one sentence of narration for the whole passing set.

Report format

# Accessibility audit — <product / scope>
WCAG 2.2 Level AA · WCAG-EM · <N> pages/states sampled

## Scope
- Target & boundary: <…>     Goal: WCAG 2.2 AA
- Technologies in use: <…>
- AT baseline (for the human handoff, not tested here): <SR+browser pairs, keyboard-only, …>

## Sample
- Structured: <page/state> — <why>   (×N)
- Random: <page/state>

## Conformance (per success criterion)
- Pass ●: <n>  ·  Fail ●: <n>  ·  Undetermined (◐/○/not exercised): <n>  ·  N/A: <n>
- Fail ●: <SCs>   Pass ●: <SCs>   N/A: <SCs>
- Undetermined: <SCs (shared reason)> · <SCs (shared reason)>
- Pass/fail is asserted only for ● criteria; ◐/○ and not-exercised are undetermined.

## Findings — by severity, tagged by evidence basis
### Critical
- [●] <barrier> — SC x.x.x — where: <selector / file:line> — tier: scan|inspect — → `accessibility-fix`
- [◐] <barrier> — SC x.x.x — evidence: <screenshot / measurement> — confirm: <what a person checks>
### Serious / Moderate / Minor
[same shape]

## Human-required (○) — the testing handoff
- <what only AT or lived experience reveals> — SC x.x.x
    needs: <functional ability + AT, per Section 508 FPC>   flow: <sampled flow>

## Recommendations
- Root-cause / pattern fixes (one change that clears many instances) → hand to `accessibility-fix`.
- What to send to human and AT testing, and on which flows.
- Wire `accesslint:accessibility-diff` into CI for the sampled targets.

Notes

  • Assess, don't fix (use accessibility-fix) or diff (use accessibility-diff). Don't emulate human experience: usability is ◐, lived experience is ○ and handed off.
  • Conformance is per SC across the whole sample. Don't average failures away.
  • Two browsers can drift selectors; prefer a shared browser for ●-precision, otherwise note that dedup is best-effort.
  • State what wasn't covered (pages outside the sample, ○ criteria). Omitting it reads as "all clear".
  • Use list_rules and explain_rule for engine-rule metadata.

Default branch: !git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null | sed 's|.*/||' || echo main

Report only what changed. Locate; don't fix.

Shared grounding and honesty conventions: ../shared/methodology.md.

Parse $ARGUMENTS: if --branch <name> is present, remove it and use branch mode (no value means the default branch above). The rest is the target: a URL, a config target name, or empty for the default target from accesslint.config.json. If it's empty and there's no config, ask for a URL.

1. Audit

PORT=$(npx -y @accesslint/chrome@latest ensure | node -e 'process.stdin.on("data",d=>process.stdout.write(""+JSON.parse(d).port))')

Stash mode (default; uncommitted changes). Tell the user first: "Running in diff mode — stashing your changes to capture a baseline, then restoring. Your working tree will be fully restored." If git stash push fails, warn and exit.

git stash push -u -m "accesslint-diff-baseline"
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --update-snapshot
git stash pop && sleep 2
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --format json

Branch mode (--branch <name>). Tell the user first: "Diffing against <name> — checking out that branch to capture a baseline, then restoring. Your working tree will be fully restored." Branch switching triggers a rebuild but not a browser reload, so the CLI opens a fresh tab each run to read the current build. Use --wait-for "<selector>" to hold the audit until the rebuild is ready; without it, warn that a slow build may give a stale baseline.

git diff --quiet && git diff --cached --quiet || git stash push -u -m "accesslint-diff-branch"
git checkout <branch>
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --update-snapshot [--wait-for "<selector>"]
git checkout - && git stash pop 2>/dev/null
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --format json [--wait-for "<selector>"]

Pass --selector and --include-aaa to both runs.

2. Report

Accessibility diff — http://localhost:3000/ vs main (94 rules, live DOM)
2 new · 1 fixed · 4 pre-existing hidden

New — Critical
- color-contrast — 2.1:1 (needs 4.5:1), #bbb on #fff
    where: main > p.subtitle   fix: darken to #767676
Fixed
- img-alt — <img src="old.jpg"> (no longer present)

For each new violation: where (selector verbatim, plus file:line (symbol) if source is present; don't fabricate), evidence, and fix (mechanical change or NEEDS HUMAN).

Don't edit. For fixes, apply the mechanical ones and re-run accesslint:accessibility-diff to verify; for bulk work hand off to accesslint:accessibility-fix.

3. Tear down

npx -y @accesslint/chrome@latest stop --all  # skip if ensure reported "managed":false

Notes

  • ensure determines the port; don't hardcode 9222.
  • CLI exit 2 means a bad URL or target, or the page never loaded; check the dev server.
  • A target name resolves the same in both runs only if accesslint.config.json is unchanged across the stash or checkout. If your changes touch the config, pass an explicit URL.
  • Stash mode: sleep 2 covers most HMR cases; if the baseline looks identical to current, add --wait-for "<selector>".
  • Branch mode: no HMR; the CLI opens a fresh tab each run, and --wait-for is the rebuild gate.
  • Large DOM changes between runs cause selector drift; re-run accesslint:accessibility-scan for the full picture.

This skill remediates accessibility violations: baseline, edit, verify. It only fixes. To find what's wrong, use accesslint:accessibility-scan (one page, automated), accesslint:accessibility-inspect (one page, manual), or accesslint:accessibility-audit (whole site, WCAG-EM); to check for regressions, use accesslint:accessibility-diff. The engine runs here are internal to the loop — a baseline before and a check after — not a report.

Shared conventions (grounding, never invent content): ../shared/methodology.md.

For large remediations, run via Task for context isolation; the steps are the same.

Input

  • A findings worklist (from accessibility-scan, accessibility-inspect, or accessibility-audit, or pasted): apply it directly; the baseline is already done.
  • A target (URL, config target name, files, or a directory): audit it first for the baseline, then fix.

Given neither, ask what to fix. Don't sweep a whole codebase unprompted.

Picking a flow (for baseline and verify)

  1. audit_live for any URL. It ensures a debuggable Chrome (auto-launches a headless one if none is reachable) and audits the live DOM. Use selector to scope and wait_for for async content. The live DOM catches what source can't.
  2. audit_html for raw HTML strings, files (Read first), or JSX rendered to a string.

For an authenticated session, have the user start a headed debuggable Chrome (npx @accesslint/chrome ensure --headed), sign in, then call audit_live({ url, port }) to attach to it.

Steps

  1. Baseline. Audit with format: "compact" and record the violation set (rule ID and selector for each). Skip this if you were handed a worklist.
  2. Apply. For each violation:
    • If a Source: line is present, open that file at that line. If several are listed (separated by ←), the first is the JSX literal and the rest are enclosing components; use Symbol to disambiguate.
    • If not, grep stable hooks (data-testid, id, aria-label), then visible text, then tree position.
    • Use the Fixability: and Fix: fields: apply mechanical fixes as given; leave a TODO with the rule ID for contextual or visual. Don't invent content (alt text, labels, link text).
    • Group edits to the same file into one operation.
    • Confirm scope before editing files outside the obvious target, or before more than about 10 mechanical fixes.
  3. Verify. Re-run the same audit and compare to the baseline: every targeted violation gone, no new ones. For a precise new/fixed/pre-existing comparison on a URL, use accesslint:accessibility-diff rather than checking by eye.

Source: lines come from React DevTools fibers and appear only in live-DOM audits against React dev builds. Static audits won't have them; fall back to selectors. When unsure about a rule, use explain_rule({ id }).

When to stop

  • A violation with no Fix: directive: leave a TODO, don't guess.
  • Verification fails (a new violation appeared, or a targeted one remains): report it and stop. Don't iterate silently.

Output

Per cycle: the flow used, violations by impact, what was applied (file and rule), what was deferred (TODOs and why), and the before and after counts.

This is the semi-automated manual tier of a WCAG assessment: the checks that need interaction (keyboard, focus, state changes, reflow) or human review (focus visibility, error recovery, reading order), which a static rule engine can't decide. Work against the running page; use source only to map a finding to file:line. Locate and assess — don't fix (that's accesslint:accessibility-fix). The automated tier is accesslint:accessibility-scan; accesslint:accessibility-audit runs both under WCAG-EM.

The shared rules — severity, the no-proxy boundary, high-risk patterns, conformance, grounding — are in ../shared/methodology.md. Read it when a call needs judgment. The rules that always apply are below.

Grading

Tag each finding with a severity (user impact) and an evidence basis (what you can support). Keep the two separate.

  • ● Verified — deterministic and reproducible. Cite the selector, the interaction, and the observed a11y-tree or DOM fact. Without that proof it is not ●.
  • ◐ Flagged — you have evidence, but the decision needs a person. Attach the evidence and your opinion; don't decide it yourself.
  • ○ Human-required — needs assistive technology or lived experience. Hand it off; don't emulate it.

When unsure between two evidence grades, use the lower one. The icons show evidence basis by fill, not color.

A finding that stacks a deterministic fact on an interpretive call takes the lower grade. The machine-checkable half (e.g. no programmatic status in the a11y tree — a 1.3.1 fact) is ● evidence inside a ◐ finding; the interpretive conclusion (e.g. that color is the sole carrier of the meaning — 1.4.1) stays ◐. Citing the ● half does not upgrade the whole.

Severity (user impact, separate from evidence basis):

  • Critical — blocks a core task, with no workaround.
  • Serious — a major barrier; the task is possible but difficult.
  • Moderate — noticeable friction; the task still completes.
  • Minor — a small inefficiency or polish issue.

The ledger — a denominator, not a script

The checkpoint areas below are the run's denominator: every criterion in them ends the run in exactly one state, and the report says which.

  • ● verified or ◐/○ flagged — you drove the check and have the evidence.
  • N/A — the triggering feature isn't on the page (no form, no media, no drag UI). Decided from the snapshot; free.
  • Not exercised — the feature is present but you didn't drive it. Reported as undetermined, never silently dropped, and never as a pass.

Not-exercised is a legitimate, honest outcome and it costs nothing. Drive only what the page's features and the engine's gaps demand; don't work through checkpoints to make the report look thorough. An "undetermined — not exercised" line and a driven-and-verified line differ in evidence, not in honesty.

Dedup before driving, not after: the engine (accessibility-scan) owns the statically-detectable criteria — name/label presence, lang, autocomplete, semantic markup, contrast of text on flat backgrounds. If a scan result set or engine-owned SC list was provided (as accessibility-audit does), never re-check those criteria; ledger them as engine-owned. Without one, read what you can from the initial snapshot rather than re-deriving what the engine would catch.

AreaSCsTrigger to drive
Keyboard & focus2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11Always — one batched walk (below)
Structure & semantics1.3.1, 1.3.2, 2.4.1, 2.4.6Always — read from the initial snapshot; no extra driving
Names, roles, states4.1.2, 2.5.3, 4.1.3Custom widgets / stateful controls present (static name presence is engine-owned)
Visual adaptation1.4.1, 1.4.4, 1.4.10, 1.4.12, 1.3.4, 2.3.3, 1.4.11Reflow/zoom on every page (one resize each); motion checks only if motion is present
Forms & errors3.3.1–3.3.3, 1.3.5, 3.3.7, 3.3.8A form is present (label/autocomplete presence is engine-owned)
Media & timing1.2.x, 2.2.1, 2.2.2<video>/<audio>, autoplay, or timeouts present
Pointer & target2.5.1, 2.5.7, 2.5.8Target size comes free from the batched walk; drag checks only if drag UI
Content & navigation3.1.1/2, 2.4.4, 3.2.3/4, 3.2.6lang and link purpose from the snapshot; cross-page consistency is accessibility-audit's (not exercised here)

Per-checkpoint procedure and default grades: references/checkpoints.md. Read it when a triggered area needs its detailed steps, or when the user asks for a deep pass (--deep: drive every triggered area through its full procedure).

Evidence budget — cap spend by grade

Calibrated uncertainty must be cheaper than false certainty. The grade a finding can reach bounds the evidence worth gathering:

  • ● — full proof, gathered once: selector, interaction, observed DOM or a11y-tree fact. Don't repeat an interaction you already recorded.
  • ◐ — hard cap: one selector, one screenshot (only if the question is visual), your opinion, and what a person should confirm. Then stop. A ◐ is re-decided by a human whichever way you lean; more evidence doesn't upgrade it to ●, it just costs more.
  • ○ — zero driving: name the functional ability, the assistive technology, and the flow you already exercised. Never drive the page to "strengthen" a ○.

Prerequisite: a browser to drive

This tier runs through a browser MCP: chrome-devtools (recommended), playwright, or puppeteer. If none is connected, run only the static checks, report the rest as ○ handoffs, and tell the user:

claude mcp add chrome-devtools npx -- -y chrome-devtools-mcp@latest

Target

$ARGUMENTS is a URL, an accesslint.config.json target name, or empty for the default target. --selector <css> scopes to a component; --wait-for <css> waits for async content.

navigate_page needs a URL, so resolve first:

  • A URL: use it.
  • A target name or empty: read accesslint.config.json (and the gitignored accesslint.config.local.json overlay) and resolve the name (or default) to its url; also take its waitFor and selector.
  • No config: ask for a URL, or suggest npx @accesslint/cli init.

Then navigate to the URL and wait for the gate (--wait-for if given, otherwise the target's waitFor) before testing.

Driving efficiently

One snapshot, then scoped reads. Take one full snapshot after the wait gate; it is the basis for structure, names, roles, states, and the N/A decisions. After a state change, don't re-snapshot the page — read only the widget that changed, via evaluate_script scoped to its selector (or a snapshot of that subtree). A full-page re-snapshot per interaction is the single largest avoidable cost in this tier.

One batched keyboard walk. Traverse focus in a single evaluate_script call, not one press_key/snapshot cycle per stop: compute the tabbable sequence, focus() each element in order, and return compact JSON per stop — selector, role/name, document.activeElement confirmation, computed outline/box-shadow on :focus, bounding box (which settles 2.5.8 for free), and whether the element sits under a sticky/overlay rect (2.4.11). The walk is deterministic DOM fact, so its results are ●-citable.

The walk finds candidates; real key events confirm behavior. Scripted focus() doesn't run an app's keydown handlers, so operability (Enter/Space/arrows) and trap claims still need press_key — but only at the walk's suspects: composite widgets (roving tabindex, aria-activedescendant), elements whose handlers plausibly capture Tab/Esc, anything the walk couldn't reach. A ● keyboard-trap finding needs the real Tab/Esc presses at that widget; it doesn't need them at every widget on the page.

High-risk patterns

For drag-and-drop, rich-text editors, tree views, data grids, custom comboboxes or menus, carousels, and toast or live-region-heavy UIs, heuristic checks are unreliable. Name the APG pattern, verify what you can (●/◐), and hand off the rest as ○ with the assistive-technology steps to run. Use explain_rule for engine rules and the APG for widget contracts.

Report

Group findings by evidence basis; mark severity inline. Close the ledger at the top — every SC in the denominator lands in exactly one bucket — and keep it compact: counts, then bare SC numbers. Group not-exercised SCs by shared reason, one parenthetical clause per group, never a line per SC.

The report spends its words on failures, flags, and handoffs. A pass is its SC number in the ledger — not a paragraph: no "what passed" narration beyond at most one sentence, and no restating in the recommendations a fix already given on its finding.

# Manual inspection — <target>  ·  semi-automated tier
Severity: <c> critical · <s> serious · <m> moderate    Basis: ● <v> · ◐ <f> · ○ <h>
Ledger: pass ● <SCs> · fail ● <SCs> · flagged ◐/○ <SCs> · engine-owned <SCs> · N/A <SCs>
        not exercised → undetermined: <SCs (shared reason)> · <SCs (shared reason)>

## ● Verified
- [serious] Keyboard trap in date picker — SC 2.1.2
    where: div.datepicker[role=dialog]   repro: Tab into grid, focus never exits via Tab or Esc
    fix: <mechanical> | NEEDS HUMAN

## ◐ Flagged
- [moderate] Focus indicator may be too faint — SC 2.4.7
    where: button.ghost   evidence: focus-ghost.png; outline = 1px rgba(0,0,0,.2)
    opinion: likely fails 3:1 non-text contrast — confirm visually

## ○ Human-required
- Live-region announcement on add-to-cart — SC 4.1.3
    aria-live="polite" present (●); actual NVDA/JAWS/VoiceOver output unverified
    needs: screen-reader users (blind / low-vision, per Section 508 FPC)
    flow: add-to-cart → toast (exercised above)

Ground each entry by selector and visible text. Add file:line (symbol) only when accessibility-scan's source maps provide it; don't guess. Each ○ entry is a handoff: the functional ability and assistive technology needed, plus the flow you exercised.

Notes

  • The a11y tree shows machine state, not what a screen reader announces. aria-live being present does not mean it announces.
  • Browser zoom isn't exposed; CSS-zoom approximations are ◐.
  • Wait for async content before the initial snapshot; after that, prefer selector-scoped reads over re-snapshots.
  • Composing the tiers (dedup against accessibility-scan, one shared browser) is accessibility-audit's job. On its own, this skill reports what its checks find — and its ledger says what they didn't.

Audit a live page and report each violation and where it is. Locate; don't fix.

Shared grounding and honesty conventions: ../shared/methodology.md.

$ARGUMENTS is a URL, a config target name (dev, storybook, …), or empty to audit the default target from accesslint.config.json. If it's empty and no config exists, ask for a URL or suggest npx @accesslint/cli init.

1. Audit

PORT=$(npx -y @accesslint/chrome@latest ensure | node -e 'process.stdin.on("data",d=>process.stdout.write(""+JSON.parse(d).port))')
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --format json

<target> is the URL or config target name from $ARGUMENTS. Omit it (don't pass "") to audit the config's default target. Add flags as needed: --selector, --wait-for "<selector>", --include-aaa, --disable <rules>, or pin them per-target in accesslint.config.json.

2. Report

Counts by impact, then one entry per violation:

  • where: selector verbatim, plus file:line (symbol) if source is present. Don't fabricate. If no violation has source, note "source mapping unavailable; located by selector only".
  • evidence: contrast ratio, missing attribute, empty name.
  • fix: mechanical change, or NEEDS HUMAN.

Don't edit. For fixes, apply the mechanical ones and re-run to verify; for bulk work hand off to accesslint:accessibility-fix.

3. Tear down

npx -y @accesslint/chrome@latest stop --all  # skip if ensure reported "managed":false

Notes

  • ensure determines the port; don't hardcode 9222.
  • CLI exit 2 means a bad URL or target, or the page never loaded; check the dev server. An unknown target name makes the CLI list the available targets from accesslint.config.json.

MCP servers 1

Sponsors

Details

Marketplace
AccessLint/skills
Source
plugins/accesslint
Author
AccessLint
Category
Code Quality
License
MIT
Keywords
accessibility, a11y, wcag, wcag22, screen-reader, keyboard-navigation, color-contrast, aria, section-508, audit, conformance, inclusive-design