accessibility

无障碍

构建无障碍 Web 应用的全面模式：符合 WCAG 2.2 AA、键盘焦点管理、React Aria 组件模式、原生 HTML 优先理念、认知包容性，以及尊重用户偏好。每个类别都在 rules/ 中提供独立的规则文件，按需加载。

快速参考

类别	规则	影响	使用场景
WCAG 合规性	3	严重	颜色对比度、语义化 HTML、自动化测试
POUR 退出标准	1	严重	为每项 WCAG 2.2 AA 标准设定可证伪的通过/失败阈值
静态反模式	1	高	无需浏览器即可检测的可通过 grep 查找的模式
焦点管理	1	高	键盘导航；焦点陷阱/恢复机制由上游负责
React Aria	2	高	无障碍组件和表单钩子；覆盖层 API 由上游负责
现代 Web 无障碍	2	严重/高	原生 HTML 优先、用户偏好；认知上限见 references/ork-delta.md

共计：6 个类别中的 10 条规则

快速入门

// 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>

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

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

WCAG 合规性

实现 WCAG 2.2 AA，让 Web 应用兼具包容性并符合法律要求。

规则	文件	关键模式
颜色对比度	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 无障碍测试、屏幕阅读器测试

POUR 退出标准

为每项 WCAG 2.2 AA 标准设定具体的通过/失败阈值，取代含糊的“符合要求”检查。

规则	文件	关键模式
POUR 退出标准	rules/pour-exit-criteria.md	可证伪的检查清单：图像替代文本、对比度、焦点指示器、触摸目标、ARIA 状态

静态反模式

可通过静态分析或代码审查检测的反模式，无需浏览器。

规则	文件	关键模式
无障碍反模式（静态）	rules/a11y-antipatterns-static.md	移除焦点、缺少标签、自动播放、纯图标按钮、div 点击处理程序

焦点管理

面向无障碍交互式组件的键盘焦点管理模式。

规则	文件	关键模式
键盘导航	rules/focus-keyboard-nav.md	循环 tabindex、跳过链接、方向键

焦点陷阱和恢复机制由上游负责：使用 React Aria <FocusScope contain restoreFocus autoFocus>（参见上游覆盖范围（不要重复说明））。如果无法使用 React Aria，请复制 scripts/focus-trap-template.tsx；两者的内部规则均见 references/ork-delta.md。

React Aria

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

规则	文件	关键模式
组件	rules/aria-components.md	useButton、useDialog、useMenu、FocusScope
表单	rules/aria-forms.md	useComboBox、useTextField、useListBox

覆盖层钩子 API（useModalOverlay、useTooltip、usePopover）见上游文档（参见上游覆盖范围（不要重复说明））；内部覆盖层方案（FocusScope 加共享动态效果预设）见 references/ork-delta.md。

现代 Web 无障碍

2026 年最佳实践：优先使用原生 HTML，兼顾认知包容性，并尊重用户偏好。

规则	文件	关键模式
优先使用原生 HTML	rules/wcag-native-html-first.md	<dialog>、<details>，优先使用原生元素而非自定义 ARIA
用户偏好	rules/wcag-user-preferences.md	prefers-reduced-motion、forced-colors、prefers-contrast、缩放

认知包容性（支持 ADHD／自闭症／阅读障碍）由上游 W3C COGA 涵盖（参见上游涵盖内容（勿重复））；内部的认知负荷上限（通知数量上限、导航项数量上限、阅读水平目标）见 references/ork-delta.md。

关键决策

决策	建议
一致性等级	WCAG 2.2 AA（法律标准：ADA、Section 508）
对比度	普通文本为 4.5:1，大号文本和 UI 组件为 3:1
目标尺寸	最小 24px（WCAG 2.5.8），触控目标为 44px
焦点指示器	3px 实线轮廓，对比度为 3:1
组件库	使用 React Aria hooks 进行控制，使用 react-aria-components 提升开发速度
状态管理	react-stately hooks（专为无障碍设计）
焦点管理	模态框使用 FocusScope，小部件使用 roving tabindex
测试	jest-axe（单元测试）+ Playwright axe-core（E2E）

反模式（禁止）

• Div soup：使用 <div> 而非语义元素（<nav>、<main>、<article>）
• 仅用颜色传达信息：状态仅通过颜色表示，没有图标／文本
• 缺少标签：表单输入没有关联的 <label> 或 aria-label
• 键盘陷阱：焦点无法通过 Escape 键移出
• 移除焦点轮廓：使用 outline: none，却不提供替代指示器
• 正值 tabindex：使用 tabindex > 0（会打乱自然顺序）
• 带 onClick 的 Div：使用 <div onClick> 而非 <button> 或 useButton
• 在模态框中手动管理焦点：使用 useEffect + ref.focus() 而非 FocusScope
• 自动播放媒体：音频／视频未经用户操作便自动播放
• 过度使用 ARIA：语义化 HTML 已足够时仍使用 ARIA

上游涵盖内容（勿重复）

在 2026-07-31 的 wrap-plus-delta 精简中，已移除供应商教程、API 参考和成功标准详解。请查阅一手资料；只有 ork 增补内容（底线、经验教训、内部决策）保留在 references/ork-delta.md 中。

主题	一手资料
WCAG 2.2 成功标准详解和审计清单	WCAG 2.2 快速参考 和 WCAG 2.2 规范
ARIA 小部件模式和键盘交互模型	WAI-ARIA 编写实践指南
React Aria hook API（useButton、useMenu、useComboBox、useModalOverlay、useTooltip、usePopover）、组件清单、完整示例	React Aria 文档
焦点陷阱、焦点还原、roving tabindex 和跳转链接算法	React Aria FocusScope 和 APG 模式
认知无障碍指南（COGA）	W3C 让内容更易于使用
屏幕阅读器测试详解（NVDA、JAWS、VoiceOver、TalkBack）	WebAIM 屏幕阅读器测试

详细文档

资源	说明
scripts/	模板：无障碍表单、焦点陷阱、React Aria 组件
references/ork-delta.md	Ork 专属底线、经验教训和内部决策（认知负荷上限、覆盖层方案、规范焦点陷阱选择器）
references/ux-thresholds-quick.md	UI/UX 阈值快速参考：对比度、触控目标、认知负荷、排版、表单
examples/wcag-examples.md	完整的无障碍表单、模态框和导航示例

相关技能

• ork:testing-e2e - E2E 测试模式，包括无障碍测试
• design-system-starter - 无障碍组件库模式
• ork:i18n-date-patterns - RTL 布局和区域设置感知格式
• motion-animation-patterns - 减少动态效果和动画无障碍