Accessibility Audit

技能简介

想象一下：你花了一整天写了一个漂亮的表单页面，自认为代码无懈可击，结果用户测试时一位视障人士用屏幕阅读器却完全无法操作——导航跳来跳去，提交按钮没有标签，对比度低得连“确认”两个字都看不清。更扎心的是，这很可能违反法规，让你面临合规风险。这绝不是少数用户的边缘需求——全球超过10亿人存在某种形式的残疾，而良好的无障碍设计能让所有人的体验都更好。

Accessibility Audit 正是为了解决这个问题而生的 AI 技能。它是一个遵循 WCAG 2.2（Web 内容无障碍指南） 的全自动化审计工作流。你只需要把代码交给 AI 编程助手，这个技能就会自动扫描 HTML、CSS、JavaScript 和组件代码，检测出三大类最核心的无障碍问题：颜色对比度不足、键盘导航缺失或错误、屏幕阅读器兼容性缺陷。它会输出具体的检测报告，并直接给出可复制的修复代码建议。不再需要手动翻规范、反复测试，也不需要在“等测试发现”和“自己逐行审查”之间纠结——Accessibility Audit 把无障碍变成了编码过程中的即时反馈。

为什么它值得关注？因为无障碍从来不是一个“加个 aria 标签”就能解决的事。它涉及设计、布局、交互、语义、动态内容等多个维度，而且 WCAG 每两三年就会更新标准。这个技能已经内置了 WCAG 2.2 的最新要求（比如焦点顺序、拖放操作的无障碍），并且可以不断更新规则库。你不需要成为无障碍专家，也能交付真正面向所有人的产品。

核心优势

• 覆盖最常踩的“三大坑”
  颜色对比度不足（尤其是浅色背景上的灰字）、键盘焦点丢失（Tab 后找不到元素）、屏幕阅读器内容无法理解——这三个问题占据了实际项目中 80% 以上的无障碍 Bug。Accessibility Audit 会逐一检查每个交互元素，并对每个问题提供 WCAG 等级（A/AA/AAA）的详细说明，让你知道该优先修哪个。

• 报告即修复，一步到位
  很多工具只告诉你“有错”，但你要自己翻规范查写法。这个技能不一样：它会针对每个问题生成直接可用的代码补丁。比如检测到按钮没有 aria-label，它会根据上下文推断按钮功能并生成建议；检测到对比度不足时会推荐新的色值。你只需确认后粘贴，就能快速修掉大部分问题。

• 支持动态内容和单页应用（SPA）
  传统静态分析工具面对 JavaScript 生成的内容常常束手无策。Accessibility Audit 设计时考虑了现代前端框架（React、Vue、Angular 等），它会分析组件的状态变化、条件渲染和焦点管理逻辑，不仅检查静态 DOM，还能模拟动态交互场景（比如弹窗出现、列表加载）下的无障碍状况。

• 与你的工作流无缝集成
  通用技能意味着你可以在 Claude Code、Cursor、GitHub Copilot 等任何主流 AI 编程助手中使用。不需要切换工具，不需要额外安装笨重的插件。在写代码的同时运行一次审计，几秒钟内就能拿到结果。你甚至可以把审计结果作为 PR 门禁的一部分——让不符合无障碍标准的代码无法合并。

• 开源且持续更新
  这个技能的规则库托管在 GitHub 上，完全开源，任何人可以审查、改进和扩展。WCAG 2.2 是 2023 年发布的，里面包含了新的“焦点顺序（Focus Order）”等成功标准，而 Accessibility Audit 已经第一时间适配。社区也会不断贡献新的检测规则，让你始终站在无障碍前沿。

主要功能

功能	说明
颜色对比度检测	检查文本、图标和交互元素的对比度是否符合 WCAG AA/AAA，自动计算推荐色值并生成 CSS 修复。
键盘导航审计	验证所有可交互元素是否可聚焦，焦点顺序是否逻辑正确，是否存在“键盘陷阱”（焦点卡住无法脱离）。
屏幕阅读器语义分析	检查 ARIA 属性使用是否正确（如 role、aria-label、aria-describedby），同时识别隐藏内容是否被不当暴露。
表单与输入无障碍	检测表单标签是否与输入控件关联，错误提示是否有屏幕阅读器可感知的方式，以及必填字段标记。
动态内容通知	对于通过 AJAX 或框架状态更新的区域，检测是否使用了 aria-live 等实时区域通知屏幕阅读器。
图像与媒体替代文本	检查 img、svg、video 等元素是否包含 alt 或等效文本，并评估替代文本的描述质量（过于冗余或缺失）。
焦点管理与弹窗/遮罩层	测试弹窗打开时焦点是否被捕获在内部，关闭后焦点是否回到触发元素——这是 WCAG 2.2 新增的重点。
合规报告生成	输出结构化的 JSON/Markdown 报告，包含问题描述、严重等级、受影响的代码片段和推荐修复方案。

如何获取与安装

Accessibility Audit 是一个通用开源技能，可以配置到多种 AI 编程助手中。你不需要安装单独的软件，只需要将技能的工作流规则（通常为提示词集合或配置文件）导入你的助手。以下是两种最常见的使用方式：

方式一：用于 Claude Code（推荐）

1. 获取规则文件
   访问 GitHub Topics 页面：github.com/topics/web-accessibility
   在列表中查找“accessibility-audit-workflow”或类似仓库，找到最新的 accessibility-audit.md 文件（或 .prompt 文件）。

2. 安装到 Claude Code

   • 如果你使用的是 Claude Code 插件市场，可以通过以下命令直接安装（假设插件已发布）：

     /plugin install accessibility-audit
     

   • 如果未发布，可以将规则文件内容保存为 accessibility-audit.prompt，然后通过 Claude Code 的 --prompt 参数加载：

     claude code --prompt ./accessibility-audit.prompt
     

   • 或者，将规则内容添加到项目根目录的 .claude/instructions.md 文件中，让 Claude 在每次会话中自动加载该技能。

3. 验证安装
   在对话中输入“运行无障碍审计”，如果 Claude 开始分析代码中的无障碍问题，则说明安装成功。

方式二：用于 Cursor（通过 .cursorrules）

1. 从 GitHub 下载 accessibility-audit.cursorrules 示例文件（或从上述 Topics 页面的仓库中找到）。

2. 将该文件放置在你的项目根目录，并重命名为 .cursorrules。

3. 在 Cursor 中打开项目，AI 会主动参考该文件来提供无障碍检测。你也可以在 Cursor 的设置中手动添加规则路径。

4. 使用示例命令触发审计（在对话中描述想要检查的代码区域）：

   请对当前文件执行无障碍审计，重点检查颜色对比度和键盘导航。
   

方式三：用于 GitHub Copilot（通过自定义指令）

1. 在仓库根目录创建 .github/copilot-instructions.md 文件。
2. 将 Accessibility Audit 的规则内容复制进去，保存后提交。
3. Copilot 在代码补全和 Chat 中会优先遵循这些无障碍规范。

注意：不同助手的配置语法略有差异，请以对应工具的官方文档为准。如果你使用的工具不支持自定义规则，也可以直接将规则内容复制到对话的初始提示中（作为 system prompt 的一部分）。

适用场景

• 前端组件开发与重构：在写组件时边写边审计，确保每个按钮、表单、导航都符合无障碍标准，避免在后期返工。
• 合规性审查（特别是政府或金融项目）：许多国家和地区的法律（如美国的 Section 508、欧盟的 EN 301 549）要求必须达到 WCAG AA。Accessibility Audit 可以快速扫描代码库，输出合规报告。
• 设计系统的无障碍验收：当你构建或维护一个 UI 组件库时，用这个技能统一检查所有组件的渲染结果，保证设计 tokens 中的颜色对比度达标、ARIA 模式正确。
• 第三方依赖的无障碍评估：引入新的 npm 包或 UI 框架后，用审计扫描其输出的 DOM，避免第三方库引入无障碍漏洞。
• 代码审查流程自动化：在 PR 触发时，通过 CI/CD 调用 AI 助手运行无障碍审计，自动在 PR 评论中列出问题，减少人工审查负担。

小贴士

1. 不要一次性审完整项目。先针对一个页面或组件运行，否则报告会很长，难以消化。优先处理与用户交互最频繁的模块（表单、导航、模态框）。
2. 始终结合手动测试。AI 能检测出大部分机械性问题，但对于“用户是否真的感到困惑”这种判断，还是需要人工测试，尤其是用屏幕阅读器和键盘真实操作一遍。
3. 将无障碍规则融入团队规范。安装成功后，把 .cursorrules 或 instructions.md 一起提交到版本库，让所有成员在同一个项目中自动遵守无障碍标准，而不是依赖个人自觉。

---

免责声明：技能效果可能因版本和配置而异，请以官方文档为准。无障碍合规涉及法律和用户体验的多重因素，建议最终验证仍需结合专业工具（如 axe、WAVE）和真实用户测试。