fixing-accessibility

修复无障碍问题

修复无障碍问题。

使用方法

• /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. 媒体和动态效果（中低）

• 图片必须有正确的 alt 文本（有意义的文本或留空）
• 视频包含语音时，适用情况下应提供字幕
• 非必要动态效果应遵循 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>
  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>

审查指南

• 优先修复严重问题（名称、键盘、焦点、工具边界）
• 添加 aria 之前，优先使用原生 HTML
• 引用准确的代码片段，说明问题，并提出小幅修复建议
• 对于复杂控件（菜单、对话框、组合框），优先使用成熟的无障碍基础组件，而不是自定义行为