A11Y Toolkit

a11y-toolkit — the accessibility layer for AI coding agents

🌐 English · Español

WCAG 2.2 for your coding agent — audit, fix, document and watch. Zero dependencies, es/en.

[a11y-toolkit in action: audit (score 64), nearest passing color, re-audit (94) — real tool output]

37 MCP tools, 6 prompts and a skill covering the whole WCAG 2.2 loop: audit, fix, document, watch, hand off — and now blindfold usability testing, where the agent attempts real tasks perceiving only what a screen reader exposes. 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.

[Human in the Loop — humans guide and curate the process; every conformance artifact is signed by a person]

Quickstart

# MCP — one line, any MCP client (Claude, Cursor, Codex, Windsurf, …)claude mcp add a11y-toolkit -- uvx --from a11y-toolkit a11y-toolkit-mcp
# CLI — same engine, one commandpip install a11y-toolkita11ytoolkit audit --url https://example.coma11ytoolkit pair "#1f2328" "#fbfaf7"

Static audits, contrast math, PDF/DOCX screening and the evidence pack run with zero dependencies. The rendered tools (real contrast over images, keyboard traps, reflow, forms) additionally need Playwright: pip install playwright && playwright install chromium.

[CI] [PyPI] [npm] [Downloads] [License: MIT] [MCP] [Sponsor] [Supply chain] [OpenSSF Scorecard] [OpenSSF Best Practices] [ACT Rules] [Releases] [Dependencies] [Python Versions] [GitHub Release]

Features

The tools (37)

Full reference — descriptions, arguments, return shapes and behavior — in docs/tools.md. All tools accept lang (en|es) unless noted; output is JSON unless noted. Generated from server.TOOLS by scripts/gen_readme.py.

The 6 prompts

• audit-page (url*, language): Full accessibility audit workflow for a URL: automated tools + what to verify manually (keyboard, screen reader, zoom). Every prompt exists in English and Spanish.

• fix-contrast (fg*, bg*, context): Guided contrast fix: verify the pair (or the text-over-image region), get the nearest passing color, apply it to the code. Every prompt exists in English and Spanish.

• pre-deploy-check (url*, baseline): Pre-deploy regression check: express audit of the URL plus snapshot diff against a baseline snapshot. Every prompt exists in English and Spanish.

• declaration-eaa (entity*, url*, status): Generate a European Accessibility Act / RD 1112/2018 accessibility statement, collecting any missing legal fields from the user. Every prompt exists in English and Spanish.

• conformance-wcagem (url*, tier, language): Guided WCAG-EM conformance ladder for a site: express screening → agent-verified guided evaluation on a representative sample → conformance report inputs. Every prompt exists in English and Spanish.

• blindfold-task (url*, goal*, kind, language): Blindfold usability test — the agent attempts a real task perceiving ONLY the accessibility tree and acting only by accessible name and keyboard, logging friction per step; closes with a11y_journey_verdict. The capability no other accessibility tool has: task-based non-visual testing where the agent IS the screen-reader user. Every prompt exists in English and Spanish.

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 Node-native? npx -y @kinti/a11y-toolkit mcp… — the npm launcher runs the same engine via uv (npm/). docs/clients.md for every verified config format. Composing it with the popular servers (Playwright, GitHub, Filesystem, Fetch…) — docs/interop.md. Start-to-finish recipes (audit → fix → seal → CI): docs/cookbook.md.

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./skills/install-skill.sh     # → ~/.zcode/skills and ~/.claude/skills

Agent hook — a11ytoolkit init

Agents that read AGENTS.md on their own get the rule that matters — after any UI change, re-audit before calling the work done — with the exact commands:

cd your-projectuvx --from a11y-toolkit a11ytoolkit init     # writes/merges the AGENTS.md hook (idempotent)

It also prints the MCP config block and the optional skill install step. --check reports whether the hook is present (exit 1 if not — CI-friendly).

Languages — community locale packs

All user-facing messages (findings, remediations, legal wording) live in locale packs — one JSON per language, es and en ship today. Adding a language is a single-file PR: copy _template.json, translate keeping the {placeholders}, and python3 tests/test_locales.py validates it mechanically (keys, placeholders, plural rule, completeness). Same community model as axe-core's locales — with validation axe-core doesn't have. Guide: docs/i18n.md. Downstream products can layer brand wording via overlays without forking.

Claim an open language: French, Brazilian Portuguese and German have seeded issues under good first issue — one JSON file, mechanical validation, credit in the README and in the release notes. Any other language: use the Add a language template. Human translation only — machine translation is rejected; the catalog IS the product's voice.

CLI — same engine, one command

Install it with pip install a11y-toolkit (or uv tool install a11y-toolkit).

a11ytoolkit audit --changed                     # ONLY what changed since HEAD (CI gate)a11ytoolkit audit --changed --base origin/main  # a branch's changes — exit 2 on high/mediuma11ytoolkit audit --url https://example.com --pages 5   # sitemap-first crawla11ytoolkit pair "#1f2328" "#fbfaf7"                    # contrasta11ytoolkit image hero.jpg --text "#fff" --region 120,40,420,90a11ytoolkit forms https://mysite/contact                # form errorsa11ytoolkit kbd https://mysite                          # keyboard traps + 3.2.1/3.2.2a11ytoolkit reflow https://mysite                       # 320px reflowa11ytoolkit scroll https://medium.com/feed              # infinite scrolla11ytoolkit validate --url https://example.com          # W3C Nua11ytoolkit hover https://mysite                        # tooltip dismissibilitya11ytoolkit fix --file page.html -o fixed.html          # safe autofixa11ytoolkit declaration --entity "Acme" --url https://… --status partial --framework eaaa11ytoolkit snapshot https://mysite --out before.json   # before deploya11ytoolkit diff before.json after.json                 # after deploya11ytoolkit evidence audit.json -o pack.json            # verifiable evidence packa11ytoolkit disprove --url https://mysite               # re-verify findingsa11ytoolkit budget --budget budget.json --audit audit.json  # only NEW findings blocka11ytoolkit budget --init-snapshot s.json > structural.json      # structural budget: today's structure is accepteda11ytoolkit budget --budget structural.json --snapshot s2.json   # only NEW rendered structure blocks (exit 0/2)a11ytoolkit engines https://mysite                        # same page in 3 engines: behavioral divergences, pairwisea11ytoolkit trace https://mysite --script journey.json -o t.json  # scripted real journey, then: trace diff t_old.json t.jsona11ytoolkit patterns https://mysite                       # APG keyboard contracts, live: dialog / tablist / disclosure / combobox / menu / slidera11ytoolkit ledger recurrence --ledger a11y-ledger.json   # chronic signals + hot urls: the review queue without MLa11ytoolkit contrast-dom https://mysite --walk            # perceptual pass: per-element ratios, thresholds, suggestionsa11ytoolkit sarif --from-audit audit.json -o a11y.sarif # GitHub code scanninga11ytoolkit badge --score 92 --out badge.svg            # honest SVGa11ytoolkit contrast-dom https://mysite --selector ".hero h1"  # auto-region pixel samplinga11ytoolkit vpat pack.json --product "Acme" -o vpat.html      # VPAT 2.5 (WCAG) drafta11ytoolkit earl --from-audit audit.json -o earl.json          # ACT Rules / EARL exporta11ytoolkit wcag3 --from-audit audit.json                      # WCAG 3 draft preview (no score)a11ytoolkit route --goal "gate my PR"                          # which tools for the taska11ytoolkit route --file page.html                             # diagnosis: the page orders the examsa11ytoolkit mutants --seed 7 --n 12                            # the engine's sealed self-exama11ytoolkit fingerprints pages/*.html -o templates.json        # twin pages → one audit per templatea11ytoolkit audit --url page.html --standard en301549          # EN 301 549 clause on every findinga11ytoolkit scope audit.json --standard 508 -o scope.json      # GSA applicability tree, WCAG exceptionsa11ytoolkit scope audit.json --solicitation annex.txt          # tender-ready accessibility annex (es/en)a11ytoolkit annotate page.html --report r.json -o marked.html  # per-element marks on a byte-exact copya11ytoolkit locate --file page.html --query "Submit"           # element by accessible name → route selectora11ytoolkit patches --file page.html -o patches.json           # sealed fix record (verify with --verify)a11ytoolkit criteria --list --level AA --new-in 2.2            # the offline Quick Ref, filterablea11ytoolkit wizard --url https://client.web --lang es          # guided: 3 questions → standard, audit, scope, annex

Standards coverage

Which market's law each command serves: docs/standards-coverage.md — EN 301 549 (EU-27 + EEA + Canada), Section 508 (US federal), RGAA 4.1 (France), WCAG-direct (Latin America and most ADA practice) — one engine, the standard of 27+ countries.

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.

The engine behind a11y.es

a11y.es is a Spanish-market accessibility service that runs this engine. The service is a separate codebase; this repository is the engine.

Validated against real pages

Benchmarked against axe-core 4.10 on real pages monthly (methodology and results). Task-based agent benchmark on live sites, including a stratified sample of Spain's most important pages (method and results). Found a contrast finding on gov.uk that axe leaves incomplete (search button at 3.91:1; manual review showed the visible part is an icon that passes the 3:1 non-text threshold, so it is not a conformance failure). Drove out our own false positives (hidden skip links, honeypot fields, single-context generic links, image-alt accname — each with a regression fixture).

Also run against the official W3C ACT test cases: scripts/act_report.py regenerates the EARL implementation report — 100% consistent with every published ACT rule it implements (355 official test cases, 20/20 rules, zero inconsistencies, verified per release against the w3c/wcag-act-rules repository; per-rule breakdown in docs/act-report-summary.md). The WCAG 2.2 catalog (86 criteria, A/AA/AAA) and the WCAG 3 outcome registry are likewise verified against their canonical w3.org sources (scripts/wcag22_ingest.py, scripts/wcag3_ingest.py).

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 finding you read about above is not a synthetic benchmark case: this engine found it, and the manual review is what caught the false positive before it shipped as a claim.

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 the 55 A/AA criteria (roughly a third of all WCAG once AAA and the genuinely-human checks are counted) — 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 && python3 tests/test_png.py && python3 tests/test_vpat.py \  && python3 tests/test_act.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.

Generated surfaces — never edit by hand: this README's tool table and docs/tools.md come from server.TOOLS (scripts/gen_readme.py), and llms.txt — this repo's index for agents, llmstxt.org convention — from the same source (scripts/gen_llms.py). Both --check in the Makefile gates: adding a tool and forgetting them fails the suite.

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 signature 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

Community

• Questions, ideas, show & tell → Discussions
• First contribution → the good first issue queue — translations are the designed entry point: no code, one file, validated mechanically (guide)
• Bugs and features → the issue templates

A practical ladder: translate → docs → bug → feature. Everything you ship is credited below and in the release notes.

Contributors

The next name here is probably a translator's: claim an open locale issue and your language ships in the next release with your name on it.

Author

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

License & name

The code is MIT — use it, sell it, embed it, fork it, including in closed-source products. One thing MIT does not cover: the name. "a11y-toolkit", the logo and the project marks are reserved and are not part of the MIT grant — a fork or redistribution that modifies the code ships under its own name, not ours. Same playbook as Debian and Firefox: permissive code, protected brand.

Built something with a11y-toolkit? Tell us — public tools get featured and credited.