accessibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Accessibility

可访问性

Comprehensive patterns for building accessible web applications: WCAG 2.2 AA compliance, keyboard focus management, and React Aria component patterns. Each category has individual rule files in

rules/

loaded on-demand.

构建可访问Web应用的综合模式：WCAG 2.2 AA合规、键盘焦点管理和React Aria组件模式。每个分类在

rules/

目录下都有单独的规则文件，可按需加载。

Quick Reference

快速参考

Category	Rules	Impact	When to Use
WCAG Compliance	3	CRITICAL	Color contrast, semantic HTML, automated testing
Focus Management	3	HIGH	Focus traps, focus restoration, keyboard navigation
React Aria	3	HIGH	Accessible components, form hooks, overlay patterns

Total: 9 rules across 3 categories

分类	规则数量	影响等级	适用场景
WCAG合规	3	关键	颜色对比度、语义化HTML、自动化测试
焦点管理	3	高	焦点陷阱、焦点恢复、键盘导航
React Aria	3	高	可访问组件、表单钩子、浮层模式

总计：3个分类共9条规则

Quick Start

快速开始

tsx

// Semantic HTML with ARIA
<main>
  <article>
    <header><h1>Page Title</h1></header>
    <section aria-labelledby="features-heading">
      <h2 id="features-heading">Features</h2>
    </section>
  </article>
</main>

tsx

// Focus trap with React Aria
import { FocusScope } from 'react-aria';

<FocusScope contain restoreFocus autoFocus>
  <div role="dialog" aria-modal="true">
    {children}
  </div>
</FocusScope>

tsx

// 结合ARIA的语义化HTML
<main>
  <article>
    <header><h1>页面标题</h1></header>
    <section aria-labelledby="features-heading">
      <h2 id="features-heading">功能特性</h2>
    </section>
  </article>
</main>

tsx

// 使用React Aria实现焦点陷阱
import { FocusScope } from 'react-aria';

<FocusScope contain restoreFocus autoFocus>
  <div role="dialog" aria-modal="true">
    {children}
  </div>
</FocusScope>

WCAG Compliance

WCAG合规

WCAG 2.2 AA implementation for inclusive, legally compliant web applications.

Rule	File	Key Pattern
Color Contrast	`rules/wcag-color-contrast.md`	4.5:1 text, 3:1 UI components, focus indicators
Semantic HTML	`rules/wcag-semantic-html.md`	Landmarks, headings, ARIA labels, form structure
Testing	`rules/wcag-testing.md`	axe-core, Playwright a11y, screen reader testing

用于构建包容性、符合法律要求的Web应用的WCAG 2.2 AA实现方案。

规则	文件	核心模式
颜色对比度	`rules/wcag-color-contrast.md`	普通文本4.5:1，UI组件3:1，焦点指示器
语义化HTML	`rules/wcag-semantic-html.md`	地标、标题、ARIA标签、表单结构
测试	`rules/wcag-testing.md`	axe-core、Playwright a11y、屏幕阅读器测试

Focus Management

焦点管理

Keyboard focus management patterns for accessible interactive widgets.

Rule	File	Key Pattern
Focus Trap	`rules/focus-trap.md`	Modal focus trapping, FocusScope, Escape key
Focus Restoration	`rules/focus-restoration.md`	Return focus to trigger, focus first error
Keyboard Navigation	`rules/focus-keyboard-nav.md`	Roving tabindex, skip links, arrow keys

用于可访问交互式组件的键盘焦点管理模式。

规则	文件	核心模式
焦点陷阱	`rules/focus-trap.md`	模态框焦点捕获、FocusScope、ESC键退出
焦点恢复	`rules/focus-restoration.md`	将焦点返回触发元素、聚焦第一个错误项
键盘导航	`rules/focus-keyboard-nav.md`	可移动tabindex、跳转链接、方向键导航

React Aria

Adobe React Aria hooks for building WCAG-compliant interactive UI.

Rule	File	Key Pattern
Components	`rules/aria-components.md`	useButton, useDialog, useMenu, FocusScope
Forms	`rules/aria-forms.md`	useComboBox, useTextField, useListBox
Overlays	`rules/aria-overlays.md`	useModalOverlay, useTooltip, usePopover

用于构建符合WCAG标准的交互式UI的Adobe React Aria钩子。

规则	文件	核心模式
组件	`rules/aria-components.md`	useButton、useDialog、useMenu、FocusScope
表单	`rules/aria-forms.md`	useComboBox、useTextField、useListBox
浮层	`rules/aria-overlays.md`	useModalOverlay、useTooltip、usePopover

Key Decisions

关键决策

Decision	Recommendation
Conformance level	WCAG 2.2 AA (legal standard: ADA, Section 508)
Contrast ratio	4.5:1 normal text, 3:1 large text and UI components
Target size	24px min (WCAG 2.5.8), 44px for touch
Focus indicator	3px solid outline, 3:1 contrast
Component library	React Aria hooks for control, react-aria-components for speed
State management	react-stately hooks (designed for a11y)
Focus management	FocusScope for modals, roving tabindex for widgets
Testing	jest-axe (unit) + Playwright axe-core (E2E)

决策项	推荐方案
合规等级	WCAG 2.2 AA（法律标准：ADA、Section 508）
对比度	普通文本4.5:1，大文本和UI组件3:1
目标尺寸	最小24px（WCAG 2.5.8），触摸元素44px
焦点指示器	3px实线轮廓，3:1对比度
组件库	如需自定义控制使用React Aria钩子，追求速度使用react-aria-components
状态管理	react-stately钩子（专为可访问性设计）
焦点管理	模态框使用FocusScope，组件使用可移动tabindex
测试	jest-axe（单元测试） + Playwright axe-core（端到端测试）

Anti-Patterns (FORBIDDEN)

反模式（禁止使用）

Div soup: Using
```
<div>
```
instead of semantic elements (
```
<nav>
```
,
```
<main>
```
,
```
<article>
```
)
Color-only information: Status indicated only by color without icon/text
Missing labels: Form inputs without associated
```
<label>
```
or
```
aria-label
```
Keyboard traps: Focus that cannot escape without Escape key
Removing focus outline:
```
outline: none
```
without replacement indicator
Positive tabindex: Using
```
tabindex > 0
```
(disrupts natural order)
Div with onClick: Using
```
<div onClick>
```
instead of
```
<button>
```
or
```
useButton
```
Manual focus in modals: Using
```
useEffect
```
+
```
ref.focus()
```
instead of
```
FocusScope
```
Auto-playing media: Audio/video that plays without user action
ARIA overuse: Using ARIA when semantic HTML suffices

Div堆砌：使用
```
<div>
```
而非语义化元素（
```
<nav>
```
、
```
<main>
```
、
```
<article>
```
）
仅用颜色传递信息：仅通过颜色而非图标/文本表示状态
缺少标签：表单输入未关联
```
<label>
```
或
```
aria-label
```
无法退出的键盘陷阱：焦点无法通过ESC键以外的方式退出
移除焦点轮廓：使用
```
outline: none
```
但未提供替代指示器
正tabindex值：使用
```
tabindex > 0
```
（破坏自然导航顺序）
Div绑定onClick：使用
```
<div onClick>
```
而非
```
<button>
```
或
```
useButton
```
模态框手动聚焦：使用
```
useEffect
```
+
```
ref.focus()
```
而非
```
FocusScope
```
自动播放媒体：无需用户操作自动播放的音频/视频
过度使用ARIA：语义化HTML可满足需求时仍使用ARIA

Detailed Documentation

详细文档

Resource	Description
scripts/	Templates: accessible form, focus trap, React Aria components
checklists/	WCAG audit, focus management, React Aria component checklists
references/	WCAG criteria reference, focus patterns, React Aria hooks API
examples/	Complete accessible component examples

资源	描述
scripts/	模板：可访问表单、焦点陷阱、React Aria组件
checklists/	WCAG审计、焦点管理、React Aria组件检查清单
references/	WCAG标准参考、焦点模式、React Aria钩子API
examples/	完整的可访问组件示例

accessibility

Original

Translation

Accessibility

可访问性

Quick Reference

快速参考

Quick Start

快速开始

WCAG Compliance

WCAG合规

Focus Management

焦点管理

React Aria

React Aria

Key Decisions

关键决策

Anti-Patterns (FORBIDDEN)

反模式（禁止使用）

Detailed Documentation

详细文档

Related Skills

相关技能