accessibility-excellence

无障碍卓越实践

让所有人都能使用产品——包括仅使用键盘的用户、屏幕阅读器用户和低视力用户——对照 WCAG 检查点审查真实代码，并按优先级修复问题。**首要原则：优先使用语义化 HTML；只有原生元素无法满足需求时，才用 ARIA 补足。大多数无障碍问题，都是用错了元素来完成本该做对的事。**交付一份按优先级排列的审查结果和已实施的修复——不要长篇讲解合规要求。

何时使用 / 何时不使用

适用于：无障碍审查、WCAG 合规工作、键盘和焦点行为、ARIA 与屏幕阅读器支持、对比度问题、无障碍表单／模态框／菜单、替代文本和字幕。

以下情况请转交给其他技能：

• 设计配色方案本身（从设计之初就具备无障碍性的设计令牌）→ skills/frontend-design/color-system
• 深入处理减少动态效果和动画安全 → skills/frontend-design/interaction-physics（本技能负责审查；该技能负责实现动态效果层）
• 处理超出 ARIA 接线范畴的错误消息 UX → skills/frontend-design/error-handling-recovery
• 在提升无障碍性之前先重构杂乱的组件 → skills/frontend-design/component-architecture

步骤 0 — 检查代码库，只询问仍未明确的信息

1. 衡量当前 ARIA／语义化用法：搜索 aria-、role=、alt=、tabIndex、<main、<nav、<button、div／span 上的 onClick、outline: none、label／htmlFor。可点击的 div 与真正的按钮之比，是快速判断代码健康状况的指标。
2. 盘点交互界面：表单、模态框／对话框、菜单／下拉列表、标签页、工具提示、自定义控件（拖放、滑块、组合框）——这些是键盘／ARIA 风险最集中的地方。
3. 检查标题结构（一个 h1，级别不可跳过）、地标用法、<html lang>、跳过链接、图像替代文本覆盖情况和视频字幕。
4. 如果有可运行的环境，先运行自动化扫描（axe-core / Lighthouse a11y），建立基线——但要记住，它只能发现约三分之一到一半的实际问题，绝不能当作完整审查。
5. 记录组件技术栈：如果项目已使用无头无障碍库（Radix、React Aria、Headless UI、原生 <dialog>），采用这些库进行修复，通常优于自行实现。

**根据上下文选择 WCAG 目标——除非确实存在歧义，否则不要询问：**默认采用 WCAG 2.2 AA（法律／监管场景的常见标准——ADA、EAA、Section 508 均引用 AA）。政府／公共部门／教育领域 → 必须达到 AA，可考虑选用部分 AAA 标准。将 AAA 作为一揽子目标并不实际——仅在用户服务的主要受众为低视力人群或用户有此要求时，才应用具体的 AAA 标准（例如 7:1 对比度）。只询问用户：是否有合规截止日期／要求，以及当应用规模较大时哪些流程最关键。除此之外，说明“正在按照 WCAG 2.2 AA 进行审查”，然后继续。

工作流

1. 按照 POUR 检查点进行审查

使用 references/checkpoints.md 中的检查点表，逐一核查四项原则（进行审查时请阅读该文件）。需要遵循的 AA 关键阈值如下——这些是具体数值，不要估算：

• **对比度：**普通文本 ≥ 4.5:1；大号文本（≥24px，或加粗时 ≥18.66px）≥ 3:1；非文本 UI 组件和焦点指示器 ≥ 3:1。（AAA：7:1 / 4.5:1。）
• **目标尺寸（WCAG 2.2 AA）：**指针目标 ≥ 24×24 CSS px；44×44 是 AAA／移动端 HIG 的标准。
• **键盘：**所有操作都能通过键盘完成；所有地方都有可见焦点；没有 tabindex > 0；没有键盘陷阱（有意设置且可退出的模态框陷阱除外）。
• **闪烁：**任何内容每秒闪烁不超过 3 次。

2. 为每项发现评定严重程度

• 阻断级 — 某类用户无法完成核心任务（控件无法访问、焦点陷阱、结账表单没有标签、缺少键盘操作路径）。
• 严重 — 任务可以完成，但体验大幅受损（缺少播报、主要文本对比度不足、阅读顺序错误）。
• 中等 — 使用不便（链接文本含糊、重复播报、次要文本对比度轻微不足）。
• 轻微 — 细节优化（装饰性图片的替代文本冗长、缺少 aria-current）。

修复顺序：阻断级 → 严重 → 中等。列出按严重程度排序的清单；对于大型代码库，批量修复前请用户确认范围，否则直接继续。

3. 按以下决策规则修复

• 原生元素与 ARIA 改造： 如果 <div onClick> 的行为类似按钮、链接或复选框，就将其替换为原生元素——这一个改动即可同时修复角色、键盘操作和焦点问题。只有在确实无法使用原生元素时，才添加 role/tabIndex/键盘事件处理程序。
• 自定义控件与库： 对于模态框、菜单、组合框、标签页，优先采用项目现有的无头库或原生 <dialog>，而不是手动实现焦点陷阱和方向键逻辑。只有在项目没有相关库且不便添加库时，才手动实现。
• 对比度修复： 调整设计令牌，而非单个实例——找到定义未通过检查的颜色的位置，并在源头修复（如果需要重新设计调色板，请与 skills/frontend-design/color-system 协同）。
• 播报： 阻断任务的错误 → role="alert"；后台状态 → aria-live="polite"（区域必须预先存在于 DOM 中）；只有在导航级别的上下文变化时才移动焦点。
• 标签： 可见的 <label for> 优于 aria-label，后者优于 aria-labelledby 链；占位符绝不能作为标签。

规范模式（焦点陷阱、跳过链接、实时区域、字段错误关联、各类控件应支持的按键）：references/checkpoints.md。

4. 验证

对已修改的流程至少进行以下验证：完整的键盘操作检查（可到达、可操作、可见焦点、可退出）、如有条件则重新运行自动扫描、放大到 200%，并检查无障碍树以确认播报和名称。明确说明哪些内容无法验证（例如未在 VoiceOver/NVDA 上进行真实屏幕阅读器测试），并告知用户自行验证——绝不可声称符合超出实际检查范围的标准。

必需输出格式

交付以下两项：

1. 代码 — 已实施的修复（语义元素替换、标签、焦点管理、ARIA 关联、对比度设计令牌调整），并遵循现有组件约定。

2. 无障碍审计（Markdown）：

## Scope & target
Pages/flows audited; target: WCAG 2.2 AA; tools used (axe/Lighthouse/manual keyboard).

## Findings
| # | Severity | Issue | WCAG criterion | Location | Fix | Status |
| 1 | Blocker | Checkout "Pay" is a div, keyboard-unreachable | 2.1.1 | Checkout.tsx | native <button> | fixed |
| 2 | Serious | Placeholder-only labels on signup | 3.3.2 | SignupForm.tsx | <label for> added | fixed |
| 3 | Serious | Body text #9CA3AF on #F9FAFB ≈ 2.5:1 | 1.4.3 | tokens.css | darkened token to pass 4.5:1 | fixed |
| 4 | Moderate | No skip link | 2.4.1 | layout | added | fixed |

## Verified
- Keyboard walk-through: [flows] ✓
- Automated scan: [before → after issue count]

## Not verified — user action required
- Screen reader pass (VoiceOver/NVDA) on [flows]
- [anything environment prevented]

## Recurring root causes
[e.g. "clickable divs pattern-wide — adopt lint rule jsx-a11y"]

质量标准（交付前检查）

• 每项发现均注明 WCAG 标准和严重程度——不得凭感觉标记
• 所有阻断级问题均已修复，或已明确由用户拒绝修复
• 交付的代码中不得新增 <div onClick>、未提供替代样式的 outline: none、正数 tabindex 或将占位符用作标签的情况
• 对比度修复在设计令牌／源头完成，并使用计算值根据 4.5:1／3:1 验证
• 范围内每个模态框／菜单均已验证：焦点移入、正确陷阱、Escape 可用、焦点返回触发控件
• 每个表单控件都有程序化标签；每个错误都通过 aria-describedby 关联并可播报
• 标题层级有效；存在地标；已设置 lang；跳过链接是第一个可聚焦元素
• “未验证”部分如实列出未经测试的内容——不得夸大符合性

严格禁止：不要在已正常工作的原生元素上随意添加 ARIA；不要根据自动扫描声称“符合 WCAG”；不要通过臆造新的单次使用颜色来修复对比度；绝不要移除焦点轮廓，除非提供同等或更好的可见替代样式。

集成

• skills/frontend-design/component-architecture → 提供组件清单；修复应在共享组件中落实，以便同步生效。将反复出现的问题反馈为组件级规范。
• skills/frontend-design/color-system → 当对比度问题涉及多个令牌而非单个令牌时，负责重新设计调色板。
• skills/frontend-design/error-handling-recovery → 负责错误文案和恢复体验；本技能提供其必须遵循的 role="alert"/aria-invalid/焦点规则。
• skills/frontend-design/interaction-physics → 负责实现减少动态效果和闪烁安全；本技能负责审查。

参考资料

• references/checkpoints.md — 完整的 POUR 检查点表（含 WCAG 标准编号）、语义化 HTML 参考、键盘模式（焦点陷阱、跳过链接、各类组件的按键预期）、ARIA 模式集和常见 ARIA 错误、多媒体/内容规则，以及测试工具指南。在执行审计和编写修复时阅读。