accessibility-engineer

无障碍工程师技能

适用场景

在请求涉及以下内容时应用此技能：

• 无障碍、a11y、WAI-ARIA、屏幕阅读器支持、语义化 HTML、键盘导航、焦点管理
• 无障碍适配、WAI-ARIA、屏幕阅读器适配、语义化 HTML、键盘操作、焦点管理
• 任何 UI 实现（应与其他技能一同应用）

核心原则（最重要）

• 优先使用原生元素。 先用合适的 HTML 元素（button、a、label、input 等）解决问题，再考虑 ARIA。
• 尽量少用 ARIA。 不要为了让内容“看起来”无障碍而添加 role/aria-*。只有确有需要时才添加。
• 可操作 = 可传达。 不只是视觉上可见，辅助技术还必须能获取状态、名称和用途。这是完成的标准。
• 键盘操作是基础。 仅支持鼠标的 UI 并不完整。应先设计焦点移动和操作方式。

实现规则

1) 语义结构

• 保持标题层级顺序（h1 → h2 → ...）。不要为了样式跳过层级。
• 为主要区域设置地标（header、nav、main、footer，必要时也包括 aside）。
• 列表使用 ul/ol/li，定义使用 dl/dt/dd，不要用 div 替代。

2) 无障碍名称

• 按钮、链接和输入框需要有“名称”（屏幕阅读器会读出标签）。
  • 优先级：可见文本
  • 备选：aria-label（无法使用可见文本时）
  • 组合：aria-labelledby（引用现有元素）
• 仅含图标的按钮/链接必须有名称（例如“搜索”“关闭”）。

3) 表单（必需）

• 将 label 与 input 关联（for/id）。绝不能只用 placeholder 作为标签。
• 以机器可读的方式传达必填/选填、错误和提示信息（例如，使用 aria-describedby 关联辅助文本）。
• 错误信息必须说明：哪里出了问题、原因是什么，以及如何修复。

4) 状态与播报（动态 UI）

• 优先使用原生 disabled 属性（例如 button disabled）。
• 对于切换控件，仅在原生元素无法满足需求时使用 aria-pressed / aria-expanded。
• 使用 aria-live 播报异步操作完成或失败的消息，但不要过度使用。

5) 键盘操作与焦点

• 设计 DOM 顺序，确保 Tab 顺序符合逻辑。不要用 tabindex 强行改变顺序。
• tabindex="0"：仅在需要让元素可获得焦点时少量使用。
• tabindex="-1"：仅用于以编程方式移动焦点。
• 始终保留可见焦点（focus-visible）。绝不要隐藏焦点。
• 对话框/模态框：指定打开时焦点移至何处，以及关闭时焦点返回何处。必要时实现焦点陷阱。

6) 图像与媒体

• 根据用途设置 alt（装饰性图像使用空 alt=""）。
• 对于视频/音频：确认是否提供控件（播放/停止）和替代形式（字幕/文字稿）。不明确时请询问。

反模式（绝不要这样做）

• 使用带 onClick 的 div 充当按钮（会破坏键盘操作/角色语义）。
• 将 role="button" 作为变通方案（应使用原生 button）。
• 到处添加 aria-label（可见标签已经存在时会造成重复播报）。
• 移除焦点环（焦点不可见就无法操作）。

澄清问题（不要自行假设）

• 此 UI 是否必须支持仅用键盘完成操作？（如果是，请列出操作步骤并达成一致。）
• 对于模态框/抽屉：打开时焦点移至何处？关闭时焦点移至何处？
• 何时播报错误？立即播报，还是提交后播报？
• 视频/音频是否需要字幕或文字替代内容？

输出格式（用于实现）

1. 语义结构（地标、标题、列表）
2. 键盘操作（Tab 顺序、Enter、Space、Escape）
3. ARIA 用法（仅在需要时使用，并说明理由）
4. 状态（禁用/加载/错误）与播报（必要时使用 aria-live）
5. 无障碍检查清单自评（OK / 需要改进）