用途
Accessibility Audit 用于审查 UI 与标记的可访问性，并给出与 WCAG 对齐的具体修复建议，使所有用户都能感知、操作和理解界面。
何时启用
- 用户要求“accessibility”“a11y”“WCAG”或“screen reader support”
- 发布新页面或组件之前
- 审查表单、模态框或交互式 UI
- 设计或 UI 变更影响交互或内容之后
工作流程
- 定义范围——要审查的页面、组件或流程（例如登录表单、报表表格、模态对话框）。
- 检查每个领域——语义 HTML、键盘、标签与名称、颜色与对比度、动态内容、动效。使用下方检查清单。
- 记录发现——位置（组件/文件或元素类型）、WCAG 准则或原则、问题、影响、建议修复。严重程度：critical / major / minor。
- 建议修复——尽可能给出代码片段或属性修改。在原生 HTML 和正确 ARIA 足够时，优先使用它们而非自定义组件。
- 建议后续——建议使用自动化工具（如 axe、Lighthouse）和手动测试（仅键盘、屏幕阅读器）以获得更广覆盖。不要声称单次审查即可实现完整 WCAG 合规。
重点领域与检查清单
1. 语义 HTML 与结构
- 每页一个
<h1>；标题层级按顺序（不跳过 2 → 4）。 - 地标：适当使用
<main>、<nav>、<aside>、<footer>。 - 列表使用
<ul>/<ol>/<li>；表格使用<th>、scope，如适用使用 caption。 - 按钮是
<button>或<input type="submit">；链接是<a href="...">。不要在没有 role、键盘和焦点处理的情况下使用<div onclick>执行操作。 - 表单控件具有正确的 type 和分组（组使用
<fieldset>、<legend>）。
2. 键盘
- 所有交互元素可聚焦（除非为模态框管理，否则按钮/链接上不要用
tabindex="-1"）。 - 焦点顺序合乎逻辑（与视觉顺序一致或被显式管理）。
- 可见焦点指示器（outline 或自定义样式）；不要在没有替代方案的情况下用
outline: none移除。 - 无键盘陷阱：用户可以 Tab 出模态框和菜单；预期处 Escape 可关闭。
- 自定义组件（标签页、手风琴、菜单）可用键盘操作（Enter/Space 激活，如适用使用方向键）。
3. 标签与名称
- 每个表单输入都有可见的
<label>或aria-label；标签已关联（例如 for/id 或包裹）。 - 按钮和链接有清晰、唯一的名称（文本内容或 aria-label）。没有上下文的“Click here”或“Read more”不可用。
- 图片：有意义的图片 alt 描述内容；装饰性图片
alt=""或role="presentation"。 - iframe 和嵌入内容有 title 或 aria-label。
4. 颜色与对比度
- 文本满足对比度（例如普通文本 4.5:1，大文本 3:1；UI 组件 3:1）。对照背景检查。
- 信息不只靠颜色传达（例如必填字段、错误、状态）。同时使用图标、文本或图案。
- 焦点指示器可见，且不只依赖颜色变化。
5. 动态内容与焦点
- 出现或更新的内容（例如 toast、实时结果）会被播报：视情况使用
aria-live="polite"或aria-live="assertive"。 - 模态框和对话框：打开时焦点移入模态框；焦点被困在其中；关闭时焦点返回触发元素；按模式聚焦第一个可聚焦元素或显式 autoFocus。
- 状态被传达：展开/折叠（aria-expanded）、选中（aria-selected）、当前（aria-current）、禁用（disabled 或 aria-disabled）。
6. 动效
- 如果项目支持：尊重
prefers-reduced-motion（禁用或减少动画）。可选但推荐用于前庭敏感人群。
输出格式
对每个问题：
**[位置：文件或组件/元素]**
- **问题：** [哪里错了。]
- **WCAG / 原则：** [准则或原则，例如 1.3.1 Info and Relationships、2.1.1 Keyboard。]
- **影响：** [谁受影响以及如何受影响。]
- **建议：** [具体修复：代码或属性。]
- **严重程度：** Critical | Major | Minor
摘要：“已审查：[范围]。发现 X 个 critical、Y 个 major、Z 个 minor。建议自动化扫描（axe/Lighthouse）和键盘/屏幕阅读器测试。”
严重程度
- Critical——阻塞核心任务（例如无法提交表单、无法用键盘导航、必填字段无标签）。发布前修复。
- Major——显著障碍（例如对比度差、缺少标题、顺序混乱）。尽快修复。
- Minor——改进项（例如冗余标签、轻微对比度）。待办或修改该组件时修复。
好与坏示例
按钮：
<!-- BAD -->
<div onclick="submit()">Submit</div>
<!-- GOOD -->
<button type="submit">Submit</button>
图片：
<!-- Decorative -->
<img src="decoration.svg" alt="" role="presentation">
<!-- Meaningful -->
<img src="chart.png" alt="Bar chart showing revenue up 20% in Q4">
表单：
<!-- BAD -->
<input type="email" placeholder="Email">
<!-- GOOD -->
<label for="email">Email</label>
<input id="email" type="email" placeholder="you@example.com">
规则
- 不要声称完整合规——表述为“在审查范围内发现的问题”。建议自动化和手动测试以获得完整覆盖。
- 优先使用原生 HTML——使用
<button>、<label>、<main>等。当语义无法用 HTML 表达时使用 ARIA（例如自定义手风琴上的 aria-expanded）。 - 组件库——如果项目使用组件库（例如 Radix、MUI），注意库的无障碍模式（焦点陷阱、角色），并确保正确使用，而不是重新实现。
完成前检查清单
- 范围已明确定义
- 每个发现都有位置、问题、WCAG 引用、建议、严重程度
- 至少覆盖语义结构、键盘和标签/名称
- 建议后续（自动化 + 手动测试）
- 没有完整审计就不写“完全符合 WCAG 2.1 AAA”
反模式
| 反模式 | 更好的做法 |
|---|---|
| 只检查颜色对比度 | 覆盖键盘、标签、结构和动态内容 |
| 到处建议“添加 aria-label” | 优先可见标签和语义 HTML；必要时使用 ARIA |
| 忽略模态框中的焦点顺序 | 记录焦点陷阱和返回焦点行为 |
| 仅代码审查后就声称合规 | 建议 axe/Lighthouse 和真实辅助技术测试 |