a11y-toolkit — the accessibility layer for AI coding agents

19 MCP tools + 5 prompts + a skill covering the full WCAG 2.2 loop: audit → fix → document → watch → hand off. 50 of 54 A/AA criteria carry automated signals (92%). Zero dependencies at the core; every finding ships with a concrete remediation your agent can apply.

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 (19)

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

Registry: 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 (pip install playwright && playwright install chromium); everything else works with zero dependencies. Rendered tools accept auth_state (Playwright storage_state path) to audit behind login.

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 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 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: 50 of 54 WCAG 2.2 A/AA criteria (92%)

The 5 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 92% 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 evidence pack is the handoff object for the human who signs.

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 test_contrast.py && python3 test_audit.py && python3 test_v32.py \
  && python3 test_dom.py && python3 test_cli.py && python3 test_solido.py \
  && python3 test_mcp.py

test_dom.py self-skips without Playwright. 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)
• Form deep-dive: placeholder-only, fieldset, label quality, financial confirmation
• Sitemap-driven crawling · behind-login auditing (auth_state)
• 50/54 A/AA criteria with automated signals (92%)

Author

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