无障碍与包容性设计：从 WCAG 到屏幕阅读器的全链路落地

法律驱动：
□ 欧盟 EAA（2025 生效）：面向消费者的数字服务须达 WCAG 2.1 AA
□ 美国 ADA / Section 508：政府与公共采购强约束
□ 中国《信息无障碍 信息技术互联网内容无障碍可访问性技术要求》
□ 后果：罚款、诉讼、应用商店下架、政府采购资格丧失

用户驱动：
□ 全球约 16% 人口有某种形式的显著残障（WHO）
□ 视障、低视力、色盲、运动障碍、听障、认知障碍
□ 临时性障碍：强光下看不清、单手操作、手臂受伤
□ 情境性障碍：嘈杂环境、慢网络、旧设备

商业驱动：
□ 可访问的页面天然对爬虫与搜索引擎友好（语义化收益）
□ 更清晰的层级与焦点管理同时提升普通用户体验
□ 覆盖更广的设备与网络条件 → 转化率提升

P — 可感知（Perceivable）：
  信息必须能被感知到
  · 非文本内容有替代文本（图片 alt、图标 aria-label）
  · 视频有字幕、音频有文字稿
  · 内容不依赖单一感官（不能只靠颜色传达信息）

O — 可操作（Operable）：
  界面组件必须可操作
  · 全部功能键盘可达
  · 用户能控制时限、暂停动效
  · 有足够时间阅读，不诱发癫痫（闪烁 < 3Hz）

U — 可理解（Understandable）：
  信息与操作必须可理解
  · 页面语言声明（lang）
  · 导航与组件行为可预测
  · 输入错误有明确提示与纠正建议

R — 健壮（Robust）：
  必须能被各类辅助技术解析
  · 有效、完整的 HTML 语义
  · 名称/角色/值（Name, Role, Value）对辅助技术可见

ARIA 五规则（W3C 官方）：
1. 能用原生 HTML 语义，就别用 ARIA
   · <button> 而不是 <div role="button">
   · 原生元素自带键盘、焦点、状态，ARIA 只描述不实现

2. 不要改变原生语义
   · <h1 role="button"> 会让标题变成按钮 → 混乱

3. 所有可交互的 ARIA 组件必须键盘可达
   · role="button" 必须能 Tab 到、能 Enter/Space 触发

4. 不要给可聚焦元素加 aria-hidden="true"
   · 焦点落进隐藏元素 → 屏幕阅读器「消失」

5. 所有 ARIA 元素必须有可访问名称（accessible name）
   · role="button" 必须配文本或 aria-label

<!-- 好：原生按钮 + 明确的名称与状态 -->
<button type="button" aria-pressed="false" aria-label="点赞，当前 128 个赞">
  <svg aria-hidden="true">...</svg>
</button>

<!-- 列表语义：帖子流用 ul/li，而不是一堆 div -->
<ul role="feed" aria-busy="false">
  <li aria-posinset="1" aria-setsize="-1">...</li>
</ul>

键盘可达性检查清单：
□ Tab 顺序与视觉顺序一致（不要用 tabindex="1,2,3" 打乱）
□ 每个可交互元素都有可见的焦点样式（:focus-visible）
□ 焦点不会被「困」在某个区域（modal 除外，那是刻意陷阱）
□ 有「跳到主内容」链接（Skip to content）
□ 不劫持浏览器快捷键（Ctrl/Cmd + 组合键）
□ Esc 关闭弹层，关闭后焦点回到触发元素

// 打开模态框：记录触发元素 → 移焦到对话框 → 限制 Tab 循环
const trigger = document.activeElement;
dialog.showModal();
dialog.querySelector('[autofocus]')?.focus();

// 关闭：恢复焦点，避免用户「丢失位置」
dialog.addEventListener('close', () => trigger?.focus());

主流屏幕阅读器：
□ NVDA（Windows，免费，最常用）
□ JAWS（Windows，商业，企业常用）
□ VoiceOver（macOS / iOS，内置）
□ TalkBack（Android，内置）
□ Orca（Linux）

朗读模型：
  角色（Role）→ 名称（Name）→ 状态（State）→ 值（Value）
  例：「按钮，点赞，已按下，128」
  任何一项缺失，用户就少了判断依据

<!-- 状态提示：不打断当前朗读，等空档播报 -->
<div aria-live="polite" class="sr-only">已点赞，共 129 个赞</div>

<!-- 紧急提示：立即打断（慎用，会打断用户阅读） -->
<div aria-live="assertive" role="alert">发布失败，请重试</div>

对比度要求（AA）：
□ 正文文本：≥ 4.5:1
□ 大号文本（≥ 18.66px 粗体 或 ≥ 24px）：≥ 3:1
□ 图标、边框、图形等非文本：≥ 3:1
□ 焦点指示器：≥ 3:1（相对相邻颜色）

测量：用相对亮度公式计算，别靠肉眼猜
  L = 0.2126R + 0.7152G + 0.0722B（先做 sRGB 线性化）
  对比度 = (L1 + 0.05) / (L2 + 0.05)

不能只靠颜色传达信息：
□ 错误提示：红色 + 图标 + 文字，而非仅变红
□ 状态区分：色块 + 形状/文字标签
□ 图表：用色 + 图案/直接标注数值
□ 链接：下划线或加粗，而非仅靠颜色

/* 尊重系统偏好，而不是覆盖它 */
:root { color-scheme: light dark; }
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
@media (prefers-contrast: more) {
  :root { --border: #000; --text-muted: #333; }
}

动效无障碍：
□ 尊重 prefers-reduced-motion，关闭视差与自动播放
□ 自动播放的视频默认静音 + 可暂停（WCAG 1.4.2）
□ 闪烁频率 < 3Hz，避免光敏性癫痫
□ 动画不作为唯一的反馈手段

认知无障碍：
□ 语言简单、句子短、避免行话
□ 表单标签明确、错误信息给出「怎么改」
□ 一致的导航与命名，降低记忆负担

移动端触控无障碍：
□ 触控目标 ≥ 44×44 px（iOS HIG）/ 48×48 dp（Material）
□ 目标间距足够，避免误触相邻按钮
□ 手势必须有单点替代（滑动删除 → 也提供按钮）

自动化能查（约 30~40% 的问题）：
□ 缺失 alt / aria-label
□ 对比度不足
□ 表单缺 label
□ 无效的 ARIA 角色
□ 标题层级跳跃（h1 → h3）

自动化查不出（必须人工）：
□ 焦点顺序是否合理
□ alt 文本是否有意义（「图片」也是合法 alt，但没价值）
□ 屏幕阅读器体验是否连贯

// CI 中的组件级断言：违规即失败
import { axe } from 'jest-axe';

test('发帖编辑器无无障碍违规', async () => {
  const { container } = render(<Composer />);
  const results = await axe(container, {
    rules: { 'color-contrast': { enabled: true } },
  });
  expect(results).toHaveNoViolations();
});

包容性设计的三个延伸：
□ 设备包容：低端机、慢网络、小存储也能用
  · 首屏体积预算、图片渐进加载、离线降级
□ 语言包容：多语言、RTL 布局、本地化日期与数字
□ 能力包容：不同阅读水平、不同文化背景、不同输入方式