bashi-website/ui-design-spec.md

巴适伙伴 · 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 末尾。
2. skip-to-content 链接：加在 SiteShell.tsx，<main> 加 id="main-content"；三语文案（跳到主要内容 / 跳到主要內容 / Skip to main content）；默认隐藏、键盘 Tab 聚焦时滑入显现。
3. 清理死 CSS：删除 global.css 中 0 引用的 .status-badge / .status-developing / .status-planned / .progress-glow / .progress-glow::after / @keyframes progressShine（删除前 Select-String 全 src 复核确认零引用）。
4. --fs-* 令牌迁移：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（更符合人眼；中风险）。