fixing-accessibility

修复无障碍问题

使用时机

当你需要审查和修复 HTML 无障碍问题时，请使用此技能，包括 ARIA 标签、键盘导航、焦点管理、色彩对比度和表单错误。添加交互控件、表单、对话框或检查 WCAG 合规性时也请使用。

修复无障碍问题。

如何使用

• /fixing-accessibility 将这些约束应用于本次对话中的所有 UI 工作。

• /fixing-accessibility <file> 根据以下所有规则检查文件，并报告：

  • 违规项（引用确切的行或代码片段）
  • 重要原因（一句简短说明）
  • 具体修复方法（代码级建议）

不要大幅改写 UI。优先进行最小且有针对性的修复。

适用场景

在以下情况下参考这些指南：

• 添加或修改按钮、链接、输入框、菜单、对话框、选项卡、下拉菜单
• 构建表单、验证、错误状态、辅助文本
• 实现键盘快捷键或自定义交互
• 处理焦点状态、焦点陷阱或模态框行为
• 渲染仅含图标的控件
• 添加仅悬停时显示的交互或隐藏内容

按优先级划分的规则类别

优先级	类别	影响
1	无障碍名称	严重
2	键盘访问	严重
3	焦点和对话框	严重
4	语义	高
5	表单和错误	高
6	信息播报	中高
7	对比度和状态	中
8	媒体和动态效果	中低
9	工具边界	严重

快速参考

1. 无障碍名称（严重）

• 每个交互控件都必须有无障碍名称
• 仅含图标的按钮必须具有 aria-label 或 aria-labelledby
• 每个 input、select 和 textarea 都必须有标签
• 链接必须使用有意义的文本（不要使用“点击此处”）
• 装饰性图标必须设置 aria-hidden

2. 键盘访问（严重）

• 不要将 div 或 span 用作按钮，除非提供完整的键盘支持
• 所有控件都必须可通过键盘访问；复合控件可以只占用一个 Tab 停靠点，并提供有说明的方向键导航
• 键盘用户必须能看到焦点
• 不要使用大于 0 的 tabindex
• 适用时，按 Escape 必须关闭对话框或叠加层

3. 焦点和对话框（严重）

• 模态框打开时必须限制焦点在其中
• 关闭时将焦点还原到触发控件
• 在对话框内设置初始焦点
• 打开对话框时不应导致页面意外滚动

4. 语义（高）

• 优先使用原生元素（button、a、input），而不是基于 role 的变通方案
• 如果使用 role，必须提供所需的 aria 属性
• 列表必须使用带有 li 的 ul 或 ol
• 不要跳过标题级别
• 适用时，表格标题必须使用 th

5. 表单和错误（高）

• 错误必须通过 aria-describedby 与字段关联
• 必须播报必填字段
• 无效字段必须设置 aria-invalid
• 辅助文本必须与输入框关联
• 必须说明禁用提交操作的原因

6. 信息播报（中高）

• 关键表单错误应使用 aria-live
• 加载状态应使用 aria-busy 或状态文本
• Toast 不得作为传达关键信息的唯一方式
• 可展开控件必须使用 aria-expanded 和 aria-controls

7. 对比度和状态（中）

• 确保文本和图标具有足够的对比度
• 仅悬停时显示的交互必须提供键盘等效操作
• 禁用状态不能只依赖颜色来表示
• 不要移除焦点轮廓，除非提供清晰可见的替代效果

8. 媒体和动态效果（中低）

• 图像必须使用正确的替代文本（有意义的文本或空文本）
• 视频包含语音时，适用情况下应提供字幕
• 对于非必要的动态效果，应遵循 prefers-reduced-motion
• 避免自动播放带声音的媒体

9. 工具边界（严重）

• 优先进行最小改动，不要重构无关代码
• 如果原生语义已能解决问题，就不要添加 aria
• 除非收到请求，否则不要迁移 UI 库

常见修复

 <button><svg>...</svg></button>
  <button aria-label="Close"><svg aria-hidden="true">...</svg></button>


 <div onclick="save()">Save</div>
  <button onclick="save()">Save</button>


 <input id="email" /> <span>Invalid email</span>
  <label for="email">Email</label><input id="email" type="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>

审查指引

• 优先修复严重问题（名称、键盘、焦点、工具边界）
• 在添加 aria 之前优先使用原生 HTML
• 引用确切的代码片段，说明失败情况，提出小幅修复方案
• 对于复杂组件（菜单、对话框、组合框），优先使用成熟的无障碍原语，而非自定义行为

局限性

• 仅当任务明确匹配其上游来源和本地项目上下文时，才使用此技能。
• 在应用更改之前，请验证命令、生成的代码、依赖项、凭据以及外部服务行为。
• 不要将示例视为针对特定环境的测试、安全审查或对破坏性或高成本操作的用户批准的替代品。