
accesslint
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@accesslintRun it inside Claude Code after adding the marketplace with /plugin marketplace add AccessLint/skills.
Contents
Discovered from sourceSkills 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.
-
Scope. State the target and its boundary, the goal (default WCAG 2.2 AA;
--level AAAadds AAA), the technologies in use, and the assistive-technology baseline the human handoff should cover. You scope that baseline; you don't test it. -
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.jsontargets are a starting point. -
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.
-
Evaluate. Delegate each sampled page or state to its own
Taskso 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, thenaccesslint:accessibility-inspectagainst 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-scanowns rule-detectable criteria,accessibility-inspectowns 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 (
--autoConnector--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-forgate and dedups by SC ownership. - runs
-
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 (useaccessibility-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_rulesandexplain_rulefor 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
ensuredetermines 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.jsonis unchanged across the stash or checkout. If your changes touch the config, pass an explicit URL. - Stash mode:
sleep 2covers 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-foris the rebuild gate. - Large DOM changes between runs cause selector drift; re-run
accesslint:accessibility-scanfor 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, oraccessibility-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)
audit_livefor any URL. It ensures a debuggable Chrome (auto-launches a headless one if none is reachable) and audits the live DOM. Useselectorto scope andwait_forfor async content. The live DOM catches what source can't.audit_htmlfor raw HTML strings, files (Readfirst), 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
- Baseline. Audit with
format: "compact"and record the violation set (rule ID and selector for each). Skip this if you were handed a worklist. - 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; useSymbolto disambiguate. - If not, grep stable hooks (
data-testid,id,aria-label), then visible text, then tree position. - Use the
Fixability:andFix:fields: applymechanicalfixes as given; leave aTODOwith the rule ID forcontextualorvisual. 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.
- If a
- 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-diffrather 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 aTODO, 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.
| Area | SCs | Trigger to drive |
|---|---|---|
| Keyboard & focus | 2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11 | Always — one batched walk (below) |
| Structure & semantics | 1.3.1, 1.3.2, 2.4.1, 2.4.6 | Always — read from the initial snapshot; no extra driving |
| Names, roles, states | 4.1.2, 2.5.3, 4.1.3 | Custom widgets / stateful controls present (static name presence is engine-owned) |
| Visual adaptation | 1.4.1, 1.4.4, 1.4.10, 1.4.12, 1.3.4, 2.3.3, 1.4.11 | Reflow/zoom on every page (one resize each); motion checks only if motion is present |
| Forms & errors | 3.3.1–3.3.3, 1.3.5, 3.3.7, 3.3.8 | A form is present (label/autocomplete presence is engine-owned) |
| Media & timing | 1.2.x, 2.2.1, 2.2.2 | <video>/<audio>, autoplay, or timeouts present |
| Pointer & target | 2.5.1, 2.5.7, 2.5.8 | Target size comes free from the batched walk; drag checks only if drag UI |
| Content & navigation | 3.1.1/2, 2.4.4, 3.2.3/4, 3.2.6 | lang 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 gitignoredaccesslint.config.local.jsonoverlay) and resolve the name (ordefault) to itsurl; also take itswaitForandselector. - 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-livebeing 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) isaccessibility-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)ifsourceis present. Don't fabricate. If no violation hassource, 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
ensuredetermines 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