fixing-accessibility
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesefixing-accessibility
修复无障碍问题
Fix accessibility issues.
修复无障碍问题。
how to use
使用方法
-
Apply these constraints to any UI work in this conversation.
/fixing-accessibility -
Review the file against all rules below and report:
/fixing-accessibility <file>- violations (quote the exact line or snippet)
- why it matters (one short sentence)
- a concrete fix (code-level suggestion)
Do not rewrite large parts of the UI. Prefer minimal, targeted fixes.
-
将这些约束应用于本次对话中的任何UI工作。
/fixing-accessibility -
根据以下所有规则审查文件并报告：
/fixing-accessibility <file>- 违规情况（引用确切的代码行或片段）
- 问题影响（一句话简要说明）
- 具体修复方案（代码层面的建议）
请勿重写UI的大部分内容。优先选择最小化、针对性的修复。
when to apply
适用场景
Reference these guidelines when:
- adding or changing buttons, links, inputs, menus, dialogs, tabs, dropdowns
- building forms, validation, error states, helper text
- implementing keyboard shortcuts or custom interactions
- working on focus states, focus trapping, or modal behavior
- rendering icon-only controls
- adding hover-only interactions or hidden content
在以下场景中参考这些指南：
- 添加或修改按钮、链接、输入框、菜单、对话框、标签页、下拉菜单
- 构建表单、验证逻辑、错误状态、辅助文本
- 实现键盘快捷键或自定义交互
- 处理焦点状态、焦点捕获或模态框行为
- 渲染仅图标控件
- 添加仅悬停交互或隐藏内容
rule categories by priority
按优先级划分的规则类别
| priority | category | impact |
|---|---|---|
| 1 | accessible names | critical |
| 2 | keyboard access | critical |
| 3 | focus and dialogs | critical |
| 4 | semantics | high |
| 5 | forms and errors | high |
| 6 | announcements | medium-high |
| 7 | contrast and states | medium |
| 8 | media and motion | low-medium |
| 9 | tool boundaries | critical |
| 优先级 | 类别 | 影响程度 |
|---|---|---|
| 1 | 无障碍名称 | 严重 |
| 2 | 键盘访问 | 严重 |
| 3 | 焦点与对话框 | 严重 |
| 4 | 语义化 | 高 |
| 5 | 表单与错误 | 高 |
| 6 | 状态播报 | 中高 |
| 7 | 对比度与状态 | 中 |
| 8 | 媒体与动效 | 中低 |
| 9 | 工具边界 | 严重 |
quick reference
速查指南
1. accessible names (critical)
1. 无障碍名称（严重）
- every interactive control must have an accessible name
- icon-only buttons must have aria-label or aria-labelledby
- every input, select, and textarea must be labeled
- links must have meaningful text (no “click here”)
- decorative icons must be aria-hidden
- 每个交互控件必须具备无障碍名称
- 仅图标按钮必须添加aria-label或aria-labelledby
- 每个输入框、选择框和文本域必须添加标签
- 链接必须包含有意义的文本（禁止使用“点击这里”）
- 装饰性图标必须设置aria-hidden
2. keyboard access (critical)
2. 键盘访问（严重）
- do not use div or span as buttons without full keyboard support
- all interactive elements must be reachable by Tab
- focus must be visible for keyboard users
- do not use tabindex greater than 0
- Escape must close dialogs or overlays when applicable
- 不要使用div或span作为按钮，除非具备完整的键盘支持
- 所有交互元素必须可通过Tab键访问
- 键盘用户必须能看到焦点状态
- 不要使用大于0的tabindex值
- 适用场景下，按Escape键必须关闭对话框或浮层
3. focus and dialogs (critical)
3. 焦点与对话框（严重）
- modals must trap focus while open
- restore focus to the trigger on close
- set initial focus inside dialogs
- opening a dialog should not scroll the page unexpectedly
- 模态框打开时必须捕获焦点
- 关闭时将焦点恢复到触发元素
- 在对话框内设置初始焦点
- 打开对话框不应导致页面意外滚动
4. semantics (high)
4. 语义化（高）
- prefer native elements (button, a, input) over role-based hacks
- if a role is used, required aria attributes must be present
- lists must use ul or ol with li
- do not skip heading levels
- tables must use th for headers when applicable
- 优先使用原生元素（button、a、input）而非基于角色的变通方案
- 如果使用角色，必须添加所需的aria属性
- 列表必须使用ul或ol包裹li元素
- 不要跳过标题层级
- 适用场景下，表格必须使用th作为表头
5. forms and errors (high)
5. 表单与错误（高）
- errors must be linked to fields using aria-describedby
- required fields must be announced
- invalid fields must set aria-invalid
- helper text must be associated with inputs
- disabled submit actions must explain why
- 错误信息必须通过aria-describedby关联到对应字段
- 必填字段必须被播报
- 无效字段必须设置aria-invalid
- 辅助文本必须关联到输入框
- 禁用的提交操作必须说明原因
6. announcements (medium-high)
6. 状态播报（中高）
- critical form errors should use aria-live
- loading states should use aria-busy or status text
- toasts must not be the only way to convey critical information
- expandable controls must use aria-expanded and aria-controls
- 严重的表单错误应使用aria-live
- 加载状态应使用aria-busy或状态文本
- 关键信息不能仅通过提示框（toast）传达
- 可展开控件必须使用aria-expanded和aria-controls
7. contrast and states (medium)
7. 对比度与状态（中）
- ensure sufficient contrast for text and icons
- hover-only interactions must have keyboard equivalents
- disabled states must not rely on color alone
- do not remove focus outlines without a visible replacement
- 确保文本和图标具备足够的对比度
- 仅悬停交互必须有键盘等效操作
- 禁用状态不能仅依赖颜色区分
- 不要移除焦点轮廓，除非提供可见的替代方案
8. media and motion (low-medium)
8. 媒体与动效（中低）
- images must have correct alt text (meaningful or empty)
- videos with speech should provide captions when relevant
- respect prefers-reduced-motion for non-essential motion
- avoid autoplaying media with sound
- 图片必须添加正确的alt文本（有意义或为空）
- 含语音的视频在相关场景下必须提供字幕
- 尊重prefers-reduced-motion设置，避免非必要动效
- 避免自动播放带声音的媒体
9. tool boundaries (critical)
9. 工具边界（严重）
- prefer minimal changes, do not refactor unrelated code
- do not add aria when native semantics already solve the problem
- do not migrate UI libraries unless requested
- 优先选择最小化修改，不要重构无关代码
- 原生语义已能解决问题时，不要添加aria属性
- 除非被要求，否则不要迁移UI库
common fixes
常见修复方案
html
<!-- 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>html
<!-- 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>review guidance
审查指南
- fix critical issues first (names, keyboard, focus, tool boundaries)
- prefer native HTML before adding aria
- quote the exact snippet, state the failure, propose a small fix
- for complex widgets (menu, dialog, combobox), prefer established accessible primitives over custom behavior
- 优先修复严重问题（名称、键盘、焦点、工具边界）
- 优先使用原生HTML，再考虑添加aria属性
- 引用确切代码片段，说明问题所在，提出小型修复方案
- 对于复杂组件（菜单、对话框、组合框），优先使用成熟的无障碍原生组件而非自定义行为