
关于
审计和修复 HTML 无障碍问题,包括 ARIA 标签、键盘导航、焦点管理、颜色对比度和表单错误。适用于添加交互控件、表单、对话框或审查 WCAG 合规性。
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
- 引用确切代码片段,说明失败原因,提出小修复
- 对于复杂组件(菜单、对话框、组合框),优先使用成熟的无障碍原语而非自定义行为
限制
- 仅在任务明确匹配上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果所需输入、权限、安全边界或成功标准缺失,请停下来寻求澄清。
兼容工具
Claude CodeCursor
标签
前端开发