a11y-audit

a11y-audit skill 概览

a11y-audit 适合用来做什么

a11y-audit 是一个面向无障碍审计的 skill，用于在 Web 代码库中发现、修复并验证 WCAG 2.2 Level A 和 AA 问题。当你希望 AI agent 不只是给出泛泛的无障碍建议，而是输出包含严重程度、WCAG 引用、结合框架的修复方案，以及开发者或合规相关方可以直接采取行动的报告时，a11y-audit skill 会特别有用。

最适合的用户和项目

a11y-audit skill 适合使用 React、Next.js、Vue、Angular、Svelte 或纯 HTML 的前端团队。它尤其适用于发布前检查、清理已知无障碍技术债、审查 pull request，或把无障碍检查加入 CI/CD 的团队。如果你只需要宽泛的 UX 评论、法律层面的认证，或不涉及代码级修复的手动屏幕阅读器测试，它的价值就相对有限。

这个 skill 的不同之处

这个 skill 不是围绕一次性 prompt 设计的，而是围绕 Scan、Fix、Verify 工作流组织的。它的配套文件包括用于扫描和对比度检查的 Python 脚本、示例输出、报告模板、CI/CD 指南、WCAG 2.2 参考、ARIA 模式、测试检查清单，以及特定框架示例。这让 agent 更容易生成可重复的审计输出，而不是给出模糊的“改进无障碍”建议。

采用前需要注意的事项

a11y-audit 可以帮助识别常见的代码级问题，例如缺少 alt 文本、点击处理器无法通过键盘访问、缺少标签、正数 tabIndex、表格表头问题、ARIA 误用，以及对比度不达标。它仍然应该与人工审查、浏览器测试、键盘测试和辅助技术检查配合使用。自动化和 AI 辅助审计无法完整验证用户意图、内容含义、焦点体验或真实的屏幕阅读器行为。

如何使用 a11y-audit skill

a11y-audit 安装方式与仓库路径

使用下面的命令从 GitHub repository 安装这个 skill：

npx skills add alirezarezvani/claude-skills --skill a11y-audit

该 skill 位于：

engineering-team/a11y-audit/skills/a11y-audit

安装后，先阅读 SKILL.md，然后查看 references/wcag-quick-ref.md、references/testing-checklist.md、references/framework-a11y-patterns.md、references/aria-patterns.md 和 references/ci-cd-integration.md。在让 agent 审计你自己的代码之前，先预览 expected_outputs/sample-scan-report.md 和 expected_outputs/sample-scan-output.json，了解高质量输出应该是什么样。

能产出更好审计结果的输入

要充分发挥 a11y-audit 的作用，应向 agent 提供真实组件文件、使用的框架、路由上下文、设计系统约束以及目标标准。较弱的 prompt 是：

“Check this page for accessibility.”

更强的 prompt 是：

“Use the a11y-audit skill to review these React components for WCAG 2.2 Level AA. Focus on keyboard access, form labels, image alternatives, table semantics, ARIA use, and color contrast. Return findings grouped by severity with file/line references, WCAG criteria, before/after code, and verification steps. Do not change our design-system Button API.”

这样可以给 skill 足够的上下文，让它优先处理真正需要修复的问题，并避免输出通用化的重写建议。

建议的 Scan、Fix、Verify 工作流

从一个小范围的重点扫描开始：一个页面、一个组件目录，或一个 pull request。如果你需要机器可读输出，可以要求 JSON 风格的发现项；如果是给人审阅，可以要求 markdown 报告。随后让 agent 先修复 critical 和 serious 问题，同时保留既有行为和框架约定。

一个实用流程是：

1. 针对明确路径运行或请求扫描，例如 src/components/UserCard.tsx。
2. 按严重程度和 WCAG criterion 审阅发现项。
3. 分小批应用修复：键盘支持、标签、语义、对比度、ARIA。
4. 让 skill 验证每个原始问题都已解决。
5. 使用 references/audit-report-template.md 中的结构生成最终报告。

使用内置脚本和参考资料

仓库包含 scripts/a11y_scanner.py 和 scripts/contrast_checker.py。当你希望在聊天会话之外进行可复现检查时，可以把它们作为实用工具或示例来使用。对比度示例展示了普通文本、大号文本和 UI 组件的精确比例以及通过/失败阈值。CI/CD 参考中包含一个 GitHub Actions 模式，可在存在 critical 无障碍违规时让 pull request 失败；如果你希望把 a11y-audit 用于 Frontend Development 工作流，以防止回归而不只是生成一次性报告，这一点很有价值。

a11y-audit skill 常见问题

a11y-audit 适合初学者吗？

适合，前提是你具备基本前端知识。这个 skill 会结合 WCAG 引用和具体修复方案解释违规问题，因此可以在审计的同时帮助学习。初学者应从一个组件开始，在跨整个代码库进行大范围修改前，先要求解释每个问题。

它比普通无障碍 prompt 好在哪里？

普通 prompt 可能只会生成检查清单或通用建议。a11y-audit skill 提供了更明确的工作流、严重程度模型、示例输出、报告格式、框架示例、ARIA 指南、对比度指南以及 CI/CD 集成说明。这种结构能帮助 agent 生成更容易审阅、实现和验证的输出。

它能认证 WCAG 合规吗？

不能。a11y-audit 可以支持 WCAG 2.2 Level A 和 AA 的修复工作，但不能替代正式无障碍审计、用户测试、法律审查或辅助技术验证。应把它视为面向开发者的审计与修复加速工具，而不是认证机构。

什么时候不应该使用 a11y-audit？

不要单独依赖它处理原生移动应用、PDF 无障碍、视频字幕工作流、法律合规声明，或需要人工测试的复杂辅助技术行为。它最擅长处理 Web UI 源代码，尤其是 HTML 和现代前端框架组件。

如何改进 a11y-audit skill 的使用效果

让 a11y-audit prompt 更具体

最常见的失败模式，是在缺少足够源代码上下文的情况下要求审计。应包含框架、文件路径、组件用途、相关 CSS 或 design tokens，以及修改是否必须保留 public APIs。如果涉及颜色，请提供前景色和背景色值，而不只是 class 名称。如果涉及表单，请包含验证行为和可见标签要求。

要求符合你代码库的修复方案

告诉 skill 你偏好的实现模式。例如：“Use our existing <Button> and <TextField> components”、“avoid adding ARIA when semantic HTML is available”，或“keep route behavior unchanged”。这可以减少过度修正，例如不必要地替换组件，或给语义化元素添加冗余 role。

不要停留在第一版答案

拿到第一份报告后，让 a11y-audit 根据原始 WCAG criterion 验证每项修复，并识别可能的回归。好的后续 prompt 包括：“Check keyboard order after these changes”、“Confirm the accessible names for all icon buttons” 和 “Review whether these ARIA attributes are necessary or harmful”。这会把 skill 从扫描器变成一个修复闭环。

添加项目专属护栏

如果要反复使用，建议维护一份简短的内部无障碍说明，包含你们支持的框架、设计系统组件、严重程度策略、浏览器支持范围和 CI 阈值。再结合仓库参考文件，例如 testing-checklist.md、wcag-22-new-criteria.md 和 ci-cd-integration.md。验收标准定义得越一致，a11y-audit 在 pull request、发布检查和长期前端质量治理中的价值就越高。