a11y-toolkit — the accessibility layer for AI coding agents

23 MCP tools + 5 prompts + a skill covering the full WCAG 2.2 loop: audit → fix → document → watch → hand off. 51 of 55 A/AA criteria carry automated signals (93%). Zero dependencies at the core; every finding ships with a concrete remediation your agent can apply. Works with Chromium, Firefox, WebKit, Chrome or Edge — whatever you have.

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

a11y.jquin.net — the machine half, free forever: full report, honest badge, evidence-pack download. SSRF-guarded, rate-limited. Every free report ends at the exact boundary where a qualified human begins.

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

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 human half is priced, not guessed: every A/AA criterion carries an effort class — MIN 23 (read and confirm), MED 19 (verify in the browser), MAX 13 (real interaction and judgment) — full table. The evidence pack is the handoff object for the human who signs — and now includes a screen reader transcript 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

• Rendered audit (shadow DOM, state contrast, text spacing, color-only links)
• 0-100 score · ARIA validity · criterion knowledge (56 entries)
• Form error testing + autofix (find AND fix)
• Keyboard traps + focus/input navigation detection (2.1.2, 3.2.1, 3.2.2)
• Infinite scroll · reflow · W3C Nu validation
• SARIF export · error budget · scheduled surveillance recipe
• Evidence pack with agent-verified status (spec published, self-verifying)
• Form deep-dive: placeholder-only, fieldset, label quality, financial confirmation
• Sitemap-driven crawling · behind-login auditing (auth_state)
• 51/55 A/AA criteria with automated signals (93%)
• Browser auto-detection (Chromium, Firefox, WebKit, Chrome, Edge)
• Screen reader transcript · hover dismissibility · disprover · coverage ledger

Author

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