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或状态文本
- 提示框（toasts）不能是传达关键信息的唯一方式
- 可展开控件必须使用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
- 图片必须包含正确的替代文本（有意义或为空）
- 包含语音的视频在相关时应提供字幕
- 对于非必要动效，尊重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库
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属性
- 引用确切的代码片段，说明问题，提出小范围修复方案
- 对于复杂组件（菜单、对话框、组合框），优先使用成熟的无障碍原生组件而非自定义行为