前端设计系统治理重构 ds-flow

用 ds-flow 把 Flutter 五端 + 官网 + 用户中心收口到「设计单源 · 代码镜像 · 静态闸拦漂移 · 双级像素验收兜底」

阅读版；执行真相源 docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md（含 checkbox）。
关键前提：pangolin 不是从零 bootstrap，已约 65% 达标——token 单源（含暗色）、Flutter codegen + drift 闸、golden + CI 闸、pre-commit（写好未启用）都在。本计划是补缺口 + Web 共享原子层去重，非推倒重来。主题保持 light / dark 双主题。

现状盘点

维度	现状	缺口
Token 单源	✓ colors_and_type.css（含 [data-theme=dark]）	迁为 ds-flow 原型结构
Flutter codegen / 主题层	✓ gen 层/实现层分离 + drift 闸	—
Flutter UI 硬编码	✓ 零裸 hex（唯 1 处裸色 adaptive_menu）	清 1 处
Flutter golden	✓ 36 张 + harness + 真字体 + CI	6 张 failure；缺 CJK 测试字体；覆盖不全
website / usercenter	✓ 179 / 171 处 var(--token)	零前端测试
跨端共享组件	✗ 下拉/按钮/卡片两端各写一遍	抽 atoms 对齐
原型三件套	⚠ 有 _ds_manifest/preview/ui_kits	缺 atoms.css / icons.js / index.html
静态闸	✓ redline / analyze+test / codegen-drift / golden	✗ 硬编码色扫描 / fidelity / Web 同源
pre-commit	⚠ .githooks 写好	默认未启用

已定决策

Web 去重：两端各自实现 + 同源闸（不建跨端组件包；成本低、风险小，符合 jiu 取舍）
ui_kits：jsx/css 端原型收敛为纯 HTML 原型并删副本（消除与「禁向 design/ 提组件代码副本」的冲突）
节奏：先定稿本计划，再逐刀执行（每刀 commit，tier-1 大改走确认闸）

执行阶段（6 阶段）

Phase 0 — 更新 CLAUDE.md + 计划落库

CLAUDE.md 补「前端设计系统治理（ds-flow）」章节：原型单源位置、codegen 命令、L1/L2/L3 三层规则、四道静态闸 +「违规谁拦」对照表、golden/fidelity 双闸定位
本计划 .md 定稿 + HTML 阅读版 + 登记 docs/index.html
/todo 建 tier-1 条目 + 6 子任务

Phase 1 — 原型单源三件套（design/prototype/）

把散在 ui_kits / preview / _ds_manifest.json 的东西收敛为 ds-flow 标准三件套。

serve.mjs 照搬 jiu（零依赖热重载）
tokens.css：现有 token 数值不变，重排为「基础 :root 标量 + [data-theme=dark] 颜色覆盖」结构
atoms.css：按钮/卡片/输入/语言下拉/徽章/状态药丸公用原子（只引 var(--token)）
icons.js：SVG sprite 单源，收敛 website / usercenter / Flutter 三处图标集
index.html：活登记页——light/dark 切换 + 声明式色板 + 全组件/图标展示卡（每 atom 必登记）
ui_kits jsx 副本提炼后删除；屏级布局参考迁 prototype/screens/

Phase 2 — Web token 升为一等公民 + 同源闸

两端 token 落点统一指向原型 tokens.css（website→tokens.gen.css / usercenter→public/colors_and_type.css）
tools/check-l1-sync.mjs（照搬 jiu 裁剪）：website / usercenter token 值逐值同源 + icons 同集 + Web hex 白名单扫描
build-tokens 幂等：重跑零 diff（纳入 CI）

Phase 3 — Web 共享原子层对齐工作量最大

各自实现 + 同源闸：两端对齐同一 atoms.css，靠闸防漂移。

抽公共原子：langsel / button / card / input / badge / pill → atoms.css canonical
website：website.css/site-extra.css 对齐 atoms 语义，非白/黑/logo 硬编码清零
usercenter：shared.tsx 的 card/input/LangSeg 对齐 atoms 语义，13 处硬编码核对
两端 langsel 一致性纳入登记；更新 CONTRACT.md（Web 原子清单 + 屏级三态台账）

Phase 4 — Flutter 收尾 + golden 补齐

清 adaptive_menu.dart 唯 1 处裸色 → token
测试字体补 CJK 子集（make-cjk-subset.sh → client/test/fonts + flutter_test_config 注册）
处理现存 6 张 failure diff，逐张确认后 --update-goldens 重录
golden 覆盖扩容：desktop/tablet/mobile 全屏 × light/dark 双主题矩阵
harness 对齐 jiu：多主题循环 + 钉死 viewport/dpr + ProviderScope 固定数据

Phase 5 — 静态闸挂满 + 启用 pre-commit + fidelity 体检

硬编码色扫描：Flutter check_ds_code.mjs（含 --changed）+ Web hex 并入 check-l1-sync
原型校验 check-ds.mjs（照搬 jiu 12 道，按 pangolin 断点/主题裁剪）
CI 串起来：原型校验 → 跨端同源 → 代码色单源 → codegen 零 diff（已有）→ 测试含 golden（补 mobile+主题）
启用 pre-commit：install-hooks 纳入文档，增挂 check-ds --changed（条件触发）
fidelity 像素闸（本地体检，不进 CI）：screens.mjs + fidelity.mjs，逐屏阈值=实测残差+2pp
全景文档 docs/frontend-overview.html（照搬 jiu 十节）+ 登记索引

Verification（端到端）

原型：serve.mjs 逐屏目检 light/dark；check-ds 12 道全绿
同源：check-l1-sync 全绿（tokens 逐值 / icons 同集 / Web hex 白名单）
Flutter：analyze + test（golden ×双主题）；check_ds_code 绿；codegen 重跑零 diff
Web：两端 build 通过；token 同源绿；langsel/button/card 对齐 atoms
fidelity：逐屏残差在阈内（首次校准记录实测值）
闸生效：install-hooks 后改一处硬编码色/未登记组件 → pre-commit 或 CI 拦下

不在本轮

新功能 / 新屏开发（本轮是治理重构）
iOS/iPad 专属布局深度优化（响应式已覆盖）
三主题扩展（保持 light/dark）

真相源（含 checkbox 执行跟踪）：docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md