网页可访问性（WCAG 2 AA）

通过在设计系统中内建可访问性，而非事后审计，使界面符合 WCAG 2 AA 级标准。一个颜色、文本样式或组件，若在进入系统时已满足 AA 级要求，则其将自动适配所有使用它的页面；反之，若不满足，则会在所有使用它的页面上同时成为可访问性缺陷。

合规目标：WCAG 2.2 AA 级（快速参考指南）。

实施顺序

1. 先处理 Tokens（设计令牌） —— 在任何组件使用前，先以前景色/背景色成对方式验证调色板。
2. 再处理 Components（组件） —— 每个组件的状态（state）、焦点（focus）、目标尺寸（target size）、语义（semantics）等。
3. 最后处理 Pages（页面） —— 页面结构、标题层级、替代文本（alt text）、键盘导航走查（keyboard walk-through）等。

修复一个不合规的 Token，即可修复所有依赖它的组件；而修复一个不合规的页面，仅解决该页面的问题。请自上而下推进工作。

1. 颜色对比度是数学问题，而非主观判断

切勿凭肉眼估算对比度。阈值要求（依据 WCAG 2.2）如下：

运行内置的对比度校验脚本（无外部依赖，Node ≥14）：

# 临时校验单对：fg,bg,minimum,label
node scripts/check-contrast.mjs --pair "#0f766e,#ffffff,4.5,link on white"

# 从 JSON 配置文件批量校验整个调色板（格式详见脚本头部注释）
node scripts/check-contrast.mjs contrast-pairs.json

将其集成至构建流程中。 仅运行一次的对比度检查属于审计行为；而集成进 npm run build 或 CI 流程、并在失败时以非零退出码终止构建的检查，则构成一项强制保障。请为每个主题（theme）中所有以文本或具语义图形形式渲染的 Token 对，全部加入校验配置。

2. 从设计源头保障颜色可访问性的 Token 模式

以下三种模式可覆盖绝大多数实际调色板失效场景：

• 分离填充角色与文本角色。 鲜艳的品牌色（如青绿色、橙色、中蓝色）通常可作为 深色文字的背景填充 通过对比度检测，但作为 浅色背景上的文字 时往往失败——有时差距达两倍。因此应分别定义两类 Token，并禁止组件跨角色混用：

  --color-primary:      #14b8a6;  /* 用于填充、边框、焦点环 —— 绝不用于浅色背景上的文字 */
  --color-primary-text: #0f766e;  /* 同一色相，但足够深以满足文本对比度（≥4.5:1） */
  

  于是，实心按钮可根据主题动态选择文字颜色：亮色填充配深色文字，或深色填充配浅色文字——具体采用哪一组，由脚本验证决定，而非主观审美偏好。

• 按主题调节语义色。 在近黑色背景（如 #f59e0b 琥珀色、#ef4444 红色）下可读性良好的 success/warning/error 色值，在白色背景上可能失效——例如琥珀色在白底上对比度仅约 2.2:1。因此应为 --color-success/--color-warning/--color-error 分别配置深色主题与浅色主题的取值，而非共用同一套值：深色主题保留明亮色阶，浅色主题则采用更暗的色阶（例如 #b45309、#dc2626）。

• 弱化文本存在明确亮度下限。 占位符（placeholder）、提示（hint）和说明文字（caption）仍属文本范畴，必须满足 4.5:1 对比度。诸如 #9ca3af 这类中灰在白底上对比度约为 2.5:1，是全网最常出现的可访问性违规项。白底上满足 AA 级的最浅灰色约为 #767676；请将您的“弱化”Token 设定为此亮度值或更低。

3. 可缩放的排版系统

• 使用相对单位（rem/em）定义字体大小、行高及容纳文本的容器尺寸——浏览器缩放与文字大小调整必须支持放大至 200%，且不丢失内容（成功标准 SC 1.4.4）。
• 正文字体 ≥ 1rem（即 16px）；切勿使用 html { font-size: 62.5% } 等技巧强行锁定像素尺寸，从而覆盖用户设置的字体大小偏好。
• 正文行高 ≥ 1.5；段落间距应大于行高（成功标准 SC 1.4.12 要求内容能承受这些属性被用户强制修改）。
• 不可仅依赖颜色传达含义（成功标准 SC 1.4.1）：需搭配图标、字重、下划线或文字标签共同表达；嵌入正文中的链接，不能仅靠色相变化来区分。

4. 交互状态

• 每个可交互元素均需提供 :focus-visible 样式 —— 至少 2px 宽的轮廓线，且与周围表面保持 ≥3:1 的对比度（成功标准 SC 2.4.7、2.4.13）。禁用 outline: none 时，必须提供功能等效的视觉焦点指示。
• 悬停（hover）与激活（active）状态的颜色变更也须满足对比度要求。 悬停时变深的链接两次均通过；而向背景色趋近变亮的链接，恰恰在用户注视它时失效。请将各类状态色同样纳入对比度配置中校验。
• 目标尺寸 ≥ 24×24 CSS 像素（成功标准 SC 2.5.8）—— 包括按钮、导航链接、图标按钮等。主控件推荐维持 44px 的舒适默认尺寸。
• 尊重 prefers-reduced-motion 媒体查询 —— 将非必要动画置于该媒体查询条件之下启用。

5. 语义化检查清单（Tokens 无法自动修复的部分）

请针对每个组件或页面逐项核查；详细说明与修复方案参见 references/wcag-checklist.md：

• 图片：alt 文本需准确描述该图片在此处的 功能或作用；纯装饰性图片应设为 alt=""（1.1.1）
• 页面有且仅有一个

  ；标题严格按逻辑层级递进，不得为样式目的跳级（1.3.1）

• 使用真实语义化元素：、、 —— 禁止用样式化的
  模拟（4.1.2）
• 每个表单控件均有明确关联的标签；错误信息需以文本形式呈现，不可仅依赖颜色（3.3.1、3.3.2）
• 完整键盘导航走查：可抵达（reach）、可操作（operate）、可离开（leave）每一项；Tab 键顺序符合逻辑；页面级导航区域需提供“跳过链接”（skip link）（2.1.1、2.1.2、2.4.1）
• 当前页面或状态需明确标识（如 aria-current="page"、aria-expanded 等）
• 页面需声明 lang 属性，并设置具备描述性的