accessibility

无障碍 — Review Skill

面向 Web UI 的无障碍审查视角，以 W3C Web Accessibility Initiative（WAI）为依据。 目标是 WCAG 2.2 一致性等级 AA——这是 EN 301 549、ADA、 《康复法案》第 508 条和《欧洲无障碍法案》背后的技术标准。

基于。 architecture-and-design，以及 react、angular 或 vue，用于了解各项规则背后的框架机制。只有当任务涉及相应层面时，才加载相关技能；如果没有加载，请依据常识应用该层面的要求，不要因此阻塞工作。

本 SKILL.md 可独立使用：以下 规则集 是完整且可执行的检查清单。每个 references/<topic>.md 文件都包含相应主题组的原理说明和 ❌ / ✅ 代码示例， references/worked-example.md 则提供完整的审查流程；运行环境允许时，可打开这些文件深入了解。

WCAG 按四项原则组织——POUR：

原则	内容必须满足
可感知	感官能够获取：提供文本替代内容、字幕、足够的对比度，以及调整样式后仍能保留的结构。
可操作	可通过键盘及其他输入方式使用，提供充足时间、避免引发癫痫的刺激，并确保导航清晰。
可理解	内容易于阅读且行为可预测，并提供标签和错误帮助。
稳健	现在以及未来的浏览器和辅助技术都能正确解析。

---

如何使用此 Skill

选择与任务匹配的模式，并按顺序完成步骤。

模式	步骤
生成 — 构建组件或页面	1. 优先使用原生元素。 2. 为每个控件提供无障碍名称。 3. 确认键盘操作路径，并确保焦点指示器可见。 4. 运行 axe 检查。 5. 按照检查清单逐项检查规则集。交付前修复所有未通过项。
审查 — 检查拉取请求或差异	1. 根据差异检查规则集。 2. 对每个未通过项按下方的输出格式写一条发现；在能明确问题时注明 WCAG 成功准则。 3. 按顺序排列发现：先列 must-fix，再列 consider。 4. 如果没有未通过项，用一行说明即可。不要臆造发现。
审计 — 评估现有界面	1. 运行自动化检查（axe-core）。它们能发现约 30% 到 40% 的问题。 2. 仅使用键盘走查每条关键路径。 3. 使用屏幕阅读器检查关键流程（Chrome 配合 NVDA 或 JAWS，Safari 配合 VoiceOver）。 4. 将每项发现对应到一条 WCAG 2.2 AA 准则。

先按以下顺序排查最常见的实际问题：文本对比度过低、图片缺少 alt、链接和按钮没有无障碍名称、表单字段没有标签，以及缺少 lang。这些问题占实际环境中大多数无障碍缺陷（WebAIM Million）。

输出格式

每行写一条发现：

<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>. [WCAG <criterion>]

• <severity> 为 must-fix（未达到 WCAG 2.2 AA 准则，或阻碍用户使用）或 consider（AA 标准以下的实际障碍，或稳健性风险）。
• <topic> 为规则集中的主题标识（structure、keyboard-focus、forms 等）。
• [WCAG <criterion>] 为可选项——当某条准则明确规定了要求时添加，例如 [WCAG 1.4.3]。

所有模式通用规则

• ARIA 五条规则中的第一条（w3.org/TR/using-aria）：如果某个原生元素已经具备相应角色、状态、键盘行为和焦点管理，就使用该元素。错误的 ARIA 不如不用 ARIA。
• 无障碍是正确性要求，不是功能特性，也不是事后补做的工作。
• 除非产品负责人设定了更高标准，否则目标为 WCAG 2.2 AA 级别。

---

规则集

structure → references/structure.md

• 交互元素使用原生元素——<button> / <a href> / <input>——而不是带有事件处理器的 <div>。链接用于导航；按钮用于执行操作；两者不可相互冒充。 [WCAG 4.1.2, 2.1.1]
• 每页只有一个 <h1>；标题层级每次递进一级，不得为了样式而跳过级别。[1.3.1, 2.4.6]
• 区域使用地标元素（header / nav / main / aside / footer）包裹；每页恰好有一个 <main>；同类型地标使用有区分度的 aria-label。[1.3.1]
• 列表标记为列表；表格数据使用带有 <th> 和 scope 的 <table> 标记。
• 在 <html> 上设置 lang（以及任何外语元素上）；每个页面都有唯一且具有描述性的 <title>。[3.1.1, 2.4.2]
• 打开新标签页或下载文件的链接会在可见文本或屏幕阅读器文本中说明这一点。
• 提供帮助机制（联系链接、聊天入口）的每个页面上，该机制都位于相同位置。[3.2.6]

names-aria → references/names-aria.md

• 每个交互元素都有可访问名称（可见文本、aria-label 或 aria-labelledby）——包括仅含图标的按钮。当可见标签为文本时，可访问名称 必须包含该文本。[4.1.2, 2.5.3]
• 单独阅读链接和按钮文本时也能理解其含义——不得只写“点击此处”/“阅读更多”。[2.4.4]
• 不覆盖原生角色，也不为元素添加已有的角色；ARIA 状态（aria-expanded、aria-selected、aria-checked、 aria-pressed）与 UI 保持同步。
• 自定义控件（菜单、组合框、标签页、折叠面板、滑块）遵循其 ARIA APG 模式——包括角色和键盘交互。
• 模态框使用 role="dialog"（或 <dialog> + showModal()），并设置 aria-modal="true" 和指向其标题的 aria-labelledby；按 Esc 可关闭；背景设为 inert。
• aria-hidden 子树中不得包含可聚焦元素。

keyboard-focus → references/keyboard-focus.md

• 所有交互元素都可仅使用键盘访问和操作；任何步骤都不会导致焦点陷阱。[2.1.1, 2.1.2]
• Tab 顺序遵循阅读顺序；不得使用正值 tabindex；DOM 顺序与视觉顺序一致（不得使用 Tab 键和阅读顺序无法跟随的 CSS order/定位）。[2.4.3, 1.3.2]
• 所有滑动 / 捏合 / 路径手势以及所有拖放操作，都有单指替代方式。[2.5.1, 2.5.7]
• 所有时间限制都会在到期前发出警告，并且可以延长或关闭。[2.2.1]
• 使用 :focus-visible 样式设置可见焦点指示器，对比度为 3:1；任何 outline: none 都必须有同等或更好的替代样式。[2.4.7, 1.4.11]
• 固定页眉或页脚不得遮挡获得焦点的元素。[2.4.11]
• “跳转到主要内容”链接是第一个可聚焦元素，并在获得焦点前视觉隐藏（不得使用 display: none）。[2.4.1]
• 客户端路由切换时，将焦点移至新视图（其 <h1> 或 tabindex="-1" 容器）；对话框会锁定焦点，并在关闭时将焦点恢复到触发元素。
• 复合控件（网格、列表框、工具栏、标签列表）使用 roving tabindex 或 aria-activedescendant——仅一个 Tab 停靠点，内部使用方向键导航。
• 交互目标至少为 24×24 CSS px，或周围留有 24 px 的清晰间距。[2.5.8]

forms → references/forms.md

• 每个字段都通过程序化方式关联 <label>（for/id，或由标签包裹）；占位符不能替代标签。[1.3.1, 3.3.2]
• 相关字段使用 <fieldset> + <legend> 分组；说明和格式提示应置于字段之前，并通过 aria-describedby 关联。[1.3.1, 3.3.2]
• 出错时：以文本说明错误，通过 aria-describedby 关联，在字段上设置 aria-invalid，并提供建议的修正方式——不能只依靠颜色。[3.3.1, 3.3.3, 1.4.1]
• 提交失败时，应在表单顶部显示错误摘要（包含一个标题，并为每个错误提供一个指向对应字段的链接），且将焦点移至摘要。
• 不要通过禁用提交按钮来表示表单无效——允许提交，并显示摘要。
• 必填字段应在可见标签中注明，并设置 aria-required，不能只用星号表示。[3.3.2]
• 身份和联系字段应设置 autocomplete 令牌；同一流程中不要重复询问相同信息。[1.3.5, 3.3.7]
• 登录应允许粘贴和使用密码管理器，设置 autocomplete="current-password" / "one-time-code"，并提供通行密钥或电子邮件链接方式；拼图 CAPTCHA 应提供无需认知能力的替代方式。[3.3.8]
• 对提交后会产生法律、财务或破坏性后果的操作，应可撤销、经过检查，或在提交前要求确认。[3.3.4]

perceivable → references/perceivable.md

• 每张有意义的图片都应有能传达其含义的 alt；装饰性图片的 alt=""；带标签控件中的图标应设置 alt="" 或 aria-hidden。 [1.1.1]
• 视频应配字幕；音频应提供文字稿；自动播放超过 3 s 的音频应提供暂停/停止控件和独立音量控制。[1.2.1, 1.2.2, 1.4.2]
• 含义不能只通过颜色、形状或位置来传达。[1.4.1]
• 正文文本对比度至少为 4.5:1；大号文本（约 24 px，或 19 px 粗体）、UI 组件边界和焦点指示器的对比度至少为 3:1。[1.4.3, 1.4.11]
• 在 200% 缩放下可用；重排至 320 CSS px 时不会丢失内容或功能；可适应文本间距覆盖设置；不锁定为单一方向。[1.4.10, 1.4.12, 1.3.4]
• 遵循 prefers-reduced-motion 设置（无视差效果、自动播放视频或大幅运动）；每秒闪烁不超过三次。[2.3.1]
• 移动、滚动或自动更新超过 5 s 的内容应提供可见的暂停/停止/隐藏控件。[2.2.2]
• 强制颜色模式可正常使用：不能通过 background-image 传达含义；图标应使用 currentColor 或系统颜色绘制；应在 @media (forced-colors: active) 下测试。
• 悬停或聚焦时显示的内容应可关闭、可悬停，并持续显示直至关闭。[1.4.13]

live-regions → references/live-regions.md

• 异步结果（toast、验证摘要、结果数量、保存状态）应通过 live region 播报——错误使用 role="alert"，其他情况使用 role="status" / aria-live="polite"。[4.1.3]
• 更新前，live region 元素应已存在于 DOM 中——更新其文本；不要同时插入 region 和其中的消息。
• assertive / alert 仅用于真正的错误；对于关键消息，应将焦点移至该消息，而不是依赖播报。
• 客户端导航应更新 <title>，并将焦点移至新视图（参见 keyboard-focus）。
• 加载状态应以文本播报，不能只显示加载动画；加载完成后也应进行播报。[4.1.3]

测试 → references/testing.md

• 在 CI 中运行自动化检查：axe-core，以及 eslint-plugin-jsx-a11y（React）、angular-eslint 模板无障碍规则（Angular）或 eslint-plugin-vuejs-accessibility（Vue）——这些工具大约能发现三分之一的问题。
• 仅使用键盘（Tab、Shift+Tab、Enter、Space、方向键、Esc）走查每条关键路径。
• 使用屏幕阅读器测试关键流程——Chrome 配合 NVDA 或 JAWS，Safari 配合 VoiceOver；并在浏览模式和表单／焦点模式下测试组件。
• 在浏览器缩放至 400% 且操作系统文本大小调大的情况下测试，而不只是 200%。[1.4.10]
• 单元测试按角色和可访问名称查询元素（getByRole('button', { name: 'Save' })）。
• 在设计系统中统一检查对比度，而不是逐个功能检查。
• 自定义组件应基于可访问的基础组件（Radix、React Aria、Angular CDK）构建，而非从零开始实现。

---

限制

本技能涵盖 Web UI 的无障碍性，不涵盖：

• ATAG（创作工具）或 UAAG（浏览器）——这些是面向工具和用户代理开发者的 WAI 标准，而非面向应用开发者。
• 原生移动端无障碍功能（iOS UIAccessibility、Android 无障碍 API）和文档无障碍功能（PDF、Office）。
• 法律建议——符合规范的策略和法律风险应由法律顾问处理。
• 超出 AA 的 WCAG AAA 级标准，以及仍在制定中的 WCAG 3 和认知无障碍（COGA）工作——请持续关注，但不要基于草案构建。WCAG 3 可能会 以感知模型（APCA）取代 4.5:1 的对比度要求；在此之前，2.2 中的数值仍是要求。
• 满足感知要求的 CSS——对比度令牌配对、prefers-reduced-motion、强制颜色、rem 字号——请参阅 styling-and-design-tokens。
• 根据区域设置设定 lang 和 dir，并隔离双向文本——请参阅 i18n-and-localization；本技能负责规定 lang 和语言片段的要求。
• 各规则背后的框架机制（useId、refs、portals；CDK a11y 包；SFC 模板）——请参阅 react / angular / vue。

---

参考资料

本技能与以下内容配合使用：

• architecture-and-design——其中的 frontend-practices 规则只检查语义元素和标签，并将焦点、ARIA、实时区域及无障碍测试交由本技能处理。
• react——React 机制：useId、基于 ref 的焦点管理、createPortal、基础组件库（Radix、React Aria）。
• angular——Angular 机制：CDK a11y 包（cdkTrapFocus、FocusMonitor、LiveAnnouncer）和 template/accessibility lint 规则。
• vue——Vue 机制：语义化 SFC 模板、`useId()`` 和基础组件库（Reka UI、Headless UI）。
• styling-and-design-tokens——提供满足本技能可感知性规则的令牌和查询（每种主题的对比度配对、prefers-reduced-motion、强制颜色、基于 rem 的字号）； 本技能决定要求，该技能决定 CSS。
• i18n-and-localization——根据区域设置设定 lang 和 dir，并隔离双向文本；本技能负责规定 lang 和语言片段的要求。

规范性资料：

• WCAG 2.2 — w3.org/TR/WCAG22
• WAI-ARIA 1.2 和 ARIA 创作实践指南 — w3.org/WAI/ARIA/apg
• ARIA 使用指南（五项规则）— w3.org/TR/using-aria
• HTML 中的 ARIA（哪些 ARIA 属性可用于哪些元素）— w3.org/TR/html-aria

实践者参考资料：

• MDN Accessibility — 了解 ARIA 和 HTML 在浏览器中的行为
• The A11Y Project 检查清单 — a11yproject.com/checklist
• WebAIM — 对比度检查器、年度 WebAIM Million 报告、屏幕阅读器调查
• GOV.UK Design System — 经用户测试的组件和模式说明、错误摘要模式

如有冲突，本技能决定无障碍要求，框架技能决定满足要求所用的 API。