web-accessibility

Web 无障碍

无障碍的成功标准是残障人士能否成功完成任务并从失败中恢复，而不是工具评分。实现前先定义可观察的要求，在合适的情况下优先采用平台原生行为，并在受支持的浏览器和辅助技术（AT）环境中收集有明确范围的证据。

工作流

1. 定义任务、用户、受支持的浏览器/AT、输入方式和失败恢复方式。先从 assets/acceptance-criteria-template.md 开始。
2. 优先选择原生 HTML。加载 references/semantics-and-names.md，了解结构、原生控件、无障碍名称、描述和动态更新。
3. 明确每一种交互状态：触发方式、角色/名称/状态/值、键盘操作、焦点进入/离开/返回、指针替代方式、错误和可见反馈。加载对应的模式参考文档。
4. 使用 references/visual-input-and-motion.md 进行视觉和输入适配设计；区分 WCAG 要求、产品目标和例外情况。
5. 只有在契约定义清楚后才开始实现。对于自定义复合控件，应先评估所选技术栈中成熟的原生组件或维护中的组件；APG 示例只能提供参考指导，不能证明其适合用于生产环境。
6. 使用 references/testing-and-evidence.md 以及设计、实现和发布模板进行验证。记录工具、版本、范围、手动任务、实际浏览器/AT 组合、失败情况，以及受阻或不适用的项目。
7. 不要根据自动化扫描给出 WCAG 合规性或笼统的无障碍结论。合规性声明需要在此技能自动判断范围之外进行完整且范围明确的评估。

按需加载

需求	加载
标准状态、来源权威性或精确链接	references/source-index.md
原生语义、标签、无障碍名称、地标、实时更新	references/semantics-and-names.md
Tab 顺序、焦点可见性、焦点陷阱、焦点恢复、路由更改	references/keyboard-focus-and-routing.md
标签、验证、可恢复错误、身份验证	references/forms-errors-authentication.md
模态对话框、展开/折叠内容、响应式导航	references/dialogs-disclosures-navigation.md
标签页、组合框、列表框、网格、菜单及其他复合控件	references/composite-widgets.md
对比度、重排、缩放、目标、拖动、动态效果、媒体	references/visual-input-and-motion.md
自动化检查、手动测试协议、AT 矩阵、证据	references/testing-and-evidence.md
框架或技能边界	references/routing.md
验证常见结果，但不声明合规性	references/outcome-probes.md

决策规则

• 将 WCAG 2.2 成功标准、HTML/ARIA 规范和说明性教程/模式视为不同层次。参见 references/source-index.md。
• 只有当原生宿主语言语义无法提供所需行为时，才使用 WAI-ARIA 1.2。ARIA 会改变语义，但不会创建键盘行为或视觉呈现。
• 对于边缘情况，使用 Accessible Name and Description Computation 1.2 算法。不要用优先级助记法代替；应检查计算后的无障碍树和名称。
• 对于模态框，如果目标环境支持 <dialog>.showModal()，应优先使用。确保背景内容不可用/处于惰性状态，根据内容和任务选择初始焦点，提供可见的关闭途径，并以符合逻辑的方式返回焦点。不要用 aria-hidden 隐藏背景遮罩，也不要隐藏对话框的祖先元素。
• 将常规响应式导航视为普通链接的展开/折叠控件，而不是 ARIA 菜单。只有采用应用菜单键盘交互契约时，才使用菜单语义。
• WCAG 2.2 AA 的最小目标尺寸为 24 × 24 CSS 像素，但适用间距、等效、行内、用户代理和必要性例外。更大的目标尺寸可以作为产品目标。

完成

当每项验收标准都有直接证据，或已记录为失败、受阻或不适用时，即可停止。报告剩余风险和证据的确切边界；不要将未进行的测试视为通过。

何时不使用

• 对于 Hugo 模板架构、主题级布局或 CMS 渲染问题，请使用 hugo-theme 及其设计与无障碍参考。
• 对于无障碍之外的证据收集、范围决策或面向用户的行为，请使用 product-discovery、product-methodology 或 product-design-and-ux。本技能负责处理无障碍交互与符合性深度。
• 对于框架或库 API，请先定义本技能的语义与交互契约，再查阅最新的官方文档。React 实现细节请参阅 react；Vite 配置请参阅 vite。