web-accessibility

Web 无障碍

当任务需要指出无障碍问题所在的界面、在正确层级修复问题，并留下简短的修复与验证说明时，使用此技能。

此任务不是罗列通用 WCAG 文本、粘贴原始扫描器输出，也不是处理所有相关的前端问题。

此技能应：

1. 对无障碍问题所在的界面进行分类，
2. 区分自动化检测结果与人工或辅助技术后续验证，
3. 选择最小且可信的修复方案，
4. 明确说明路由应用中的反馈和焦点行为，
5. 如实转交更广泛的设计、布局或组件治理工作。

请先阅读以下支持文档：

• references/intake-packets-and-route-outs.md
• references/audit-remediation-checklist.md
• references/handoff-boundaries.md

何时使用此技能

• 团队提出“让这个功能更无障碍”，但尚未明确具体缺失的无障碍界面
• 需要将 axe、Lighthouse、Accessibility Insights、Pa11y、QA 备注或用户报告转化为一份修复计划，而不是原样罗列检测结果
• 需要判断主要问题属于语义、键盘/焦点、标签/播报、重排/对比度/动效、媒体替代方案，还是路由应用导航反馈
• 模态框、表单、导航、菜单、表格、仪表盘或路由流程在发布前需要人工与自动化验证指导
• 怀疑存在屏幕阅读器、仅键盘操作或缩放/重排问题，但责任归属和后续检查尚不明确

何时不使用此技能

• 主要任务是可复用的基础组件 / 插槽 / 变体 API 设计或组件族所有权 → design-system
• 主要任务是视口适配、断点策略、容器查询规划或布局溢出控制 → responsive-design
• 主要任务是令牌治理、贡献规则或全系统前端标准 → design-system
• 任务仅是运行一个工具并粘贴原始结果；直接运行该工具，然后回到这里确定修复优先级并安排人工后续验证

说明

步骤 1：先明确无障碍任务，再确定修复方案

先收集最精简的说明。

accessibility_intake:
  surface: page | routed-flow | modal | form | nav | menu | table | dashboard | component-family | mixed | unknown
  workflow_type: audit-review | remediation-pass | release-readiness | regression-follow-up | user-reported-bug | design-system-follow-up
  signal_source: axe | lighthouse | accessibility-insights | pa11y | manual-qa | screen-reader-report | user-feedback | mixed | unknown
  primary_surface: semantics | keyboard-focus | labels-announcements | visual-perception-reflow | media-alternatives | routed-navigation-feedback | mixed | unknown
  severity: blocker | major | medium | low | unknown
  ownership: app-team | frontend-platform | design-system | qa-accessibility | shared | unknown

规则：不要一开始就说“添加 ARIA”“再次运行 axe”或“引用 WCAG 2.1”。 首先指出存在问题的无障碍界面。

步骤 2：只选择一个主要修复方案

使用 references/intake-packets-and-route-outs.md 中的路由规则。

主要修复方案：

1. semantics-structure
2. keyboard-focus
3. labels-announcements
4. visual-perception-reflow
5. media-alternatives
6. routed-navigation-feedback

选择对用户影响风险最高的问题作为主要问题。 其余问题列为后续事项，不要将它们列为同等负责人。

步骤 3：明确保留以下原则

以下规则适用于所有回答：

• 自动化工具有助于加快发现问题，但不能证明无障碍完整性
• 原生 HTML 语义已能解决问题时，应优先使用原生语义，而不是用 ARIA 打补丁
• 在交互流程中，键盘/焦点问题通常比外观细节问题优先级更高
• 路由应用需要明确决定焦点和播报行为，因为浏览器导航提示会消失
• 标签、说明、错误信息和异步状态文本都是完成任务的一部分，而非锦上添花
• 每项修复建议都必须配有对应的人工验证步骤

步骤 4：整理无障碍修复说明

按以下结构返回：

# Accessibility Remediation Packet

## Scope
- Surface:
- Workflow type:
- Primary packet:
- Confidence: high | medium | low

## Current signal
- Tool or report source:
- What is already known:
- What still needs direct verification:

## Highest-risk gaps
1. ...
2. ...
3. ...

## Recommended first slice
1. ...
2. ...
3. ...

## Verification plan
- Automated re-check:
- Manual keyboard / focus:
- Manual screen-reader / AT:
- Visual / zoom / motion / reflow:

## Ownership and route-outs
- Primary owner:
- Adjacent skills / teams:

第 5 步：使用数据包，而不是冗长的检查清单

从 references/intake-packets-and-route-outs.md 获取数据包。

数据包规则：

• semantics-structure → 地标、标题、列表、表格、按钮/链接、表单标记、优先使用原生功能的修复
• keyboard-focus → Tab 顺序、可见焦点、陷阱/退出行为、初始焦点、焦点返回、复合控件行为
• labels-announcements → 无障碍名称、辅助文本/错误信息关联、实时区域、状态/错误消息、必填状态清晰度
• visual-perception-reflow → 对比度、减少动态效果、缩放、重排、目标可见性、状态可见性
• media-alternatives → 替代文本、装饰性与信息性图像的区分、字幕、文字稿、备用描述
• routed-navigation-feedback → 页面标题/标题播报、路由变更焦点策略、SPA/应用路由提示、异步加载状态播报

第 6 步：区分自动化发现与手动验证

每个正式答复都要采用以下划分：

• 适合自动化检测 — 缺失标签、重复 ID、无效 ARIA、简单的对比度问题、地标/标题缺失
• 手动键盘/焦点验证 — Tab 顺序、可见焦点、陷阱行为、初始焦点、焦点返回、菜单/列表框/对话框交互
• 手动辅助技术 / 内容质量验证 — 播报是否有用、替代文本质量、标签清晰度、路由变更是否易于理解、异步反馈质量

如果请求以扫描器结果为起点，请明确说明扫描器是输入材料，而不是最终答案。

第 7 步：明确转交相关工作

问题跨越职责边界时，使用以下转交方式：

如果实际任务是……	转交给……
全面的 UI/设计评审、层级、润色或规范合规性	在此处理，采用全面评审模式
可复用组件 API / 基础组件归属 / 插槽与变体设计	design-system
视口/容器布局策略或断点规划	responsive-design
设计令牌治理或系统级前端标准	design-system
React/Next 性能或水合行为	react-best-practices

输出要求

此技能给出的优秀答复应：

1. 找出主要存在问题的无障碍方面；
2. 推荐一个范围明确的修复数据包；
3. 指出仍需进行的手动验证；
4. 避免把扫描器通过等同于任务完成；
5. 将更广泛的前端职责问题转交给相关方，而不是一概揽下。

示例

示例 1：使用 axe 审核模态框

输入

请审核此结账模态框的无障碍问题，并告诉我运行 axe 后还要手动测试什么。

输出方向

• 选择 keyboard-focus 或 labels-announcements
• 将 axe 视为输入材料，而不是整个工作流程
• 验证初始焦点、陷阱行为、焦点返回和播报质量
• 除非视觉润色会实质影响无障碍体验，否则不要扩展到更广泛的视觉润色问题

示例 2：路由应用的导航令人困惑

输入

屏幕阅读器用户反映，我们的 React 应用切换路由后不会播报新页面，焦点仍停留在旧的导航链接上。

输出方向

• 选择 routed-navigation-feedback
• 将标题播报和焦点重置策略归为相应问题
• 修复后进行手动辅助技术验证
• 避免把任务扩展成泛泛的路由架构工作

示例 3：组件边界不清

输入

我们的按钮基础组件 API 很混乱，而且有些变体不符合无障碍要求。这属于 Web 无障碍还是设计系统？

输出方向

• 将无障碍名称、焦点状态以及禁用/加载状态播报的修复留在 web-accessibility 中
• 将基础组件 API / 变体归属问题转交给 design-system
• 拆分计划，而不是强行让一个技能承担所有工作

示例 4：Lighthouse 检查后的手动验证

输入

Lighthouse 说对比度现在没问题了。我还应该手动测试什么？

输出方向

• 将其视为验证规划，而不是庆祝得分
• 在适用时，验证键盘操作顺序、焦点可见性、路由流程提示以及屏幕阅读器播报质量
• 当界面依赖缩放／重排和减少动态效果设置时，也要检查这些方面

最佳实践

1. 从用户任务和出现问题的界面入手，而不是从规则编号入手。
2. 将自动化工具视为加速器，而不是可访问性完整性的证明。
3. 优先使用原生 HTML 语义，而不是大量依赖 ARIA 的修补方案。
4. 对覆盖层、路由变更和异步验证的焦点行为进行有意识的设计。
5. 将修复事项与更广泛的设计评审或组件架构工作分开。
6. 如有疑问，应指出仍需进行的手动验证，而不是假装扫描已经足够。

参考资料

• W3C：Web 可访问性评估概览
• W3C：简单检查——Web 可访问性初步审查
• web.dev：手动进行可访问性测试
• MDN：键盘可访问性
• React Router：可访问性
• Next.js：可访问性