需要做 WCAG 2.2 AA 无障碍合规测试时：用…

当你要验证 Web 应用对键盘用户和辅助技术可用、并满足 WCAG 2.2 AA / ADA / EAA / Section 508 等合规要求时，用自动化扫描加人工检查的组合方案。

适用场景

解决思路

1. 先检查 .agents/qa-project-context.md，若存在则以其为基础，跳过已回答的发现性问题。
2. 明确需求与合规目标：确认所需 WCAG 等级（A/AA/AAA，AA 是实际法律默认值）、适用法律（ADA、EAA/EN 301 549、Section 508、AODA）、是否需要维护 VPAT 或无障碍声明。
3. 评估现状与测试基础设施：是否做过审计及发现、设计系统是否含无障碍组件、CI 中是否已有自动化 a11y 测试、团队用哪些屏幕阅读器（VoiceOver、NVDA、JAWS、TalkBack）。
4. 牢记自动化只能发现 30-40% 的问题：axe-core 能查缺失 alt、低对比度、缺标签、无效 ARIA，但无法判断 alt 是否有意义、Tab 顺序是否合理、自定义组件是否可操作；且 axe 对 WCAG 2.2 的 2.4.11、2.5.7 无规则、2.5.8 仅部分覆盖，绿色 axe 不等于 2.2 AA 合规。
5. 优先使用语义化 HTML，ARIA 作为最后手段：原生 <button>、<nav>、<input>、<dialog> 自带语义、键盘行为和屏幕阅读器支持；<div role="button"> 还需 tabindex、Enter/Space 处理、焦点样式和 ARIA 状态。
6. 按影响顺序测试：先键盘（物理阻断用户）、再屏幕阅读器（错误播报）、最后自动化（机械性剩余问题）。
7. 把无障碍当作质量属性而非功能：每个新组件、每个 PR 都持续测试，避免事后改造（成本高 10-100 倍）。
8. 用真实辅助技术测试：DevTools 和 axe 扩展只是开发辅助，不能替代 VoiceOver（macOS/iOS）、NVDA（Windows）、TalkBack（Android），复杂自定义组件必须做人工 AT 测试。
9. 安装 @axe-core/playwright（4.11.x 线，跟随 axe-core 的 major.minor）。
10. 封装可复用的 checkAccessibility(page, testInfo, options) 辅助函数：过滤 WCAG 标签 ['wcag2a','wcag2aa','wcag22aa']，把完整结果 JSON 附加到测试作为审计痕迹，断言 violations.toHaveLength(0)。
11. 对每个关键页面和交互状态（模态框打开、菜单展开）循环运行扫描，而不只是默认加载状态。
12. 仅在附有文档化理由（跟踪 issue 或行内注释）时抑制规则，对不归你所有的第三方组件用 exclude 而非全局禁用规则。
13. 键盘导航审计：Tab 顺序符合从左到右、从上到下，无意外焦点跳转。
14. 键盘导航审计：所有交互元素可通过 Tab / Shift+Tab 到达。
15. 键盘导航审计：每个聚焦元素都有可见焦点指示，不得无替代地使用 outline: none。
16. 键盘导航审计：跳过链接可用——首次 Tab 显示“跳到主内容”，Enter 将焦点移到 <main>。
17. 键盘导航审计：Enter 激活按钮/链接，Space 激活按钮并切换复选框。
18. 键盘导航审计：Escape 关闭模态框、下拉、提示，焦点返回触发元素。
19. 键盘导航审计：方向键在标签页、菜单、单选组、树视图中导航。
20. 键盘导航审计：无键盘陷阱（模态对话框在关闭前有意困住焦点是允许的）。
21. 键盘导航审计：自定义组件（滑块、日期选择器、拖放）无需鼠标即可操作。
22. 屏幕阅读器测试：导航时播报页面标题。
23. 屏幕阅读器测试：标题形成可导航大纲（h1 → h2 → h3，不跳级）。
24. 屏幕阅读器测试：图片有描述性 alt 文本（装饰性图片用 alt=""）。
25. 屏幕阅读器测试：表单输入聚焦时播报其标签。
26. 屏幕阅读器测试：必填字段播报为必填，错误与对应输入关联。
27. 屏幕阅读器测试：实时区域播报动态内容（toast、加载状态）。
28. 屏幕阅读器测试：按钮/链接播报其用途（避免“点击这里”）。
29. 颜色对比度：正文文本至少 4.5:1（WCAG AA），大文本（18pt+ / 14pt+ 粗体）至少 3:1。
30. 颜色对比度：UI 组件和图形对象与相邻颜色至少 3:1。
31. 颜色对比度：信息不能仅靠颜色传达，需加图标、图案或文字。
32. 表单与错误无障碍：每个输入有可见 <label> 并通过 for/id 关联（placeholder 不是标签）。
33. 表单与错误无障碍：必填字段在视觉上和程序上都标明（required / aria-required）。
34. 表单与错误无障碍：错误用 aria-describedby 关联到输入，用 role="alert" 播报。
35. 表单与错误无障碍：提交失败时焦点移到第一个错误。
36. 表单与错误无障碍：相关字段用 <fieldset> 和 <legend> 分组。
37. 在可访问性树（角色、名称、ARIA 状态）上测试，而非 CSS。
38. 为表单编写可运行测试：错误通过 aria-describedby 关联、aria-invalid='true'、焦点在第一个错误。
39. 为模态/对话框编写可运行测试：aria-modal='true'、aria-labelledby、焦点被困、Escape 返回焦点。
40. 为交互状态编写可运行测试：打开的下拉（role="menu" 或 role="listbox"、aria-expanded）、加载骨架（请求期间 aria-busy='true'）、toast（aria-live='polite'）；点击触发状态变化并断言打开状态的 ARIA。
41. 为数据表格编写可运行测试：columnheader 角色、aria-sort 反映当前排序。
42. 为地标编写可运行测试：恰好一个 main，存在 banner、navigation、contentinfo。
43. 用 Playwright 的 toMatchAriaSnapshot() 捕获可访问性树为 YAML 并断言，捕捉视觉变化悄悄破坏语义的回归；将快照限定到稳定容器，避免整页快照因异步内容而 flaky。
44. 法律合规映射：ADA（美国，AA，诉讼）、Section 508（美国联邦，WCAG 2.0 AA，采购要求）、EAA（欧盟，EN 301 549 / WCAG 2.1 AA，2025 年 6 月 28 日起生效）、AODA（加拿大安大略，WCAG 2.0 AA，最高每日 10 万美元罚款）、EN 301 549（欧盟，WCAG 2.1 AA，公共采购）、Equality Act 2010（英国，WCAG 2.1 AA 指南）、ISO/IEC 40500:2025（国际，等同 WCAG 2.2）。
45. 面向美国或欧盟用户时，新开发以 WCAG 2.2 AA 为目标；WCAG 2.1 AA 是暂时无法达到 2.2 时的遗留最低要求。
46. WCAG 3 仍是工作草案（2026 年 3 月更新，约 174 项要求，候选推荐目标 2027 Q4，正式推荐不早于 2028），今天按 WCAG 2.2 规划，跟踪但不要据此测试。
47. 收集审计证据：每页自动化扫描结果、含测试者和日期的人工检查清单、含 AT 版本的屏幕阅读器结果、无障碍声明、企业销售用 VPAT、已知问题的修复计划。
48. 避免只做自动化测试：跑 axe 零违规就宣布无障碍，会漏掉 60-70% 真实问题；每次 axe 运行都要配键盘和屏幕阅读器清单，两者都作为发布门禁。
49. 避免 ARIA 滥用：给已有原生语义的元素加 role、aria-label、aria-describedby 导致双重播报；删除冗余 ARIA，使用原生元素。
50. 避免忽视键盘用户：仅鼠标/触摸可用的功能（仅点击的下拉、无键盘路径的拖放、仅悬停的提示）要提供键盘等价物并用 keyboard.spec.ts 覆盖。
51. 避免事后改造无障碍：产品“完成”后不可访问模式已固化到组件库，修复成本高 10-100 倍；把 axe 检查加入 Definition of Done，每个新组件合并前门禁。
52. 避免把无障碍当可选：因“没人抱怨”而降级 a11y 工单；把 a11y 作为发布阻断项，与功能 bug 同等严重级别，并在发布就绪检查中报告未解决 a11y 问题。
53. 避免只测快乐路径：只扫描默认页面状态会漏掉模态框、展开下拉、错误消息、加载骨架；在测试中驱动每个交互状态并重新扫描变化的 DOM。
54. 验证 axe 确实在扫描真实内容：指向一个已知有违规的页面（如临时移除 <label>）运行 npx playwright test e2e/tests/a11y/pages.spec.ts，测试必须失败并指出规则名；若仍通过说明 AxeBuilder 扫描了错误 DOM。
55. 验证键盘测试到达应用而非 404：运行 npx playwright test e2e/tests/a11y/keyboard.spec.ts 并打开跳过链接测试的 trace，首次 Tab 应落在跳过链接上。
56. 验证 CI 门禁会阻断：在分支上引入一个严重违规并推送，a11y 任务必须非零退出并使 PR 检查失败，之后回滚。
57. 抽查 ARIA 快照：先用 --update-snapshots 运行一次 toMatchAriaSnapshot，再不带该参数运行一次，第二次必须通过；若 flaky 则缩小快照范围到稳定容器。
58. 完成标准：axe-core 集成到 E2E 套件并在所有关键用户页面自动运行。
59. 完成标准：CI 报告零 critical/serious axe 违规，引入任何违规时阻断合并。
60. 完成标准：所有交互流程（表单、模态、下拉、导航菜单）的键盘导航端到端测试。
61. 完成标准：至少验证一个下拉/菜单（aria-expanded + role）、一个加载区域（aria-busy）、一个实时区域（aria-live）的交互状态 ARIA。
62. 完成标准：整个品牌色板按 WCAG AA 阈值验证对比度（正文 4.5:1，大文本和 UI 组件 3:1）。
63. 完成标准：为复杂自定义组件（日期选择器、数据表格、拖放）记录屏幕阅读器测试笔记，含所用屏幕阅读器及版本。

适用边界 · 注意事项

• 不适用于 cookie 同意/GDPR 合规——应使用 compliance-testing。
• 不适用于像素差异视觉回归——应使用 visual-testing。
• 不要用浏览器 DevTools 或 axe 扩展替代真实辅助技术（VoiceOver、NVDA、TalkBack）的测试。