a11y-toolkit — the accessibility layer for AI coding agents

23 MCP tools, 5 prompts and a skill covering the whole WCAG 2.2 loop: audit, fix, document, watch, hand off. 51 of 55 A/AA criteria carry automated signals (93%), every finding ships with a concrete remediation your agent can apply, and the rendered tools run on whichever browser you have — Chromium, Firefox, WebKit, Chrome or Edge.

The European Accessibility Act is in force since June 2025, ADA suits keep landing, and AI agents now write most of the web. A scan is not a defence: the machine finds, the human signs.

What no other a11y tool gives an agent

The tools (23)

Audit

Fix

Document

Watch

Hand off

5 prompts: audit-page, fix-contrast, pre-deploy-check (GO/NO-GO), declaration-eaa, conformance-wcagem (three-tier WCAG-EM ladder).

Install

mcp-name: io.github.kinti/a11y-toolkit · PyPI: a11y-toolkit · Zenodo DOI: 10.5281/zenodo.22843722

Works with any MCP-capable client — Claude Code/Desktop, Cursor, Windsurf, VS Code, Codex CLI, OpenCode, ZCode, Zed, Cline, Continue, Kimi Code… See docs/clients.md for every verified config format.

claude mcp add a11y-toolkit -- uvx --from a11y-toolkit a11y-toolkit-mcp

Or with JSON config:

{
  "mcpServers": {
    "a11y-toolkit": {
      "command": "uvx",
      "args": ["--from", "a11y-toolkit", "a11y-toolkit-mcp"],
      "timeoutMs": 60000
    }
  }
}

Rendered tools use Playwright if present and accept a browser parameter (auto, chromium, firefox, webkit, chrome, msedge — auto-detects the first available). Accept auth_state (Playwright storage_state path) to audit behind login. Everything else works with zero dependencies.

The skill

git clone https://github.com/kinti/a11y-toolkit && cd a11y-toolkit
./skill/install-skill.sh     # → ~/.zcode/skills and ~/.claude/skills

CLI — same engine, one command

a11ytoolkit audit --url https://example.com --pages 5   # sitemap-first crawl
a11ytoolkit pair "#1f2328" "#fbfaf7"                    # contrast
a11ytoolkit image hero.jpg --text "#fff" --region 120,40,420,90
a11ytoolkit forms https://mysite/contact                # form errors
a11ytoolkit kbd https://mysite                          # keyboard traps + 3.2.1/3.2.2
a11ytoolkit reflow https://mysite                       # 320px reflow
a11ytoolkit scroll https://medium.com/feed              # infinite scroll
a11ytoolkit validate --url https://example.com          # W3C Nu
a11ytoolkit hover https://mysite                        # tooltip dismissibility
a11ytoolkit fix --file page.html -o fixed.html          # safe autofix
a11ytoolkit declaration --entidad "Acme" --url https://… --estado parcial --marco eaa
a11ytoolkit snapshot https://mysite --out before.json   # before deploy
a11ytoolkit diff before.json after.json                 # after deploy
a11ytoolkit evidence audit.json -o pack.json            # countersignature-ready pack
a11ytoolkit disprove --url https://mysite               # re-verify findings
a11ytoolkit budget --budget budget.json --audit audit.json  # only NEW findings block
a11ytoolkit sarif --from-audit audit.json -o a11y.sarif # GitHub code scanning
a11ytoolkit badge --score 92 --out badge.svg            # honest SVG

Coverage: 51 of 55 WCAG 2.2 A/AA criteria (93%)

The 4 manual-only criteria each have a knowledge entry (a11y_criterion) telling the agent exactly how to verify them by hand. The boundary is printed on every report.

Free online analyzer

I also run a11y.jquin.net, a free online analyzer with the same engine — full report, badge, evidence-pack download. Every report ends at the exact boundary where a qualified human begins, which is the point.

Validated against real pages

Benchmarked against axe-core 4.10 on real pages monthly (methodology and results). Found a real WCAG failure on gov.uk that axe does not report (blue button at 3.91:1, manually verified). Drove out our own false positives (hidden skip links, honeypot fields, single-context generic links, image-alt accname — each with a regression fixture).

Why I built this

I have been auditing websites for accessibility since 2003. In twenty years the tools got faster and the failures stayed the same: the same missing alt text, the same keyboard traps, the same forms that swallow your work. When AI agents started writing most of the web, the audit gap stopped being a staffing problem and became an infrastructure one.

So I built the tool I always wanted next to me on an audit. Not another scanner — scanners exist. A toolkit that does half the work, says exactly where it stops, and packages the rest for the person who signs. The gov.uk failure you read about above is not a synthetic benchmark case: this engine found it, and I confirmed it with my own eyes before writing it down.

If it saves you an afternoon, leave a star — it genuinely helps the next auditor find it. If it doesn't, open an issue and tell me what is missing.

Honesty, built in

Every audit says: automation covers 93% of A/AA criteria; the rest needs a human. The audit-page prompt and the skill have the agent check what it can (keyboard, focus, zoom, announced errors) using the manual checklist. A filter, not a verdict. The remaining human work is priced per criterion — MIN 23 (read and confirm), MED 19 (verify in the browser), MAX 13 (real interaction and judgment); full table. And the evidence pack is the handoff object for the person who signs, screen reader transcript included, so the reviewer sees what a blind user hears.

Security & scope

A local tool: runs on your machine as your user. a11y_audit_url accepts http/https only (no file:// — use --file/html for local HTML). a11y_html_validate in html mode POSTs content to the W3C service (url mode shares only the URL; self-hosted vnu supported). path/output_path read/write local paths — use it in MCP clients you trust.

Development

python3 tests/test_contrast.py && python3 tests/test_audit.py && python3 tests/test_v32.py \
  && python3 tests/test_dom.py && python3 tests/test_cli.py && python3 tests/test_solido.py \
  && python3 tests/test_mcp.py

tests/test_dom.py self-skips without Playwright. tests/test_solido.py enforces the design invariants (catalog parity, version alignment, count coverage, hostile-HTML fuzz). Releases: make release V=X.Y.Z — bumps, gates, tags and pushes atomically.

Roadmap

Done recently: rendered audit with shadow DOM and state contrast, form error testing plus autofix, keyboard traps, infinite scroll, reflow, the W3C Nu integration, SARIF and error budgets, the evidence pack (spec published, self-verifying), sitemap crawling, behind-login auditing, browser auto-detection, the screen reader transcript, and per-criterion effort pricing. The full history lives in the changelog.

Next, roughly in this order:

• Attestation interlock: let an external auditor's countersignature reference the evidence pack by hash (their schema, my side adapts)
• Publish the monthly axe-core benchmark results from CI, run over real pages
• Screen-reader transcript cross-checks against NVDA and VoiceOver output
• More verified client configs (JetBrains AI, Gemini CLI), same treatment as docs/clients.md

Author

Jesús Quintana Fernández (jquin.net) — SEO/GEO consultant and web-accessibility practitioner since 2003. MIT © 2026.