---

name: fixing-accessibility description: 审计和修复 HTML 无障碍问题，包括 ARIA 标签、键盘导航、焦点管理、颜色对比度和表单错误。在添加交互控件、表单、对话框或审查 WCAG 合规性时使用。 risk: unknown source: community

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 属性
• 列表必须使用 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 库

常见修复

<!-- icon-only button: add aria-label -->
<!-- before --> <button><svg>...</svg></button>
<!-- after -->  <button aria-label="Close"><svg aria-hidden="true">...</svg></button>

<!-- div as button: use native element -->
<!-- before --> <div onclick="save()">Save</div>
<!-- after -->  <button onclick="save()">Save</button>

<!-- form error: link with aria-describedby -->
<!-- before --> <input id="email" /> <span>Invalid email</span>
<!-- after -->  <input id="email" aria-describedby="email-err" aria-invalid="true" /> <span id="email-err">Invalid email</span>

审查指南

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

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果所需输入、权限、安全边界或成功标准缺失，请停下来寻求澄清。