fixing-accessibility

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）而非基于角色的hack
• 如果使用了角色，必须存在所需的 ARIA 属性
• 列表必须使用 ul 或 ol 配合 li
• 不要跳过标题级别
• 表格在适用时必须使用 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 库

常见修复

<!-- 仅图标按钮：添加 aria-label -->
<!-- 之前 --> <button><svg>...</svg></button>
<!-- 之后 -->  <button aria-label="关闭"><svg aria-hidden="true">...</svg></button>

<!-- div 作为按钮：使用原生元素 -->
<!-- 之前 --> <div onclick="save()">保存</div>
<!-- 之后 -->  <button onclick="save()">保存</button>

<!-- 表单错误：使用 aria-describedby 链接 -->
<!-- 之前 --> <input id="email" /> <span>无效的邮箱</span>
<!-- 之后 -->  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">无效的邮箱</span>

审查指南

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