a11y

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Systematically improve accessibility so the interface works for users with disabilities, temporary impairments, and assistive technology.

This skill focuses on remediation and implementation, not just scoring. It complements

audit

(which measures across dimensions) and

harden

(which handles edge cases broadly). Use this when accessibility is the primary goal.

系统性地提升可访问性，确保残障人士、暂时性功能受损用户和辅助技术用户都能使用该界面。

本 skill 专注于修复和实施，而不仅仅是评分。它是

audit

（从多个维度进行衡量）和

harden

（广泛处理边缘情况）的补充。当可访问性是主要目标时使用本 skill。

MANDATORY PREPARATION

必须进行的准备

Users start this workflow with

/a11y

. Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup first.

Consult the accessibility testing reference for automated tool integration (axe, WAVE, Pa11y) and CI workflow guidance. Consult the colorblindness UX reference when color is carrying meaning in states, charts, or validation. Consult the component accessibility reference for keyboard support, focus handling, skip links, and hidden content patterns. Consult the interaction design reference for focus, loading, transitions, and feedback states. Consult the semantic color reference when checking whether color communicates state or just decoration. Consult the responsive design reference when accessibility needs to adapt across small screens, touch contexts, or zoom levels.

用户通过

/a11y

启动此工作流。本 skill 激活后，加载 $frontend-design——其中包含设计原则、反模式和 Context Gathering Protocol。继续操作前必须遵循该协议——如果尚不存在设计上下文，则必须先加载 $setup。

查阅可访问性测试参考，了解自动化工具集成（axe、WAVE、Pa11y）和 CI 工作流指导。当颜色在状态、图表或验证过程中承载含义时，查阅色盲 UX 参考。查阅组件可访问性参考，了解键盘支持、焦点处理、跳转链接和隐藏内容模式。查阅交互设计参考，了解焦点、加载、转场和反馈状态。检查颜色是在传达状态还是仅用于装饰时，查阅语义化颜色参考。当可访问性需要适配小屏幕、触摸环境或缩放级别时，查阅响应式设计参考。

Assess Accessibility

评估可访问性

Identify what is broken and who it affects:

Run automated checks first:
- Use axe-core, WAVE, or Pa11y against critical pages
- Target WCAG 2.1 AA as the baseline
- Document violations by severity: critical (blocks task), serious (difficult workaround), moderate (annoying), minor (polish)
- Treat automated results as a fast warning system, not a complete audit
Test keyboard navigation manually:
- Unplug the mouse. Can you reach every interactive element?
- Is the tab order logical and predictable?
- Are focus indicators visible and clear?
- Are there keyboard traps (places you cannot tab out of)?
- Do custom components respond to Enter, Space, Escape, and arrow keys?
Test with a screen reader:
- Use NVDA (Windows), VoiceOver (macOS/iOS), or TalkBack (Android)
- Navigate by headings, landmarks, and form fields
- Verify that dynamic content changes are announced
- Check that decorative elements are hidden from assistive technology
- Confirm that error messages and status updates are read aloud
Check visual accessibility:
- Verify contrast ratios: 4.5:1 for normal text, 3:1 for large text, 3:1 for UI components
- Test at 200% and 400% zoom without horizontal scrolling or content loss
- Simulate color-vision deficiencies (deuteranopia, protanopia, tritanopia)
- Ensure color is not the only signal for state or meaning
- Check that text remains readable when high-contrast mode is enabled
Check motion and animation:
- Enable
```
prefers-reduced-motion
```
  and confirm the interface remains usable
- Ensure no critical information is hidden behind motion-only reveals
- Verify that auto-playing content can be paused or stopped

确定存在的问题及其影响对象：

首先运行自动化检查：
- 对关键页面使用 axe-core、WAVE 或 Pa11y
- 以 WCAG 2.1 AA 为基准
- 按严重程度记录违规项：严重（阻碍任务）、重大（难以绕过）、中等（造成困扰）、轻微（影响精致度）
- 将自动化结果视为快速预警系统，而非完整审计
手动测试键盘导航：
- 拔掉鼠标后操作。你能访问每个交互元素吗？
- Tab 顺序是否合乎逻辑且可预测？
- 焦点指示器是否清晰可见？
- 是否存在键盘陷阱（无法通过 Tab 移出的位置）？
- 自定义组件是否响应 Enter、Space、Escape 和方向键？
使用屏幕阅读器进行测试：
- 使用 NVDA（Windows）、VoiceOver（macOS/iOS）或 TalkBack（Android）
- 通过标题、地标区域和表单字段进行导航
- 确认动态内容变化能够被播报
- 检查装饰性元素是否对辅助技术隐藏
- 确认错误消息和状态更新能够被朗读
检查视觉可访问性：
- 验证对比度：普通文本为 4.5:1，大号文本为 3:1，UI 组件为 3:1
- 在 200% 和 400% 缩放下测试，确保没有横向滚动或内容丢失
- 模拟色觉缺陷（deuteranopia、protanopia、tritanopia）
- 确保颜色不是传达状态或含义的唯一信号
- 检查启用高对比度模式时文本是否仍然清晰可读
检查动效与动画：
- 启用
```
prefers-reduced-motion
```
  并确认界面仍然可用
- 确保关键信息不会被仅通过动效显示的内容所隐藏
- 验证自动播放的内容可以暂停或停止

Remediate by Area

按领域修复

Semantic HTML

语义化 HTML

Use the right element for the job. Native HTML elements come with built-in accessibility.

Fixes:

Replace
```
<div>
```
or
```
<span>
```
buttons with
```
<button>
```
elements
Use
```
<a>
```
only for navigation,
```
<button>
```
for actions
Use
```
<nav>
```
,
```
<main>
```
,
```
<aside>
```
,
```
<header>
```
,
```
<footer>
```
for landmarks
Use
```
<ul>
```
/
```
<ol>
```
for lists, not styled divs
Use
```
<table>
```
for tabular data, not CSS grid layouts
Use
```
<label>
```
explicitly associated with inputs via
```
for
```
attribute
Use
```
<fieldset>
```
and
```
<legend>
```
for related form groups

Anti-patterns to remove:

Clickable divs without
```
role
```
,
```
tabindex
```
, and keyboard handlers
Headings used only for sizing (
```
<h1>
```
through
```
<h6>
```
should reflect document structure)
Placeholder text used as labels
Empty links or buttons with only icons and no accessible name

为具体任务选择正确的元素。原生 HTML 元素自带可访问性支持。

修复项：

使用
```
<button>
```
元素替换充当按钮的
```
<div>
```
或
```
<span>
```
```
<a>
```
仅用于导航，
```
<button>
```
用于操作
使用
```
<nav>
```
、
```
<main>
```
、
```
<aside>
```
、
```
<header>
```
、
```
<footer>
```
划分地标区域
使用
```
<ul>
```
/
```
<ol>
```
表示列表，而不是使用设置了样式的 div
使用
```
<table>
```
表示表格数据，而不是使用 CSS Grid 布局
使用
```
for
```
属性将
```
<label>
```
与输入框显式关联
使用
```
<fieldset>
```
和
```
<legend>
```
表示相关的表单组

需要移除的反模式：

缺少
```
role
```
、
```
tabindex
```
和键盘处理器的可点击 div
仅用于调整字号的标题（
```
<h1>
```
至
```
<h6>
```
应反映文档结构）
将占位文本用作标签
只有图标且没有可访问名称的空链接或按钮

Keyboard Navigation

键盘导航

Every interactive element must be reachable and operable without a mouse.

Fixes:

Ensure all interactive elements have
```
tabindex="0"
```
(or are naturally focusable)
Remove
```
tabindex="-1"
```
from elements that should be focusable
Remove positive
```
tabindex
```
values (they create unpredictable order)
Implement keyboard handlers for custom components:
- Buttons: Enter and Space activate
- Toggles: Enter or Space toggle
- Menus: Enter opens, Escape closes, arrow keys navigate
- Modals: Tab cycles within, Escape closes, focus returns to trigger
- Accordions: Enter or Space toggle, arrow keys move between items
Ensure focus is visible: provide a clear focus ring that is not suppressed by
```
outline: none
```
without replacement

每个交互元素都必须能够在不使用鼠标的情况下被访问和操作。

修复项：

确保所有交互元素都具有
```
tabindex="0"
```
（或本身可自然获得焦点）
从应当可获得焦点的元素上移除
```
tabindex="-1"
```
移除正数
```
tabindex
```
值（它们会造成不可预测的顺序）
为自定义组件实现键盘处理：
- 按钮：使用 Enter 和 Space 激活
- 开关：使用 Enter 或 Space 切换
- 菜单：使用 Enter 打开、Escape 关闭，并通过方向键导航
- 模态框：Tab 在内部循环，Escape 关闭，焦点返回触发元素
- 折叠面板：使用 Enter 或 Space 切换，并通过方向键在项目间移动
确保焦点可见：提供清晰的焦点环；不能在没有替代方案的情况下通过
```
outline: none
```
将其抑制

Focus Management

焦点管理

Focus must be intentional, visible, and predictable.

Fixes:

On route change in SPAs, move focus to the new page heading or main content
When a modal opens, trap focus inside and return focus to the trigger on close
When a dropdown opens, move focus to the first item
When an error occurs, move focus to the error summary or first invalid field
When content is removed, move focus to a logical remaining element (not document.body)
Do not auto-focus fields on page load unless the user explicitly initiated the action

焦点必须有意设置、清晰可见且可预测。

修复项：

在 SPA 中切换路由时，将焦点移至新页面标题或主要内容
模态框打开时，将焦点限制在内部；关闭时，将焦点返回触发元素
下拉菜单打开时，将焦点移至第一个项目
发生错误时，将焦点移至错误摘要或第一个无效字段
内容被移除时，将焦点移至逻辑上合理的剩余元素（而不是
```
document.body
```
）
除非用户明确发起了相应操作，否则不要在页面加载时自动聚焦字段

ARIA

Use ARIA only when native HTML is insufficient. ARIA does not change behavior, only semantics.

When to use ARIA:

Custom components that have no native HTML equivalent (tabs, tree views, complex menus)
Landmark regions that need explicit roles
Live regions for dynamic content announcements
Accessible names or descriptions that cannot be provided by visible text

Common ARIA fixes:

Add
```
role="dialog"
```
and
```
aria-modal="true"
```
to modals
Add
```
aria-expanded
```
to disclosure buttons and accordion triggers
Add
```
aria-current="page"
```
to the active navigation item
Add
```
aria-live="polite"
```
or
```
aria-live="assertive"
```
to status containers
Add
```
aria-label
```
or
```
aria-labelledby
```
to icons and icon-only buttons
Add
```
aria-describedby
```
to inputs with helper text or error messages
Add
```
aria-invalid="true"
```
to invalid form fields

ARIA anti-patterns:

Do not add
```
role="button"
```
to actual
```
<button>
```
elements
Do not use
```
aria-hidden="true"
```
on focusable elements
Do not use conflicting roles (e.g.,
```
role="button"
```
on a link)
Do not nest interactive elements inside each other
Do not rely on ARIA alone without implementing the corresponding keyboard behavior

仅当原生 HTML 不足时才使用 ARIA。ARIA 不会改变行为，只会改变语义。

何时使用 ARIA：

没有原生 HTML 等价元素的自定义组件（标签页、树视图、复杂菜单）
需要显式角色的地标区域
用于播报动态内容的 live region
无法通过可见文本提供可访问名称或描述的情况

常见 ARIA 修复项：

为模态框添加
```
role="dialog"
```
和
```
aria-modal="true"
```
为披露按钮和折叠面板触发器添加
```
aria-expanded
```
为当前导航项添加
```
aria-current="page"
```
为状态容器添加
```
aria-live="polite"
```
或
```
aria-live="assertive"
```
为图标和纯图标按钮添加
```
aria-label
```
或
```
aria-labelledby
```
为带有辅助文本或错误消息的输入框添加
```
aria-describedby
```
为无效表单字段添加
```
aria-invalid="true"
```

ARIA 反模式：

不要在实际
```
<button>
```
元素上添加
```
role="button"
```
不要在可获得焦点的元素上使用
```
aria-hidden="true"
```
不要使用相互冲突的角色（例如，在链接上使用
```
role="button"
```
）
不要将交互元素嵌套在其他交互元素中
不要只依赖 ARIA 而不实现相应的键盘行为

Color and Contrast

颜色与对比度

Ensure information is perceivable regardless of visual ability.

Fixes:

Meet WCAG AA contrast: 4.5:1 for normal text, 3:1 for large text and UI components
Never rely on color alone for state, error, or required indicators
Pair semantic colors with text labels, icons, or shape differences
Check semantic color ramps under color-vision simulation
Ensure focus indicators have sufficient contrast against their background
Provide visible text labels or icons alongside colored status indicators

确保无论视觉能力如何，信息都能被感知。

修复项：

满足 WCAG AA 对比度要求：普通文本为 4.5:1，大号文本和 UI 组件为 3:1
绝不要仅依赖颜色来指示状态、错误或必填项
将语义化颜色与文本标签、图标或形状差异搭配使用
在色觉模拟环境下检查语义化色阶
确保焦点指示器与背景之间具有足够的对比度
在彩色状态指示器旁提供可见文本标签或图标

Screen Reader Support

屏幕阅读器支持

Ensure assistive technology users receive equivalent information.

Fixes:

Provide descriptive alt text for informative images; use empty alt for decorative images
Use
```
aria-live
```
regions for dynamic updates (search results, form submissions, notifications)
Ensure form errors are associated with their fields via
```
aria-describedby
```
Provide accessible names for all icons, buttons, and controls
Use headings hierarchically (do not skip levels)
Mark decorative SVGs with
```
aria-hidden="true"
```
or
```
role="img"
```
with a title
Ensure tables have proper
```
th
```
headers and
```
scope
```
attributes

确保辅助技术用户能够接收到等价信息。

修复项：

为信息型图片提供描述性替代文本；为装饰性图片使用空的
```
alt
```
使用
```
aria-live
```
区域处理动态更新（搜索结果、表单提交、通知）
通过
```
aria-describedby
```
将表单错误与对应字段关联
为所有图标、按钮和控件提供可访问名称
按层级使用标题（不要跳过级别）
使用
```
aria-hidden="true"
```
标记装饰性 SVG，或使用
```
role="img"
```
并提供标题
确保表格具有正确的
```
th
```
表头和
```
scope
```
属性

Motion and Animation

动效与动画

Respect users who cannot tolerate or do not want motion.

Fixes:

Wrap animations in
```
@media (prefers-reduced-motion: no-preference)
```
or provide reduced-motion alternatives
For
```
prefers-reduced-motion: reduce
```
, replace motion with instant state changes or subtle fades
Do not auto-play video or animations without a pause/stop control
Ensure parallax and scroll-triggered effects do not cause disorientation
Respect motion preferences in carousels, slideshows, and onboarding tours

尊重无法耐受或不希望看到动效的用户。

修复项：

将动画包裹在
```
@media (prefers-reduced-motion: no-preference)
```
中，或提供减少动效的替代方案
对于
```
prefers-reduced-motion: reduce
```
，使用即时状态变化或轻微淡入淡出代替动效
不要自动播放视频或动画，除非提供暂停或停止控件
确保视差和滚动触发效果不会造成迷失方向
在轮播、幻灯片和引导流程中尊重用户的动效偏好

Verify Improvements

验证改进

After remediation, verify that fixes work:

Re-run automated checks: confirm previous violations are resolved and no new ones were introduced
Keyboard pass: tab through every interactive element again
Screen reader pass: navigate by headings, landmarks, and form fields
Zoom test: confirm usability at 200% and 400%
Color-vision simulation: confirm states and charts remain distinguishable
Reduced motion: enable
```
prefers-reduced-motion
```
and confirm the interface is still usable
Real devices: test on actual assistive technology when possible

修复后，验证修复是否有效：

重新运行自动化检查：确认之前的违规项已解决，且没有引入新的违规项
键盘检查：再次通过 Tab 键访问每个交互元素
屏幕阅读器检查：通过标题、地标区域和表单字段进行导航
缩放测试：确认在 200% 和 400% 缩放下仍然可用
色觉模拟：确认状态和图表仍可区分
减少动效：启用
```
prefers-reduced-motion
```
并确认界面仍然可用
真实设备：尽可能在实际辅助技术上进行测试

Practical Checklist

实用检查清单

All interactive elements are reachable by keyboard
Focus order is logical and predictable
Focus indicators are visible
Native HTML elements are used where possible
ARIA is used only when HTML is insufficient
Custom components have appropriate keyboard handlers
Color contrast meets WCAG AA (4.5:1 for text)
Color is not the only signal for state or meaning
Images have descriptive alt text (decorative images are marked as such)
Form inputs have associated labels
Form errors are linked to fields and announced
Dynamic content changes use aria-live regions
Touch targets are at least 44 by 44 pixels
Interface remains usable at 200% zoom
Motion respects
```
prefers-reduced-motion
```
Automated tests pass with no WCAG AA violations
Manual keyboard and screen reader tests pass

NEVER:

Rely on automated testing alone
Use ARIA without implementing corresponding keyboard behavior
Rely on color alone for important information
Remove focus indicators without providing a replacement
Skip manual testing with real assistive technology for critical flows
Treat accessibility as a one-time fix rather than an ongoing practice

Remember: accessible design is usable design. Fixing accessibility issues usually improves the experience for everyone.

所有交互元素均可通过键盘访问
焦点顺序合乎逻辑且可预测
焦点指示器清晰可见
尽可能使用原生 HTML 元素
仅在 HTML 不足时使用 ARIA
自定义组件具有适当的键盘处理器
颜色对比度满足 WCAG AA（文本为 4.5:1）
颜色不是传达状态或含义的唯一信号
图片具有描述性替代文本（装饰性图片已作相应标记）
表单输入框具有关联标签
表单错误已与字段关联并能够被播报
动态内容变化使用 aria-live 区域
触摸目标至少为 44 × 44 像素
界面在 200% 缩放下仍然可用
动效遵循
```
prefers-reduced-motion
```
自动化测试通过，且不存在 WCAG AA 违规项
手动键盘和屏幕阅读器测试通过

绝不：

仅依赖自动化测试
在未实现相应键盘行为的情况下使用 ARIA
仅依赖颜色传达重要信息
在未提供替代方案的情况下移除焦点指示器
对关键流程跳过使用真实辅助技术进行手动测试
将可访问性视为一次性修复，而不是持续实践

请记住：可访问的设计就是可用的设计。修复可访问性问题通常会改善所有人的体验。