docs(ds-flow): Phase 0 — CLAUDE.md 增前端设计系统治理章节

新增「## 前端设计系统治理（ds-flow）」:心智模型(原型单源·代码镜像·静态闸
拦漂移·golden/fidelity 双级验收)、原型三件套(design/prototype/ tokens/atoms/
icons/index.html)、L1/L2/L3 三层治理、codegen(Flutter 生成 + Web 同源不重复
生成)、四道静态闸「违规谁拦」对照表、双级像素验收、pre-commit 启用说明。

⏳ 标注部件为 Phase 1-5 建设中,诚实反映当前落地状态,指向计划 #19。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -90,6 +90,50 @@ cd web/website   && npm run gen:tokens
 - `design/flutter/` 已删除；Flutter 组件 canonical 实现在 `client/lib/widgets/`，规格在 `design/preview/`。
 - **禁止**再向 `design/` 提交 Dart/TS 组件代码副本（会漂移）。
 
+## 前端设计系统治理（ds-flow）
+
+> **落地中**（分阶段收口，见计划 `docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md`
+> / 阅读版 `docs/frontend-ds-refactor-plan.html` / todo #19）。以下是**目标模型与硬规则**；
+> 标注「⏳」的部件正在建，未标注的已生效。参考样板 `~/code/jiu`。
+
+**心智模型**：设计只有一个出生地（**原型单源**），代码永远是镜像；跨端副本是否走样由
+**静态闸**在提交/CI 前拦截，像素是否还原由 **golden/fidelity 双级验收**兜底。主题：**light / dark 双主题**。
+
+**原型单源** `design/prototype/`（⏳ 建设中，Phase 1）：
+- `tokens.css` — 令牌真源：基础 `:root`（主题无关标量：间距/圆角/字号/字体/阴影/动效）+ `[data-theme=dark]` 颜色覆盖块。
+  （当前真源仍是 `design/colors_and_type.css`，Phase 1 迁移后数值不变、结构规整）
+- `atoms.css` — 公用组件原子（按钮/卡片/输入/语言下拉/徽章/状态药丸），**只引 `var(--token)`，禁硬编码**。
+- `icons.js` — SVG sprite 单源（`<symbol id="i-*">`）；website/usercenter/Flutter 三处图标集须 ⊆ 此集。
+- `index.html` — 活登记页：主题切换 + 声明式色板 + 全组件/图标展示卡。**每个 atom 必须在此登记**。
+- `serve.mjs` — 零依赖热重载预览；评审给 URL，**不截图**。
+
+**三层治理**：
+- **L1 设计系统**：新增颜色/组件/图标——**先登记原型，再同步代码**，无例外。跨端映射（状态词→图标）两端同集要有闸。
+- **L2 屏级三态**（台账记 `design/CONTRACT.md`）：`同步`=入 fidelity；`快照`=原型退役、golden+契约为准；`代码先行`=无原型屏、golden 唯一基准。
+- **L3 新屏/改版**：design-first——原型 → serve 评审 → 契约 → 实现 → 验收 → 入同步态。
+
+**codegen**：
+- Flutter：`node design/codegen/gen_flutter_tokens.mjs` → `pangolin_tokens.gen.dart`（**勿手改**）。
+- Web：`build-tokens.mjs`（website→`src/styles/tokens.gen.css` / usercenter→`public/colors_and_type.css`），
+  **只同源不重复生成设计决策**；靠同源闸逐值校验（不建跨端共享组件包，两端各自实现）。
+
+**四道静态闸 —「违规谁拦」**（规则没上闸 = 没有规则）：
+
+| 闸 | 拦什么 | 何时 |
+|---|---|---|
+| 原型校验 `check-ds.mjs`（⏳ Phase 5） | 硬编码色/未定义 token/未登记组件/魔法数断点… 12 道 | pre-commit（动了原型）+ CI |
+| 跨端同源 `check-l1-sync.mjs`（⏳ Phase 2） | tokens 逐值/icons 同集/Web hex 白名单 | CI |
+| 代码色单源 `check_ds_code.mjs`（⏳ Phase 5） | Flutter 裸 `Color(0x)`/具名 `Colors.x`（`// ds-ignore: 理由` 豁免） | pre-commit（`--changed`）+ CI |
+| codegen 零 diff `ci/check-codegen-drift.sh`（**已生效**） | 重生成 token 后 `git diff` 非空即 fail | pre-commit + CI |
+
+**双级像素验收**：
+- **golden**（**已有**，`client/test/golden/`）：多主题回归自比（同渲染器），抓串色/漏 token；真字体加载防豆腐块、钉死 viewport/dpr/动态值。重录 `flutter test --update-goldens`，随功能 commit 入库。
+- **fidelity**（⏳ Phase 5，本地体检**不进 CI**）：原型 Chromium 截图 vs Flutter golden pixelmatch，逐屏阈值=实测残差+2pp；跨渲染器噪声大，故不入 CI。
+
+**pre-commit**：`.githooks/pre-commit` 已写，**每台机需 `bash ci/install-hooks.sh` 启用一次**（设 `core.hooksPath=.githooks`）。
+
+**发现硬编码色**：换 token；确属例外（`#fff/#000`/品牌 logo 固定色）加 `// ds-ignore: 理由` 或列白名单。
+
 ## client/ macOS 原生隧道(PacketTunnel 系统扩展 + 内嵌 libbox)
 
 内嵌 sing-box(`Libbox.xcframework`)的 `NEPacketTunnelProvider` **系统扩展**(站外 Developer ID

docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md

@@ -21,14 +21,14 @@
 
 ## Phase 0 — 更新 CLAUDE.md + 计划落库
 
-- [ ] 0.1 CLAUDE.md 新增「## 前端设计系统治理（ds-flow）」章节：
+- [x] 0.1 CLAUDE.md 新增「## 前端设计系统治理（ds-flow）」章节：
   - 原型单源位置（`design/prototype/`：tokens/atoms/icons/index.html 登记簿）+ 只读约定
   - codegen 命令（Flutter `gen_flutter_tokens.mjs`；Web `build-tokens.mjs` 同源）
   - 三层治理 L1/L2/L3 规则速查
   - 四道静态闸清单 + 「违规谁拦」对照表（原型校验 / 跨端同源 / 代码色单源 / codegen 零 diff）
   - golden（多主题回归自比）/ fidelity（对原型 pixelmatch，本地体检不进 CI）双闸定位
-- [ ] 0.2 本 `.md` 定稿 + 生成 HTML 阅读版 `docs/frontend-ds-refactor-plan.html`，登记进 `docs/index.html`「实现计划」
+- [x] 0.2 本 `.md` 定稿 + 生成 HTML 阅读版 `docs/frontend-ds-refactor-plan.html`，登记进 `docs/index.html`「实现计划」
-- [ ] 0.3 `/todo` 建 tier-1 条目跟踪本重构，拆 6 个子任务（对应 Phase 1-5 + 收尾）
+- [x] 0.3 `/todo` 建 tier-1 条目跟踪本重构，拆 6 个子任务（对应 Phase 1-5 + 收尾）
 
 ---