# 巴适伙伴 · UI 设计规范（最新规范学习 + 项目审计落地）

> 本文是「查找最新 UI 设计规范 → 学习记忆 → 运用到项目」的产物。第 1–2 节是**学到的规范**（记忆），第 3 节是**对照本项目的审计**，第 4 节是**本次落地**，第 5 节是**可选后续**。
> 研究时间：2026-08。规范以 WCAG 2.2（W3C）、Design Tokens（W3C DTCG）、Material Design 3、现代 CSS（web.dev）为权威基线，结合 2026 趋势。

---

## 1. 研究来源（权威基线）
- **WCAG 2.2**（W3C，2023 发布，现行标准）：对比度、焦点、目标尺寸、跳转等可访问性准则。
- **Design Tokens Community Group**（W3C DTCG）：令牌分层与格式化标准。
- **Material Design 3**（Google）：色彩系统、动效、形状、高程的 web 友好体系。
- **web.dev / Smashing**：现代 CSS 实践（color-mix、OKLCH、clamp、container queries）。
- **2026 趋势**（行业报告）：动态自适应、流体间距/排版、主题感知令牌、动效克制、空间深度。

---

## 2. 最新 UI 设计规范要点（学习记忆）

### 2.1 Design Tokens 四层架构（2026 共识）
1. **Foundation（基础）**：颜色基值、字号比例、圆角基准、间距基线——系统的"物理常数"，极少变动。
2. **Semantic（语义）**：primary / success / warning / error / text / surface——映射到视觉表现，支持品牌调性切换。
3. **Contextual（情境）**：响应式/容器派生（如 `--space-*` 随屏宽缩放）。
4. **Intelligent（智能）**：AI/行为数据驱动（本项目不涉及）。
- **铁律**：单一真相源（single source of truth），组件只引用令牌不写散值；深色模式靠令牌覆盖而非重写。

### 2.2 WCAG 2.2 无障碍（核心规范骨架）
| 准则 | 要求 | 级别 |
|---|---|---|
| 1.4.3 对比度（最小） | 正文 ≥4.5:1；大字（≥18pt 或 ≥14pt 粗）≥3:1 | AA |
| 1.4.1 颜色用途 | 颜色不能是传达信息的唯一通道（需文字/图标冗余） | A |
| 1.4.11 非文本对比 | UI 组件/图形对象 ≥3:1 | AA |
| 2.1.1 键盘 | 全部功能可用键盘操作 | A |
| 2.4.1 绕过区块 | 提供"跳到主内容"链接 | A |
| 2.4.7 焦点可见 + 2.4.11 焦点外观 | 焦点指示器 ≥2 CSS px、与相邻色 ≥3:1 | AA |
| 2.5.8 目标尺寸（最小） | 交互元素 ≥24×24 CSS px（AA）；2.5.5 ≥44×44（AAA） | AA |
| 2.3.3 交互动画 | 尊重 `prefers-reduced-motion` | AAA |
| 3.1.1 / 3.1.2 页面语言 | `<html lang>` 随语种；外文片段标注 | A |
| 4.1.2 名称/角色/值 | 交互元素有可访问名（aria-label/原生语义） | A |

### 2.3 现代 CSS（2026 工程基线）
- **color-mix() / OKLCH**：感知均匀的混色与调阶（OKLCH 比 HSL 更符合人眼）。
- **clamp() 流体排版/间距**：无断点连续缩放，避免极端屏崩坏。
- **container queries**：组件级响应式（比视口 media query 更内聚）。
- **逻辑属性**：`margin-inline`/`inset` 等，天然支持 RTL。
- **prefers-color-scheme + color-scheme**：原生暗色 + 表单控件自动适配。
- **:focus-visible**：仅键盘聚焦显指示器，不干扰鼠标。

### 2.4 2026 趋势（取舍）
- 动态自适应（弱网降级、环境光调对比）——方向正确，落地需克制，避免过度工程。
- 流体间距（间距随屏宽缩放）——优于固定 8px，但需防过度变形。
- 动效克制（长周期、低强度，避免视觉疲劳）——本项目已践行（40s/50s drift）。
- 空间深度（AR/3D）——官网不涉及。

### 2.5 视觉层级与一致性
- 8px 间距网格；模块化字号阶梯（display > h1 > h2 > h3 > body > micro）。
- 语义化用色（强调色按显示角色分档，各档过 WCAG 阈值）。
- 克制圆角（大块锐利、小元素圆润，形成层次）。
- 微交互有目的（hover 微浮、状态反馈），不炫技。

---

## 3. 项目审计（对照规范）

### ✅ 已合规项（设计系统成熟）
- **Design Tokens**：Foundation（`--brand-*`、`--fs-*`、`--space-*`、`--radius-*`、`--duration-*`）+ Semantic（`--accent`、`--status-*`、`--surface-*`、`--text-*`）齐备；赛道色 `--track-*` 单源（经 `src/lib/tracks.ts` 的 `TRACK_TOKEN`）。
- **主题感知 + 暗色模式**：`[data-theme="dark"]` 覆盖块 + `useTheme.ts` 三态切换 + `index.html` 防 FOUC 内联脚本。
- **color-mix**：大量用于派生色（赛道卡片底、描边、阴影）。
- **流体排版**：`--fs-*` 全部用 `clamp()`。
- **8px 间距网格**：`--space-1..11`。
- **:focus-visible**：全局 2px outline + offset（2.4.7/2.4.11 ✓）。
- **prefers-reduced-motion**：全局守卫降级动画时长（2.3.3 ✓）。
- **键盘可达**：flip-card 支持键盘/触摸/点击翻转，Esc 关下拉（2.1.1 ✓）。
- **html lang**：随路由语种切换 `zh-CN`/`zh-HK`/`en`（3.1.1 ✓）。
- **landmark**：`<main>` 语义标签。
- **动效克制**：长周期低强度（mesh 40s、渐变文 14s），有注释记录"降低强度"。
- **`<html lang>`、hreflang、OG/Twitter、JSON-LD**：SEO + 无障碍元数据完备。

### ⚠️ 差距与修复
| 差距 | 规范 | 状态 |
|---|---|---|
| 缺 skip-to-content 跳转链接 | WCAG 2.4.1 | **已修复**（首次） |
| `.status-badge/.status-developing/.status-planned/.progress-glow` 死 CSS（src 0 引用已复核） | 一致性 | **已清理**（本次） |
| 触控目标：桌面端导航 ≈24px（达 AA 24px 下限） | WCAG 2.5.8 | **已加固**（本次，navBase 加 `py-1.5` → ~28px，安全过 AA） |
| 组件内 `text-[Npx]` 硬编码未走 `--fs-*` 令牌 | Tokens 单源 | **已迁移**（Header.tsx 4 处 `text-[16px]`→`text-body`；全 src 复核无 `text-[15px]` 散落，其余页面已用令牌） |

---

## 4. 本次落地（已执行并验证）
1. **`.sr-only` + `.skip-link` 工具类**：新增于 [global.css](src/styles/global.css) 末尾。
2. **skip-to-content 链接**：加在 [SiteShell.tsx](src/components/SiteShell.tsx)，`<main>` 加 `id="main-content"`；三语文案（跳到主要内容 / 跳到主要內容 / Skip to main content）；默认隐藏、键盘 Tab 聚焦时滑入显现。
3. **清理死 CSS**：删除 [global.css](src/styles/global.css) 中 0 引用的 `.status-badge / .status-developing / .status-planned / .progress-glow / .progress-glow::after / @keyframes progressShine`（删除前 `Select-String` 全 src 复核确认零引用）。
4. **`--fs-*` 令牌迁移**：[Header.tsx](src/components/Header.tsx) 4 处 `text-[16px]` → `text-body`（走 `--fs-body`=16px 令牌，1:1 视觉等价）；保留 `text-[27px]`（品牌字标，无对应令牌）与 `text-[10px]`（▼ 装饰符，无对应令牌）。
5. **触控目标加固（WCAG 2.5.8）**：桌面端 `navBase` 加 `py-1.5`，链接触控目标由 ~24px（贴 AA 下限）提升至 ~28px，安全过 AA 24px；移动端 `mobileNavBase` 原有 `py-2.5`（~36px）保持不变。
6. **验证**：dev server HMR 干净生效（global.css + Header.tsx 多次 hmr update，零报错）。

---

## 5. 可选后续（opt-in，未动，需你拍板优先级）
> A（死 CSS 清理）、B（`--fs-*` 令牌迁移：Header 已完成，全 src 复核无其他 `text-[Npx]` 散落）、F（触控目标加固）均已在本次落地，从清单移除。

- **C. 流体间距**：把 `--space-*` 升级为 `clamp()` 极端屏自适应（中风险，需逐页验证）。
- **D. 容器查询**：关键卡片组件改 container query（重构，中高风险）。
- **E. OKLCH 色彩空间**：派生色从 `color-mix(in srgb)` 迁到 `in oklch`（更符合人眼；中风险）。
```