reviewing-accessibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reviewing Accessibility

可访问性评审

Review implemented UI code against WCAG Level AA criteria. This skill reviews code that already exists — components, pages, templates, or markup. It does not write code; findings are reported for a developer or coder agent to act on.

For pre-implementation risk assessment of plans or proposals, use

predicting-accessibility-risks

instead.

对照WCAG AA级标准评审已实现的UI代码。该Skill仅评审已存在的代码——包括组件、页面、模板或标记语言，不负责编写代码；评审结果会反馈给开发人员或编码Agent，由他们进行后续处理。

若需对规划或提案进行实现前的风险评估，请使用

predicting-accessibility-risks

。

Review process

评审流程

Review the implemented code against the checklist below. Reference specific WCAG success criteria when flagging violations. Read the actual source files — do not review from memory or assumptions.

对照以下检查清单评审已实现的代码。标记违规项时需引用具体的WCAG成功标准。请阅读实际的源文件——不要凭记忆或假设进行评审。

Semantic HTML

语义化HTML

Correct elements used (
```
button
```
,
```
nav
```
,
```
main
```
,
```
article
```
,
```
h1
```
-
```
h6
```
, etc.)
No
```
div
```
or
```
span
```
with
```
role="button"
```
when a native
```
<button>
```
would work
Heading hierarchy is logical (single
```
h1
```
per page, no skipped levels)
Lists use
```
ul
```
/
```
ol
```
/
```
dl
```
for related items, not styled divs
Data tables have
```
th
```
,
```
caption
```
or
```
aria-label
```

WCAG: 1.3.1 Info and Relationships, 2.4.6 Headings and Labels

使用正确的元素（如
```
button
```
、
```
nav
```
、
```
main
```
、
```
article
```
、
```
h1
```
-
```
h6
```
等）
当原生
```
<button>
```
可满足需求时，避免使用
```
div
```
或
```
span
```
并设置
```
role="button"
```
标题层级符合逻辑（每页仅一个
```
h1
```
，不跳过层级）
相关内容使用
```
ul
```
/
```
ol
```
/
```
dl
```
标签创建列表，而非样式化的div
数据表格包含
```
th
```
、
```
caption
```
或
```
aria-label
```

WCAG: 1.3.1 信息与关系, 2.4.6 标题与标签

Keyboard navigation

键盘导航

All interactive elements are keyboard accessible (Tab, Enter, Space, Escape, arrow keys as appropriate)
Focus order follows a logical reading sequence
No keyboard traps — every element can be navigated away from
Skip links present for main content

WCAG: 2.1.1 Keyboard, 2.1.2 No Keyboard Trap, 2.4.1 Bypass Blocks

所有交互元素支持键盘访问（按需使用Tab、Enter、Space、Escape、方向键）
焦点顺序符合逻辑阅读顺序
无键盘陷阱——所有元素均可被导航离开
提供跳转到主要内容的快捷链接

WCAG: 2.1.1 键盘, 2.1.2 无键盘陷阱, 2.4.1 绕过区块

Focus management

焦点管理

Visible focus indicators on all interactive elements
Focus trapped in modals/dialogs and returned to trigger on close
Focus moved appropriately after dynamic content changes (creation, deletion, filtering)
Route changes move focus to the main content area or page heading

WCAG: 2.4.7 Focus Visible, 2.4.11 Focus Not Obscured, 3.2.1 On Focus

所有交互元素有可见的焦点指示器
模态框/对话框中焦点被捕获，关闭后返回触发元素
动态内容变更（创建、删除、过滤）后焦点需合理移动
路由变更时，焦点需移至主要内容区域或页面标题

WCAG: 2.4.7 可见焦点, 2.4.11 焦点不被遮挡, 3.2.1 聚焦时

Labels and names

标签与名称

All form inputs have associated
```
<label>
```
elements (not placeholder-only)
All interactive elements have meaningful accessible names
Images have descriptive
```
alt
```
text (or
```
alt=""
```
for decorative images)
Error messages are programmatically associated with inputs (
```
aria-describedby
```
)
Icon-only buttons have accessible names via
```
aria-label
```
or visually hidden text

WCAG: 1.1.1 Non-text Content, 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions, 4.1.2 Name, Role, Value

所有表单输入框关联对应的
```
<label>
```
元素（不能仅依赖占位符）
所有交互元素有意义的可访问名称
图片包含描述性
```
alt
```
文本（装饰性图片使用
```
alt=""
```
）
错误消息通过
```
aria-describedby
```
与输入框关联
仅含图标按钮通过
```
aria-label
```
或视觉隐藏文本设置可访问名称

WCAG: 1.1.1 非文本内容, 1.3.1 信息与关系, 3.3.2 标签或说明, 4.1.2 名称、角色、值

ARIA

ARIA used only when native HTML cannot express the semantics
Roles, states, and properties are valid and complete
Live regions (
```
aria-live
```
) used for dynamic content announcements
Loading states announced to screen readers
```
aria-current
```
used for navigation indicators

WCAG: 4.1.2 Name, Role, Value

仅当原生HTML无法表达语义时才使用ARIA
角色、状态和属性有效且完整
使用实时区域（
```
aria-live
```
）播报动态内容
向屏幕阅读器播报加载状态
使用
```
aria-current
```
标记当前导航项

WCAG: 4.1.2 名称、角色、值

Visual

视觉设计

Text contrast minimum 4.5:1 for normal text, 3:1 for large text
Non-text contrast (UI components, graphical objects) minimum 3:1
No information conveyed by colour alone
Animations respect
```
prefers-reduced-motion
```
Interactive target sizes at least 24x24 CSS pixels

WCAG: 1.4.1 Use of Color, 1.4.3 Contrast (Minimum), 1.4.11 Non-text Contrast, 2.3.1 Three Flashes, 2.5.8 Target Size

普通文本对比度至少为4.5:1，大文本对比度至少为3:1
非文本内容（UI组件、图形对象）对比度至少为3:1
不单独通过颜色传递信息
动画效果尊重
```
prefers-reduced-motion
```
设置
交互目标尺寸至少为24x24 CSS像素

WCAG: 1.4.1 颜色使用, 1.4.3 最低对比度, 1.4.11 非文本对比度, 2.3.1 三次闪烁, 2.5.8 目标尺寸

Forms

表单

Visible, persistent labels on all fields
Required fields indicated visually and programmatically (
```
required
```
or
```
aria-required
```
)
```
aria-invalid="true"
```
set on fields in error state, cleared when corrected

Error messages associated via

aria-describedby

and announced via

role="alert"

aria-live="assertive"

Appropriate
```
autocomplete
```
values on personal data fields
Password requirements communicated before submission, not only after failure

WCAG: 1.3.5 Identify Input Purpose, 3.3.1 Error Identification, 3.3.2 Labels or Instructions, 3.3.3 Error Suggestion

所有字段有可见且持久的标签
必填字段通过视觉和编程方式标记（
```
required
```
或
```
aria-required
```
）
错误状态的字段设置
```
aria-invalid="true"
```
，修正后清除该属性

错误消息通过

aria-describedby

关联，并通过

role="alert"

或

aria-live="assertive"

播报

个人数据字段设置合适的
```
autocomplete
```
值
密码要求在提交前告知，而非仅在失败后提示

WCAG: 1.3.5 识别输入用途, 3.3.1 错误识别, 3.3.2 标签或说明, 3.3.3 错误建议

Report format

报告格式

markdown

undefined

markdown

undefined

Accessibility Review - [scope description]

可访问性评审 - [范围描述]

Critical — WCAG Level A violations that make a feature unusable for a disability group

严重——WCAG A级违规，导致某类残障用户无法使用功能

[WCAG SC]
```
file:line
```
- [issue] -> [fix]

[WCAG成功标准]
```
文件:行号
```
- [问题描述] -> [修复方案]

Serious — WCAG Level AA violations that degrade but do not block the experience

重要——WCAG AA级违规，降低体验但不阻碍使用

[WCAG SC]
```
file:line
```
- [issue] -> [fix]

[WCAG成功标准]
```
文件:行号
```
- [问题描述] -> [修复方案]

Moderate — Best practices and WCAG AAA improvements

中等——最佳实践与WCAG AAA级优化建议

[WCAG SC or "Best practice"]
```
file:line
```
- [issue] -> [fix]

[WCAG成功标准或“最佳实践”]
```
文件:行号
```
- [问题描述] -> [修复方案]

Summary

总结

[count] issues found: [n] critical, [n] serious, [n] moderate.


If no issues are found, say so. Do not invent findings.

共发现[数量]个问题：[n]个严重，[n]个重要，[n]个中等。


若未发现问题，请明确说明，不得编造评审结果。

What automated tools already catch

自动化工具已覆盖的检查项

If the project runs axe-core or a similar automated scanner, it already catches: missing alt text, duplicate IDs, basic colour contrast on static text, missing form labels, invalid ARIA attributes, missing lang attribute, landmark violations, heading level skips.

Focus review effort on what automated tools miss: dynamic state management (

aria-invalid

aria-expanded

aria-live

), focus management after interactions, keyboard trap detection, multi-theme contrast for CSS custom properties, shadow DOM internals, meaningful accessible name quality (not just presence), target size adequacy, and motion preference compliance.

Read

references/review-checklist.md

for the full prioritised checklist with WCAG criterion references.

若项目使用axe-core或类似自动化扫描工具，以下问题已能被检测：缺失alt文本、重复ID、静态文本的基础颜色对比度、缺失表单标签、无效ARIA属性、缺失lang属性、地标元素违规、标题层级跳跃。

评审重点应放在自动化工具未覆盖的内容上：动态状态管理（

aria-invalid

、

aria-expanded

、

aria-live

）、交互后的焦点管理、键盘陷阱检测、CSS自定义属性的多主题对比度、Shadow DOM内部内容、有意义的可访问名称质量（而非仅检查是否存在）、目标尺寸是否达标、动画偏好合规性。

完整的优先级检查清单及WCAG标准参考，请阅读

references/review-checklist.md

。

Gotchas

注意事项

Working accessibility trumps theoretical compliance. Before flagging a pattern, understand what the code does. If a component works correctly with keyboard and screen readers but uses an unconventional ARIA pattern, flag it as Moderate with an explanation of the tradeoff — not as a blocker.
Never recommend removing working accessibility code without first verifying that the replacement provides equivalent or better assistive technology support.
Component libraries handle accessibility internally. Many headless UI libraries (Base UI, Headless UI, Ark UI) and web component libraries (Shoelace, Web Awesome) provide built-in keyboard handling, focus trapping, and ARIA management. Adding redundant ARIA to these components can interfere with their built-in accessibility. Check the component library's documentation before recommending changes.
Playwright's
toHaveAccessibleName()
cannot pierce shadow DOM. When reviewing tests for web components with shadow DOM, accessible name assertions may need to check attributes on the host element rather than using computed name matchers.
axe-core has known gaps. It cannot check: CSS custom property contrast chains, shadow DOM internals, dynamic ARIA state management, focus behaviour after interactions, content behind modals or drawers, or
```
prefers-reduced-motion
```
compliance. Manual review and Playwright assertions fill these gaps.
Heading hierarchy is per-page, not per-component. A component that renders an
```
h3
```
is correct or incorrect depending on the page context it appears in. Review heading levels in the context of the full page, not in isolation.
aria-errormessage
has inconsistent assistive technology support. Prefer
```
aria-describedby
```
for associating error messages with form fields — it has broader support and is functionally equivalent for this purpose.
Colour contrast must be checked in every theme. A colour pairing that passes in light mode may fail in dark mode, and vice versa. Review both.

实际可访问性优先于理论合规性。标记某一模式为违规前，需先理解代码的实际功能。若某个组件通过键盘和屏幕阅读器可正常工作，但使用了非常规的ARIA模式，应将其标记为中等问题，并说明权衡取舍——而非将其列为阻塞项。
切勿建议移除有效的可访问性代码，除非已验证替代方案能提供同等或更优的辅助技术支持。
组件库内置可访问性处理。许多无头UI库（Base UI、Headless UI、Ark UI）和Web组件库（Shoelace、Web Awesome）已内置键盘处理、焦点捕获和ARIA管理功能。为这些组件添加冗余ARIA属性可能会干扰其内置的可访问性逻辑。在建议修改前，请查阅组件库的官方文档。
Playwright的
toHaveAccessibleName()
无法穿透Shadow DOM。评审含Shadow DOM的Web组件测试时，可访问名称断言可能需要检查宿主元素的属性，而非使用计算名称匹配器。
axe-core存在已知局限性。它无法检查：CSS自定义属性的对比度链、Shadow DOM内部内容、动态ARIA状态管理、交互后的焦点行为、模态框或抽屉后的内容、
```
prefers-reduced-motion
```
合规性。这些缺口需通过人工评审和Playwright断言来填补。
标题层级是针对整个页面而非单个组件。某个组件渲染
```
h3
```
是否正确，取决于其所在的页面上下文。需在完整页面的语境中评审标题层级，而非孤立评审组件。
aria-errormessage
的辅助技术支持不一致。优先使用
```
aria-describedby
```
关联表单字段与错误消息——它的支持范围更广，且在该场景下功能等效。
需在所有主题下检查颜色对比度。在浅色模式下通过的颜色组合，在深色模式下可能不达标，反之亦然。两种模式均需评审。

Authoritative references

权威参考

Ground all findings in the official WCAG specification and supporting documents. Do not rely on assumptions about what WCAG requires — defer to the spec:

When uncertain about a recommendation, say so explicitly and explain what could not be verified, rather than guessing.

所有评审结果需基于官方WCAG规范及支持文档。请勿依赖对WCAG要求的假设——需严格遵循规范：

若对某条建议不确定，请明确说明无法验证的原因，切勿猜测。