Communitygithub.com

WCAG 审计

对 Web 界面进行 WCAG 2.2 无障碍(a11y)审计,发现并修复无障碍问题。采用分阶段流程(静态源码扫描、真实浏览器运行时扫描(axe-core 和键盘检查)、对抗性验证、最小修复及可读报告),适用于用户要求审计、检查、审查或修复无障碍性、屏幕阅读器或键盘支持、颜色对比度、替代文本、标签或焦点时使用。

WCAG 审计 是什么?

WCAG Audit 是一个 AI 代理技能,用于对 Web 界面进行系统化的 WCAG 2.2 无障碍审计和修复。它通过一个分阶段的流程工作:第一阶段对 HTML/JSX/TSX/Vue/Svelte/Astro/MDX/Angular/CSS 等源码进行静态扫描,识别明显的无障碍问题;第二阶段则启动真实浏览器,结合 axe-core 和键盘交互检查,发现运行时问题(如计算后的对比度、焦点顺序、键盘陷阱等);第三阶段对每一个候选问题进行对抗性验证,通过追溯源码和渲染结果来确认、拒绝或标记为“需要验证”;第四阶段应用最小化的、保留视觉设计的修复,并提供修复解释;最后生成一份机器可读的报告(findings.json)和一份人工可读的总结报告(REPORT.md)。该技能适用于 Claude Code、Cursor 和 Codex 等支持工具调用的 AI 代理环境,其优势在于将自动化工具的覆盖率(约 30-50% 的 WCAG 失败点)与人工审查的严谨性结合,强调“已验证才发布”,并通过拒绝误报和提供行为保留的修复来建立用户信任。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mintwork/wcag-audit-skill/tree/HEAD/skills/wcag-audit

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

WCAG 审计 是做什么的?

你正在审计用户界面中的无障碍障碍并修复它们。残障用户无法像使用鼠标的健全用户那样绕过缺失的标签:将每个确认发现视为真实问题,它会阻碍一个真实的人。

目标: 一份已验证的发现列表,每个发现都与 WCAG 2.2 成功准则相关联,包含精确位置、证据和最小修复——然后应用并重新验证这些修复。

原则

  1. 未经验证,不得发布。 每个发现必须通过第三阶段。一份简短的真实问题列表胜过一份用户学会忽视的长列表。
  2. 优先使用原生 HTML。 最好的 ARIA 就是没有 ARIA。通过将 <div onClick> 改为 <button> 来修复,而不是添加 role、tabindex 和按键处理程序。
  3. 最小化、保留行为的修复。 只修改失败标记;不要重构或重新格式化周围代码。除非发现本身属于视觉问题(对比度、焦点环、目标大小),否则保持视觉设计不变。
  4. 绝不编造内容。 替代文本、标签和链接文本必须反映 UI 的实际含义。如果你无法判断图片传达了什么,将该发现标记为 needs_validation 并询问;不要编写 alt="image"。
  5. 自动化是下限,而非上限。 工具大约能发现三分之一到一半的 WCAG 失败点。报告未测试的内容(参见手动检查清单)。

设置

根据用户请求决定范围:整个仓库、一个目录、特定组件或一个 URL。然后检查工具:

npx --yes @mintwork/wcag-audit-skill --version        # CLI 可用?

如果 CLI 不可用(离线、无 Node),继续使用手动模式:自行阅读源代码,应用 references/RULES.md 中的规则列表,并跳过第二阶段,除非用户的环境提供了其他浏览器工具。

将所有产物写入仓库根目录下的 .wcag-audit/ 目录(创建它;建议将其添加到 .gitignore 中,如果项目提交了 CI 基线,则保留 .wcag-audit/baseline.json)。除非用户要求,否则不要写入其他位置。

工作流程

按顺序运行各个阶段。告知用户你处于哪个阶段。对于小范围(单个组件)各阶段可以简短,但不要跳过第三阶段。

第一阶段 — 静态扫描(源码)

npx @mintwork/wcag-audit-skill scan <path> --json -o .wcag-audit/static.json --fail-on none

即使项目提交了基线(.wcag-audit/baseline.json),也不要使用 --baseline:基线只允许 CI 忽略已知发现,但它们仍需要审查。

然后阅读 references/STATIC-SCAN.md,执行工具无法执行的审查:包装原生元素的自定义组件、条件渲染、设计系统属性(<Icon label=…>)、在 CSS-in-JS 中被移除或在另一个样式表中被替换的焦点样式(CLI 一次只检查一个文件中的 .css / .scss / .less 和 Tailwind 类)、仅颜色的状态,以及因展开属性或动态值而被扫描器跳过的内容。将这些作为候选发现添加,并设置 "source": "static" 和 "confidence": "medium"。

第二阶段 — 运行时扫描(真实浏览器)

仅当有 URL 可用或应用程序可以启动时才进行。查找开发命令(package.json 脚本、README),在后台启动它,等待其响应,然后:

npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# 更多页面/状态:
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none

扫描重要页面(首页、主要流程、表单、打开的模态框)——参见 references/RUNTIME-SCAN.md 了解需要覆盖的状态、SPA 等待和认证。将状态(打开模态框、提交空表单、深色模式、320px)放入配置中,并运行 scan --config .wcag-audit/config.json;对于需要登录的页面,使用用户的 --storage-state <file>,绝不要使用凭据。如果项目有 Storybook,也运行 scan --storybook storybook-static(或正在运行的 Storybook URL)以覆盖每个组件状态。每个运行时发现项的 sourceHint 都是一个搜索结果:在进行修复前确认它。运行时发现能捕获静态分析无法检测的内容:计算后的对比度、真实的 accessible name、焦点顺序、键盘陷阱、不可见的焦点。

第三阶段 — 验证(消除误报)

对于每个候选发现,遵循 references/VERIFICATION.md。尝试反驳它:在报告的行号处打开源码,追踪属性/插槽/展开运算符直到值被设置的位置,检查父级是否提供了标签,对于运行时发现,检查渲染后的 DOM。给出一个判定:

  • confirmed — 你追溯了它,它确实违反了准则。记录你是如何知道的。
  • needs_validation — 看似合理但你无法确定(例如替代文本质量、你无法看到的内容、你无法访问的页面)。不应用修复。
  • rejected — 已经反驳。记录原因(这教会用户应调整哪些规则)。

合并重复项:由静态扫描和运行时扫描报告的相同根本原因视为一个发现,包含两个位置。

第四阶段 — 修复

修复 confirmed 发现,按严重性从高到低排列,使用 references/FIX-PATTERNS.md 中的模式。对于每个修复:

  1. 进行满足准则的最小更改,使用框架的习惯用法(React 中的 htmlFor,Vue 中的 :aria-label 等)。
  2. 用一两句话解释:什么问题、影响谁、改变了什么。
  3. 在更改可见 UI 或文字(对比色、新的可见标签、链接文本)之前询问,除非用户已经同意。

机械性发现(html-lang 修复、meta-viewport-zoom、aria-attr-valid 拼写错误)可以通过 CLI 修复:运行 scan <path> --dry-run,向用户展示 diff,然后运行 scan <path> --fix。只有在你知道页面语言后,才使用 --lang <code> 添加缺失的 lang。

然后机械地重新验证:

npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json   # 开发服务器仍在运行

verify 命令如果仍有任何问题或修复引入了新发现,则会以非零退出。持续迭代,直到已确认的发现得到解决,或者你已解释为何无法在代码中修复(例如需要用户提供的字幕内容)。运行项目自身的测试/代码检查。

第五阶段 — 报告

编写符合 assets/report-schema.json 的 .wcag-audit/findings.json 并验证它:

node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json

然后编写 .wcag-audit/REPORT.md 并向用户提供一个简短总结,遵循 references/REPORTING.md 中的格式:按严重性和判定的计数、已修复的内容、需要用户输入的内容、未测试的内容。

严重性

严重性含义示例
critical对某些用户完全阻塞任务未标记的表单字段、作为提交唯一方式的 <div onClick>、键盘陷阱、禁用缩放
serious重大困难或信息缺失低对比度的正文文本、缺少页面语言、无名称的链接
moderate摩擦、混淆结构跳过的标题级别、上下文中冗余或模糊的链接文本
minor精细打磨、最佳实践模糊的替代文本、autofocus

严重性反映了在该特定 UI 中对用户的影响,而不是规则的默认值:页脚中未标记的搜索框比登录页面上的未标记密码字段严重程度要低。

反模式(不要做)

  • 不要添加与可见文本重复或矛盾的 aria-label(违反 WCAG 2.5.3)。
  • 不要在使用 <button> 有效时添加 role="button" + tabindex="0"。
  • 不要通过更改视觉大小来“修复”标题顺序问题;应更改级别并保留 CSS。
  • 不要为了静默扫描器而将告知性图片的 alt 设为空字符串。
  • 除非在注释旁边有书面理由,否则不要抑制发现(wcag-audit-ignore)。
  • 不要声称 WCAG“合规”——自动化工具加代理审核只能显示失败点,不能证明符合性。
  • 不要修改生成、供应商或 node_modules 代码;修复源组件。

文件

相关技能