Pangolin 前端全景 ds-flow

设计只有一个出生地（原型单源），代码永远是镜像；漂移由静态闸拦在提交/CI 前，还原由 golden 双主题验收兜底。

Flutter 五端（macOS/iOS/iPad/Android/Windows，共享 client/lib/）+ 官网 web/website/ + 用户中心 web/usercenter/。主题：light / dark 双主题。治理落地见实现计划。

① 一次 UI 改动的标准路径

加/改令牌 → 只改 design/prototype/tokens.css → codegen（Flutter gen_flutter_tokens / Web gen:tokens）加/改原子 → design/prototype/atoms.css 定义 + index.html 登记 → 落 canonical 实现（client/lib/widgets 或 web/*）加/改图标 → design/prototype/icons.js sprite 登记 → 三端只从此集取改完自检 → check-codegen-drift · check-l1-sync · check_ds_code · check-ds 四道闸 + flutter test（golden）评审原型 → node design/prototype/serve.mjs → http://localhost:5180/（给 URL，不截图）

② 目录地图

层	位置	角色
原型单源（L1 真源）	`design/prototype/`	tokens.css · atoms.css · icons.js · index.html 登记页 · serve.mjs
令牌 codegen	`design/codegen/gen_flutter_tokens.mjs` · `web/*/scripts/build-tokens.mjs`	tokens.css → Flutter .gen.dart / Web token CSS
Flutter 实现	`client/lib/{pangolin_theme.dart, widgets/, screens/, shell/}`	实现层 + canonical 组件；五端共享，响应式非平台分叉
Web 实现	`web/website/`（Astro）· `web/usercenter/`（Next 静态）	各自实现，对齐 atoms.css，靠同源闸防漂移
历史参考	`design/ui_kits/` DEPRECATED	旧整屏原型，仅历史参考，勿当真源

③ 三层真相源模型

L1 设计系统：新增颜色/组件/图标——先登记原型，再同步代码，无例外。
L2 屏级三态（台账 design/CONTRACT.md §6）：同步=入 fidelity；快照=原型退役、golden+契约为准；代码先行=无原型屏、golden 唯一基准。当前：Flutter 屏=快照，Web 屏=代码先行，原子层=同步。
L3 新屏/改版：design-first——原型 → serve 评审 → 契约 → 实现 → 验收 → 入同步态。

④ 令牌 codegen（颜色单源落地）

design/prototype/tokens.css（base :root 标量 + [data-theme=dark] 颜色覆盖）是唯一被解析的真源。colors_and_type.css 已降级为薄 @import 别名。Flutter 生成 pangolin_tokens.gen.dart（勿手改）；Web 由 build-tokens 原样同步（仅移除第三方字体 @import），不重复生成设计决策，靠同源闸逐值校验。

⑤ 四道静态闸 —「违规谁拦」

闸	拦什么	何时	状态
原型校验 `design/prototype/tools/check-ds.mjs`	硬编码色（atoms.css）/未定义 token/字体/图标未走 sprite/原子未登记	pre-commit（动原型）+ CI	✓
跨端同源 `tools/check-l1-sync.mjs`	Web token 值≡原型 · 三端图标⊆原型 sprite · Web 硬编码色	pre-commit（动原型/web）+ CI	✓
代码色单源 `client/tool/check_ds_code.mjs`	Flutter 裸 `Color(0x)`/具名 `Colors.x`（`ds-ignore` 豁免）	pre-commit（--changed）+ CI（--strict）	✓
codegen 零 diff `ci/check-codegen-drift.sh`	重生成 token 后 git diff 非空即 fail	pre-commit + CI	✓

CI（.gitea/workflows/ci.yml）的 ds-flow job 串起前三道；codegen-drift job 管第四道。pre-commit（.githooks/pre-commit，一次性 bash ci/install-hooks.sh 启用）跑条件化快子集。

⑥ 像素验收

golden（回归自比，已进 CI）：client/test/golden/，多主题同渲染器自比，抓串色/漏 token。真字体加载（含 Noto Sans SC 子集，中文不出豆腐块）、钉死 viewport/dpr/动态值（provider override）。基线在权威 Linux 容器生成：bash scripts/update-goldens.sh。当前 34 tests 全绿（components/auth/desktop/tablet × 双主题，tablet 含 zh/en）。
fidelity（保真体检，本地不进 CI） 待建：原型整屏截图 vs Flutter golden pixelmatch。前置：原型需先有整屏 HTML（design/prototype/screens/，属 L3 新屏工作）——当前原型仅原子层，无屏可比，故 fidelity 待整屏落地后建。

⑦ 响应式与五端

五端共享 client/lib/，UI 无平台分叉，靠 core/responsive/form_factor.dart（mobile/tablet/desktop 按宽度+平台判定）。平台差异隔离在 bridge/update/tray 等系统集成层，非 UI。

⑧ 规则速查（硬红线）

颜色只走语义 token；colors_and_type.css 勿加变量（改 prototype/tokens.css）。
加原子/图标先登记原型再落代码；勿向 design/ 提 Dart/TS 组件副本。
文案脱敏：禁 VPN/翻墙/科学上网等红线词（ci/scan-redline.sh 守护）。
硬编码色例外（#fff/#000/品牌 logo 色）加 // ds-ignore: 理由 或列白名单。
改 UI 提交前：四道闸绿 + flutter test（含 golden）；golden 重录随功能 commit 入库。

⑨ 文档索引

前端设计系统治理重构 · 实现计划（真相源 docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md）
根 CLAUDE.md「## 前端设计系统治理（ds-flow）」· design/CLAUDE.md（设计铁律 + 真源对照）· design/CONTRACT.md §6（Web 原子清单 + 屏级台账）

最后更新随治理重构（Phase 0–5）。fidelity（⑥）与 mobile golden 扩容为后续项。