A11Y Toolkit

a11y-toolkit — 面向 AI 编码 Agent 的无障碍层

为你的编码 Agent 提供 WCAG 2.2 支持——审计、修复、记录并持续监测。零依赖，支持西班牙语/英语。

32 个 MCP 工具、6 个提示词和一项技能，覆盖完整的 WCAG 2.2 流程：审计、修复、记录、监测、交接——现在还支持蒙眼可用性测试，Agent 会尝试执行真实任务，只感知屏幕阅读器呈现的内容。55 项 A/AA 标准中有 51 项带有自动化检测信号（93%），每条发现都附带可由 Agent 应用的具体修复方案，渲染工具可在你使用的任意浏览器中运行——Chromium、Firefox、WebKit、Chrome 或 Edge。

《欧洲无障碍法案》自 2025 年 6 月起生效，ADA 诉讼仍接连不断，而如今大多数网页都由 AI Agent 编写。扫描并不能构成防御：机器负责发现，人类负责签字。

快速开始

# 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 command
pip install a11y-toolkit
a11ytoolkit audit --url https://example.com
a11ytoolkit pair "#1f2328" "#fbfaf7"

静态审计、对比度计算、PDF/DOCX 筛查和证据包均可零依赖运行。渲染工具（图像上的真实对比度、键盘陷阱、重排、表单）还需要 Playwright： pip install playwright && playwright install chromium。

功能

能力	axe-core / Lighthouse / pa11y	a11y-toolkit
图像和渐变上的文本对比度（对真实背景进行像素采样）	否	是
根据证据包生成 VPAT 2.5（WCAG）草案——EAA 声明在美国/ADA 下的对应文件	否	是
表单错误测试：填入无效数据、实际提交并判断结果	否	是
键盘陷阱：实际 Tab 遍历 + Escape 释放测试，以及由焦点/输入触发的导航	否	是
无限滚动审计：焦点保持、播报、信息流结束	否	是
在 320px 宽度下重排，并测量 WCAG 文本间距覆盖效果	否	是
屏幕阅读器转录：盲人用户听到的线性化内容	否	是
通过实际悬停捕获忽略 Escape 的工具提示（1.4.13）	否	是
EAA / RD 1112/2018 法律声明，支持西班牙语和英语	否	是
可供人类签署的证据包——哈希、矩阵、空白签名栏	否	是
ACT 规则互操作：EARL 导出 + 对照 W3C 官方测试用例的逐规则一致性报告	否	是
WCAG 3 草案预览——将 2.2 的发现归入草案结果，不生成虚假分数	否	是
核心功能零依赖运行，支持西班牙语/英语，兼容你使用的任意浏览器	运行时依赖庞大	零依赖

工具（32 个）

完整参考——说明、参数、返回结构和行为——见 docs/tools.md。除非另有说明，所有工具都接受 lang（en|es）；输出为 JSON。内容由 scripts/gen_readme.py 根据 server.TOOLS 生成。

工具	类别	功能
a11y_audit_url	审计	快速 WCAG 审计
a11y_audit_dom	审计	渲染后的 WCAG 审计
a11y_audit_pdf	审计	PDF 无障碍筛查
a11y_docx_screen	审计	DOCX 无障碍筛查
a11y_journey_verdict	盲测	盲测流程判定
a11y_autofix	修复与对比度	确定性安全自动修复
a11y_contrast_pair	修复与对比度	对比度及判定
a11y_contrast_image	修复与对比度	图像上的文字对比度
a11y_contrast_dom	修复与对比度	实时元素对比度采样
a11y_suggest_color	修复与对比度	最接近且达标的颜色
a11y_generate_declaration	文档	无障碍声明（EAA/RD 1112）
a11y_generate_vpat	文档	VPAT 2.5 报告（WCAG 版本）
a11y_badge	文档	真实的 SVG 徽章
a11y_snapshot	监测（回归）	无障碍快照及 Tab 顺序
a11y_diff	监测（回归）	快照回归差异
a11y_diff_urls	监测（回归）	暂存环境与生产环境差异
a11y_aria_live_snippet	监测（回归）	aria-live 监测代码片段
a11y_criterion	知识与上下文	WCAG 准则说明
a11y_html_validate	知识与上下文	W3C Nu 验证
a11y_keyboard	交互	键盘陷阱检测器
a11y_forms	交互	表单错误测试
a11y_hover	交互	悬停内容可关闭性（1.4.13）
a11y_reflow	交互	320px 重排检查
a11y_scroll	交互	无限滚动审计
a11y_sr_transcript	交互	屏幕阅读器转录文本
a11y_reduced_motion	交互	是否遵循 prefers-reduced-motion？
a11y_forced_colors	交互	forced-colors 兼容性启发式检查
a11y_vtt_check	交互	WebVTT 字幕质量
a11y_evidence	覆盖与证据	证据包（可验证的交接材料）
a11y_disprove	覆盖与证据	反证：重新验证发现项
a11y_ledger	覆盖与证据	覆盖台账（持久化）
a11y_wcag3_preview	覆盖与证据	WCAG 3 草案预览（不评分）

6 个提示词

• audit-page（url*、language）：针对 URL 的完整无障碍审计工作流：自动化工具，以及需要手动核查的内容（键盘、屏幕阅读器、缩放）。每个提示词均提供英文和西班牙文版本。

• fix-contrast（fg*、bg*、context）：引导式对比度修复：验证颜色组合（或文字叠加在图像上的区域），获取最接近的合格颜色，并将其应用到代码中。每个提示词均提供英文和西班牙文版本。

• pre-deploy-check（url*、baseline）：部署前回归检查：对 URL 进行快速审计，并将快照与基线快照进行差异比较。每个提示词均提供英文和西班牙文版本。

• declaration-eaa（entity*、url*、status）：生成《欧洲无障碍法案》/ RD 1112/2018 无障碍声明，并向用户收集缺少的法律字段。每个提示词均提供英文和西班牙文版本。

• conformance-wcagem（url*、tier、language）：网站 WCAG-EM 一致性评估阶梯式引导：快速筛查 → Agent 验证的代表性样本引导式评估 → 一致性报告所需信息。每个提示词均提供英文和西班牙文版本。

• blindfold-task（url*、goal*、kind、language）：蒙眼可用性测试 — Agent 仅感知无障碍树，并且只通过无障碍名称和键盘操作来尝试完成真实任务，逐步记录操作中的阻碍；最后给出 a11y_journey_verdict。这是其他无障碍工具都不具备的能力：基于任务的非视觉测试，Agent 就是屏幕阅读器用户。每个提示词均提供英文和西班牙文版本。

安装

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

适用于任何支持 MCP 的客户端 — Claude Code/Desktop、Cursor、Windsurf、VS Code、 Codex CLI、OpenCode、ZCode、Zed、Cline、Continue、Kimi Code……所有经验证的配置格式请参见 docs/clients.md。

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

也可使用 JSON 配置：

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

渲染类工具在 Playwright 存在时会使用它，并接受 browser 参数 （auto、chromium、firefox、webkit、chrome、msedge — 自动检测第一个可用的浏览器）。接受 auth_state（Playwright storage_state 路径），以审计登录后才能访问的页面。 其他所有功能均无需任何依赖。

技能

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

Agent 钩子 — a11ytoolkit init

自行读取 AGENTS.md 的 Agent 会获得重要规则 — 每次更改 UI 后，都要重新审计，再宣布工作 完成 — 以及精确的命令：

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

它还会打印 MCP 配置块和可选的技能安装步骤。 --check 会报告钩子是否存在（若不存在则退出码为 1 — 适用于 CI）。

语言 — 社区语言包

所有面向用户的消息（问题发现、修复建议、法律措辞）均存放在 语言包中 — 每种语言对应一个 JSON 文件，目前提供 es 和 en。添加一种语言只需提交一个文件的 PR：复制 _template.json，翻译时保留 {placeholders}，然后运行 python3 tests/test_locales.py，即可通过机械化验证 （键、占位符、复数规则、完整性）。采用与 axe-core 语言包相同的社区协作模式 — 并增加了 axe-core 不具备的验证功能。指南： docs/i18n.md。下游产品可以通过叠加品牌措辞，而无需分叉。

CLI — 相同引擎，一个命令

使用 pip install a11y-toolkit（或 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/medium
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 --entity "Acme" --url https://… --status partial --framework 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            # verifiable evidence 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
a11ytoolkit contrast-dom https://mysite --selector ".hero h1"  # auto-region pixel sampling
a11ytoolkit vpat pack.json --product "Acme" -o vpat.html      # VPAT 2.5 (WCAG) draft
a11ytoolkit earl --from-audit audit.json -o earl.json          # ACT Rules / EARL export
a11ytoolkit wcag3 --from-audit audit.json                      # WCAG 3 draft preview (no score)

覆盖范围：55 项 WCAG 2.2 A/AA 标准中的 51 项（93%）

有自动化检测信号	仅限人工检测（确实需要人工）
1.1.1, 1.2.2, 1.2.3, 1.2.5, 1.3.1–1.3.5, 1.4.1–1.4.5, 1.4.10–1.4.13, 2.1.1, 2.1.2, 2.1.4, 2.2.1, 2.2.2, 2.4.1–2.4.7, 2.4.11, 2.5.1–2.5.4, 2.5.7, 2.5.8, 3.1.1, 3.1.2, 3.2.1–3.2.4, 3.2.6, 3.3.1–3.3.4, 3.3.8, 4.1.2, 4.1.3	1.2.1（音频转录文本）、1.2.4（实时字幕）、2.3.1（闪烁检测）、3.3.7（重复输入）

4 项仅限人工检测的标准各自都有一个知识条目（a11y_criterion），告诉 Agent 如何逐项人工验证。每份报告都会打印这一边界。

a11y.es 背后的引擎

a11y.es 是一项面向西班牙市场的无障碍服务，运行着这个引擎。该服务使用独立代码库；本仓库则是引擎本身。

已在真实网页上验证

每月在真实网页上与 axe-core 4.10 进行基准测试（方法和结果）。在实际网站上进行基于任务的 Agent 基准测试，其中包括对西班牙最重要网页的分层抽样（方法和结果）。在 gov.uk 上发现了 axe 未报告的一项真实 WCAG 失败（蓝色按钮的对比度为 3.91:1，已人工验证）。也排除了我们自己的误报（隐藏的跳过链接、蜜罐字段、单上下文通用链接、图像替代文本 accname——每项都有回归测试样例）。

此外，还使用 W3C 官方 ACT 测试用例进行测试：scripts/act_report.py 会重新生成 EARL 实现报告——与其实现的每条已发布 ACT 规则均 100% 一致（355 个官方测试用例、20/20 条规则、零不一致；每次发布都会对照 w3c/wcag-act-rules 仓库进行验证；各规则的细分结果见 docs/act-report-summary.md）。WCAG 2.2 目录（86 项标准，A/AA/AAA）和 WCAG 3 成果注册表也同样依据 w3.org 的权威来源进行了验证（scripts/wcag22_ingest.py、scripts/wcag3_ingest.py）。

我为什么构建这个工具

自 2003 年以来，我一直在审查网站的无障碍性。二十年来，工具变得更快了，但问题依旧：同样缺失的替代文本、同样的键盘陷阱、同样会吞掉你劳动成果的表单。当 AI Agent 开始编写大多数网页时，审查能力的缺口不再是人手不足的问题，而成了基础设施问题。

于是，我构建了这款我一直希望审查时能用上的工具。不是又一个扫描器——扫描器已经够多了。而是一套工具包，能完成一半工作，明确说明检测范围的边界，并将剩余工作整理好，交给负责签字的人。上文提到的 gov.uk 问题并非合成基准测试案例：这个引擎发现了它，我也亲眼确认后才将其记录下来。

如果它能为你省下一个下午，请点个星——这确实能帮助下一位审查人员找到它。如果没有，请提交 issue 告诉我缺少什么。

内置诚实原则

每次审计都会说明：自动化可覆盖 55 项 A/AA 标准中的 93%（若计入 AAA 和确实需要人工的检查项，约占全部 WCAG 标准的三分之一）——其余部分需要人工处理。 audit-page 提示词和技能会让 Agent 使用人工检查清单检查它能检查的内容（键盘、焦点、缩放、已播报的错误）。这是筛选工具，不是最终判定。剩余的人工工作按标准项计价：MIN 23（阅读并确认）、MED 19（在浏览器中验证）、MAX 13（实际交互并作出判断）；完整表格。证据包是交给负责签字人员的交接材料，其中也包含屏幕阅读器转录文本，让审查人员了解盲人用户听到的内容。

安全性与范围

这是一个本地工具：以你的用户身份在你的计算机上运行。a11y_audit_url 仅接受 http/https（不接受 file://——本地 HTML 请使用 --file/html）。a11y_html_validate 在 html 模式下会将内容 POST 到 W3C 服务（url 模式只会共享 URL； 支持自托管的 vnu）。path/output_path 会读取/写入本地路径——请在你信任的 MCP 客户端中使用。

开发

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

没有 Playwright 时，tests/test_dom.py 会自动跳过。tests/test_solido.py 会检查设计 不变量（目录一致性、版本对齐、数量覆盖、恶意 HTML 模糊测试）。 发布：make release V=X.Y.Z——以原子方式升级版本、执行门禁、创建标签并推送。

路线图

近期已完成：支持 shadow DOM 和状态对比度的渲染审计、表单错误 测试与自动修复、键盘陷阱、无限滚动、重排、W3C Nu 集成、SARIF 和错误预算、证据包（规范已发布、 可自验证）、站点地图爬取、登录后审计、浏览器 自动检测、屏幕阅读器转录，以及按准则计算的工作量 估价。完整历史记录见变更日志。

接下来，大致按以下顺序进行：

• 证明交互机制：允许外部审计员的签名通过哈希引用证据包（采用他们的架构，我这边适配）
• 发布 CI 中针对真实页面运行的 axe-core 月度基准测试结果
• 将屏幕阅读器转录与 NVDA 和 VoiceOver 输出进行交叉核对
• 添加更多经过验证的客户端配置（JetBrains AI、Gemini CLI），并采用与 docs/clients.md 相同的处理方式

作者

Jesús Quintana Fernández (jquin.net)——SEO/GEO 顾问及 自 2003 年起从事网页无障碍实践的专业人士。MIT © 2026。