docs(plan): 前端设计系统治理重构（ds-flow 全端）实现计划

用 ds-flow 把 Flutter 五端 + 官网 + 用户中心收口到「设计单源·代码镜像· 静态闸拦漂移·golden/fidelity 双级像素验收兜底」。摸底结论:pangolin 非从零 bootstrap,已约 65% 达标(token 单源含暗色、 Flutter codegen+drift 闸、golden+CI 闸、pre-commit 写好未启用)。本计划是补缺口 + Web 共享原子层去重,非推倒重来。主题保持 light/dark。 6 阶段:CLAUDE.md → 原型三件套(atoms/icons/index.html,收敛 ui_kits) → Web token 同源闸 → Web 原子层去重(各自实现+同源闸) → Flutter 收尾+golden 补齐 → 静态闸挂满+启用 pre-commit+fidelity 体检。真相源(含 checkbox)+ HTML 阅读版 + 登记 docs/index.html;todo #19 tier-1。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-07 23:41:50 +08:00
parent 84448b3064
commit 4d274aad7a
5 changed files with 504 additions and 25 deletions
@@ -0,0 +1,163 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>前端设计系统治理重构（ds-flow）· 实现计划</title>
+<style>
+  :root{
+    --bg:#0f1117; --panel:#171a22; --panel2:#1d2129; --fg:#e6e8ee; --fg2:#a8afbd;
+    --accent:#e0884f; --accent2:#5fb0c9; --ok:#5ec27a; --bad:#e06a6a; --warn:#e0b84f;
+    --border:#272c36; --mono:"SF Mono",ui-monospace,Menlo,Consolas,monospace;
+    --sans:-apple-system,"PingFang SC","Helvetica Neue",Arial,sans-serif;
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--fg);font-family:var(--sans);line-height:1.7;font-size:15px}
+  .wrap{max-width:920px;margin:0 auto;padding:48px 24px 96px}
+  h1{font-size:29px;line-height:1.3;margin:0 0 8px;letter-spacing:-.01em}
+  .sub{color:var(--fg2);font-size:15px;margin:0 0 28px}
+  h2{font-size:20px;margin:38px 0 12px;padding-bottom:8px;border-bottom:1px solid var(--border)}
+  h3{font-size:16px;margin:22px 0 8px;color:var(--accent)}
+  p{margin:10px 0}
+  code{font-family:var(--mono);font-size:.86em;background:var(--panel2);padding:1px 6px;border-radius:5px;color:#f0d9c4}
+  a{color:var(--accent2);text-decoration:none} a:hover{text-decoration:underline}
+  .lead{background:linear-gradient(180deg,rgba(224,136,79,.10),transparent);border:1px solid var(--border);border-radius:12px;padding:18px 20px;margin:0 0 20px}
+  .small{color:var(--fg2);font-size:13px}
+  .phase{background:var(--panel);border:1px solid var(--border);border-radius:12px;padding:16px 20px;margin:14px 0}
+  .phase h2{margin-top:4px;border:none;padding:0;font-size:18px}
+  ul{margin:8px 0;padding-left:22px} li{margin:5px 0}
+  .box{overflow-x:auto;margin:14px 0}
+  table{border-collapse:collapse;width:100%;font-size:13.5px;min-width:560px}
+  th,td{border:1px solid var(--border);padding:7px 10px;text-align:left;vertical-align:top}
+  th{background:var(--panel2);color:var(--fg)}
+  .ok{color:var(--ok);font-weight:700} .bad{color:var(--bad);font-weight:700} .warn{color:var(--warn);font-weight:700}
+  .pill{display:inline-block;font-size:11px;font-weight:700;padding:1px 8px;border-radius:999px;margin-left:6px}
+  .pill.big{background:rgba(224,106,106,.16);color:var(--bad)}
+  .tag{display:inline-block;font-size:11px;font-weight:700;padding:1px 8px;border-radius:999px;background:rgba(94,194,122,.14);color:var(--ok);margin-left:8px;vertical-align:middle}
+  .back{color:var(--fg2);font-size:13px}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<p class="back"><a href="index.html">← 文档索引</a></p>
+<h1>前端设计系统治理重构 <span class="tag">ds-flow</span></h1>
+<p class="sub">用 ds-flow 把 Flutter 五端 + 官网 + 用户中心收口到「设计单源 · 代码镜像 · 静态闸拦漂移 · 双级像素验收兜底」</p>
+
+<div class="lead">
+<strong>阅读版</strong>；执行真相源 <code>docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md</code>（含 checkbox）。<br>
+<strong>关键前提</strong>：pangolin <b>不是从零 bootstrap，已约 65% 达标</b>——token 单源（含暗色）、Flutter codegen + drift 闸、golden + CI 闸、pre-commit（写好未启用）都在。本计划是<b>补缺口 + Web 共享原子层去重</b>，非推倒重来。主题保持 <b>light / dark 双主题</b>。
+</div>
+
+<h2>现状盘点</h2>
+<div class="box">
+<table>
+<tr><th>维度</th><th>现状</th><th>缺口</th></tr>
+<tr><td>Token 单源</td><td class="ok">✓ colors_and_type.css（含 [data-theme=dark]）</td><td>迁为 ds-flow 原型结构</td></tr>
+<tr><td>Flutter codegen / 主题层</td><td class="ok">✓ gen 层/实现层分离 + drift 闸</td><td>—</td></tr>
+<tr><td>Flutter UI 硬编码</td><td class="ok">✓ 零裸 hex（唯 1 处裸色 adaptive_menu）</td><td>清 1 处</td></tr>
+<tr><td>Flutter golden</td><td class="ok">✓ 36 张 + harness + 真字体 + CI</td><td class="warn">6 张 failure；缺 CJK 测试字体；覆盖不全</td></tr>
+<tr><td>website / usercenter</td><td class="ok">✓ 179 / 171 处 var(--token)</td><td class="bad">零前端测试</td></tr>
+<tr><td>跨端共享组件</td><td class="bad">✗ 下拉/按钮/卡片两端各写一遍</td><td>抽 atoms 对齐</td></tr>
+<tr><td>原型三件套</td><td class="warn">⚠ 有 _ds_manifest/preview/ui_kits</td><td>缺 atoms.css / icons.js / index.html</td></tr>
+<tr><td>静态闸</td><td class="ok">✓ redline / analyze+test / codegen-drift / golden</td><td class="bad">✗ 硬编码色扫描 / fidelity / Web 同源</td></tr>
+<tr><td>pre-commit</td><td class="warn">⚠ .githooks 写好</td><td class="bad">默认未启用</td></tr>
+</table>
+</div>
+
+<h2>已定决策</h2>
+<ul>
+<li><b>Web 去重</b>：两端<b>各自实现 + 同源闸</b>（不建跨端组件包；成本低、风险小，符合 jiu 取舍）</li>
+<li><b>ui_kits</b>：jsx/css 端原型<b>收敛为纯 HTML 原型</b>并删副本（消除与「禁向 design/ 提组件代码副本」的冲突）</li>
+<li><b>节奏</b>：<b>先定稿本计划，再逐刀执行</b>（每刀 commit，tier-1 大改走确认闸）</li>
+</ul>
+
+<h2>执行阶段（6 阶段）</h2>
+
+<div class="phase">
+<h2>Phase 0 — 更新 CLAUDE.md + 计划落库</h2>
+<ul>
+<li>CLAUDE.md 补「前端设计系统治理（ds-flow）」章节：原型单源位置、codegen 命令、L1/L2/L3 三层规则、四道静态闸 +「违规谁拦」对照表、golden/fidelity 双闸定位</li>
+<li>本计划 .md 定稿 + HTML 阅读版 + 登记 docs/index.html</li>
+<li>/todo 建 tier-1 条目 + 6 子任务</li>
+</ul>
+</div>
+
+<div class="phase">
+<h2>Phase 1 — 原型单源三件套（design/prototype/）</h2>
+<p class="small">把散在 ui_kits / preview / _ds_manifest.json 的东西收敛为 ds-flow 标准三件套。</p>
+<ul>
+<li><code>serve.mjs</code> 照搬 jiu（零依赖热重载）</li>
+<li><code>tokens.css</code>：现有 token <b>数值不变</b>，重排为「基础 :root 标量 + [data-theme=dark] 颜色覆盖」结构</li>
+<li><code>atoms.css</code>：按钮/卡片/输入/<b>语言下拉</b>/徽章/状态药丸公用原子（只引 var(--token)）</li>
+<li><code>icons.js</code>：SVG sprite 单源，收敛 website / usercenter / Flutter 三处图标集</li>
+<li><code>index.html</code>：活登记页——light/dark 切换 + 声明式色板 + 全组件/图标展示卡（每 atom 必登记）</li>
+<li>ui_kits jsx 副本提炼后<b>删除</b>；屏级布局参考迁 <code>prototype/screens/</code></li>
+</ul>
+</div>
+
+<div class="phase">
+<h2>Phase 2 — Web token 升为一等公民 + 同源闸</h2>
+<ul>
+<li>两端 token 落点统一指向原型 tokens.css（website→tokens.gen.css / usercenter→public/colors_and_type.css）</li>
+<li><code>tools/check-l1-sync.mjs</code>（照搬 jiu 裁剪）：website / usercenter token 值逐值同源 + icons 同集 + Web hex 白名单扫描</li>
+<li>build-tokens 幂等：重跑零 diff（纳入 CI）</li>
+</ul>
+</div>
+
+<div class="phase">
+<h2>Phase 3 — Web 共享原子层对齐 <span class="pill big">工作量最大</span></h2>
+<p class="small">各自实现 + 同源闸：两端对齐同一 atoms.css，靠闸防漂移。</p>
+<ul>
+<li>抽公共原子：langsel / button / card / input / badge / pill → atoms.css canonical</li>
+<li>website：website.css/site-extra.css 对齐 atoms 语义，非白/黑/logo 硬编码清零</li>
+<li>usercenter：shared.tsx 的 card/input/LangSeg 对齐 atoms 语义，13 处硬编码核对</li>
+<li>两端 langsel 一致性纳入登记；更新 CONTRACT.md（Web 原子清单 + 屏级三态台账）</li>
+</ul>
+</div>
+
+<div class="phase">
+<h2>Phase 4 — Flutter 收尾 + golden 补齐</h2>
+<ul>
+<li>清 adaptive_menu.dart 唯 1 处裸色 → token</li>
+<li>测试字体补 CJK 子集（make-cjk-subset.sh → client/test/fonts + flutter_test_config 注册）</li>
+<li>处理现存 6 张 failure diff，逐张确认后 --update-goldens 重录</li>
+<li>golden 覆盖扩容：desktop/tablet/mobile 全屏 × light/dark 双主题矩阵</li>
+<li>harness 对齐 jiu：多主题循环 + 钉死 viewport/dpr + ProviderScope 固定数据</li>
+</ul>
+</div>
+
+<div class="phase">
+<h2>Phase 5 — 静态闸挂满 + 启用 pre-commit + fidelity 体检</h2>
+<ul>
+<li>硬编码色扫描：Flutter <code>check_ds_code.mjs</code>（含 --changed）+ Web hex 并入 check-l1-sync</li>
+<li>原型校验 <code>check-ds.mjs</code>（照搬 jiu 12 道，按 pangolin 断点/主题裁剪）</li>
+<li>CI 串起来：原型校验 → 跨端同源 → 代码色单源 → codegen 零 diff（已有）→ 测试含 golden（补 mobile+主题）</li>
+<li>启用 pre-commit：install-hooks 纳入文档，增挂 check-ds --changed（条件触发）</li>
+<li>fidelity 像素闸（本地体检，不进 CI）：screens.mjs + fidelity.mjs，逐屏阈值=实测残差+2pp</li>
+<li>全景文档 docs/frontend-overview.html（照搬 jiu 十节）+ 登记索引</li>
+</ul>
+</div>
+
+<h2>Verification（端到端）</h2>
+<ul>
+<li><b>原型</b>：serve.mjs 逐屏目检 light/dark；check-ds 12 道全绿</li>
+<li><b>同源</b>：check-l1-sync 全绿（tokens 逐值 / icons 同集 / Web hex 白名单）</li>
+<li><b>Flutter</b>：analyze + test（golden ×双主题）；check_ds_code 绿；codegen 重跑零 diff</li>
+<li><b>Web</b>：两端 build 通过；token 同源绿；langsel/button/card 对齐 atoms</li>
+<li><b>fidelity</b>：逐屏残差在阈内（首次校准记录实测值）</li>
+<li><b>闸生效</b>：install-hooks 后改一处硬编码色/未登记组件 → pre-commit 或 CI 拦下</li>
+</ul>
+
+<h2>不在本轮</h2>
+<ul>
+<li>新功能 / 新屏开发（本轮是治理重构）</li>
+<li>iOS/iPad 专属布局深度优化（响应式已覆盖）</li>
+<li>三主题扩展（保持 light/dark）</li>
+</ul>
+
+<p class="small" style="margin-top:32px">真相源（含 checkbox 执行跟踪）：<code>docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md</code></p>
+
+</div>
+</body>
+</html>
@@ -86,6 +86,11 @@
 </a>

 <h2>实现计划 / Plans</h2>
+<a class="doc" href="frontend-ds-refactor-plan.html">
+  <div class="t">前端设计系统治理重构（ds-flow 全端）<span class="tag html">HTML</span></div>
+  <div class="d">阅读版；执行真相源 <code>docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md</code>（含 checkbox）。用 ds-flow 把 Flutter 五端 + 官网 + 用户中心收口到「设计单源·代码镜像·静态闸拦漂移·golden/fidelity 双级像素验收兜底」。<b>非从零 bootstrap（已约 65% 达标）</b>：补原型三件套（atoms.css/icons.js/index.html 登记页）+ Web 共享原子层去重（各自实现+同源闸）+ 硬编码色/fidelity 闸 + 启用 pre-commit。6 阶段：CLAUDE.md → 原型单源 → Web token 同源 → Web 原子对齐 → Flutter golden 补齐 → 闸挂满。主题保持 light/dark。</div>
+  <div class="path">docs/frontend-ds-refactor-plan.html · 真相源 docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md</div>
+</a>
 <a class="doc" href="control-plane-tls-tunnel.html">
  <div class="t">控制面 TLS(Cloudflare Tunnel 前置)实现计划 <span class="tag html">HTML</span></div>
  <div class="d">阅读版；执行真相源 <code>docs/superpowers/plans/2026-07-06-control-plane-tls-tunnel.md</code>（含 checkbox）。把控制面 API 从明文 <code>http://103.119.13.48:8080</code> 迁到 <code>https://api.yanmeiai.com</code>（cloudflared 出站隧道前置，源站仅绑 127.0.0.1，数据面 sing-box REALITY :443 全程不动）。6 任务：CF Tunnel 供给 → 客户端切 https/Android 去明文 → CI 守护禁明文 → PANGOLIN_PUBLIC_URL 切 https → 退役明文口（收 loopback，带上线顺序闸）→ 文档。</div>
@@ -0,0 +1,132 @@
+# 前端设计系统治理重构（ds-flow 落地全端）
+
+> 用 ds-flow 方法论把 pangolin 全部前端（Flutter 五端 + 官网 website + 用户中心 usercenter）
+> 收口到「设计只有一个出生地（原型单源），代码永远是镜像；漂移由静态闸在提交/CI 前拦截，
+> 走样由 golden/fidelity 双级像素验收兜底」。
+>
+> **关键前提（摸底结论）**：pangolin 不是从零 bootstrap，已约 65% 达标——
+> token 单源（`design/colors_and_type.css` 含 `[data-theme=dark]`）、Flutter codegen + drift 闸、
+> golden + CI 闸、pre-commit（写好未启用）都在。本计划是**补缺口 + Web 共享原子层去重**，
+> 不是推倒重来。
+>
+> 主题模型：pangolin 用 **light / dark 两主题**（非 jiu 的 a/b/c 三主题），全程保持。
+>
+> 已定决策：① Web 两端**各自实现 + 同源闸**（不建跨端共享组件包）；
+> ② `design/ui_kits/` 的 jsx/css 端原型**收敛为纯 HTML 原型**并删副本；
+> ③ **先定稿本计划，再逐刀执行**（每刀 commit）。
+>
+> 参考样板：`~/code/jiu`（`design/prototype/` + `tools/` + `client/lib/core/theme/` + `docs/frontend-overview.html`）。
+
+---
+
+## Phase 0 — 更新 CLAUDE.md + 计划落库
+
+- [ ] 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`「实现计划」
+- [ ] 0.3 `/todo` 建 tier-1 条目跟踪本重构，拆 6 个子任务（对应 Phase 1-5 + 收尾）
+
+---
+
+## Phase 1 — 原型单源三件套（design/prototype/）
+
+把散在 `ui_kits/`（6 端 jsx/css 原型）+ `preview/`（20 规格 HTML）+ `_ds_manifest.json`（登记簿）
+的东西收敛成 ds-flow 标准三件套。
+
+- [ ] 1.1 建 `design/prototype/` 目录；`serve.mjs` 照搬 jiu（零依赖热重载，默认端口按 jiu）
+- [ ] 1.2 `design/prototype/tokens.css`：从现有 `colors_and_type.css` 迁移/规整为
+  「基础 `:root`（主题无关标量：间距/圆角/字号/字体/阴影/动效）+ `[data-theme=dark]` 颜色覆盖块」结构。
+  **保持数值不变**，只重排为 ds-flow 结构；`colors_and_type.css` 作为兼容别名或迁移为薄封装（不破坏现有 codegen）
+- [ ] 1.3 `design/prototype/atoms.css`：把按钮/卡片/输入/**语言下拉**/徽章/状态药丸等公用原子类沉淀为
+  只引 `var(--token)` 的 CSS（镜像 `design/preview/` 现有规格 + client widgets 实现语义）
+- [ ] 1.4 `design/prototype/icons.js`：SVG sprite 单源（`<symbol id="i-*">`），
+  收敛现有分散图标（website Icon.astro / usercenter icons.tsx / Flutter pangolin_icons.dart 三处的图标集）
+- [ ] 1.5 `design/prototype/index.html`：活登记页——三…两主题（light/dark）切换 + `data-swatches` 声明式色板 +
+  字号梯度 + 圆角/间距/阴影 + 全部公用组件原子展示卡 + 图标库全展示。**每个 atom 必须在此登记**
+- [ ] 1.6 `design/ui_kits/` 的 jsx/css 端原型：提炼进 prototype 后**删除 jsx 组件副本**（消除与
+  「禁向 design/ 提组件代码副本」的冲突 + 漂移源）；保留必要的屏级 HTML 布局参考迁进 `prototype/screens/`
+- [ ] 1.7 更新/退役 `_ds_manifest.json` + `_ds_bundle.js`：登记簿职责交给 `index.html`，
+  manifest 若仍被消费则保留为派生产物（记清谁是真源）
+
+---
+
+## Phase 2 — Web token 升为一等公民 + 同源闸
+
+现状：Web 的 `build-tokens.mjs` 只是「原样拷 css，删 Google Fonts 行」。升级为受闸守护的同源关系。
+
+- [ ] 2.1 确认两端 token 落点与生成链：website→`src/styles/tokens.gen.css`、
+  usercenter→`public/colors_and_type.css`；源统一指向 `design/prototype/tokens.css`（Phase 1 后）
+- [ ] 2.2 建 `tools/check-l1-sync.mjs`（照搬 jiu 裁剪）：
+  - ① website `tokens.gen.css` token 值 ≡ 原型 tokens.css（逐值）
+  - ② usercenter `public/colors_and_type.css` ≡ 原型（逐值）
+  - ③ icons 同源：website / usercenter / Flutter 三处图标集 ⊆ 原型 icons.js sprite
+  - ④ Web 硬编码色扫描（白名单 `#fff/#000/logo 固定色`，其余报警）
+- [ ] 2.3 codegen 幂等：重跑 `build-tokens.mjs` 后 `git diff` 零差异（纳入 CI，见 Phase 5）
+
+---
+
+## Phase 3 — Web 共享原子层对齐（各自实现 + 同源闸）★工作量最大
+
+不建跨端组件包；两端各自实现，但都对齐 `design/prototype/atoms.css`，靠闸保证不漂移。
+
+- [ ] 3.1 抽公共原子清单：langsel（语言下拉，刚修的两套合规范）/ button / card / input / badge / pill。
+  对每个原子在 `atoms.css` 定义 canonical 样式
+- [ ] 3.2 website：`website.css` + `site-extra.css` 里的按钮/卡片/下拉 class 对齐 atoms.css 语义，
+  残留 `#fff/#000`/logo 外的硬编码色清零（当前业务硬编码 ~30 处，多为可保留的白/黑/logo）
+- [ ] 3.3 usercenter：`shared.tsx` 的 `card/input/LangSeg` 内联对象对齐 atoms.css 语义；
+  残留 13 处硬编码（基本 `#fff`）核对，非白/黑/logo 的清零
+- [ ] 3.4 两端 langsel 行为/样式一致性核对（此前刚统一为自定义下拉，纳入 atoms 登记）
+- [ ] 3.5 更新 `design/CONTRACT.md`：Web 原子清单 + 屏级台账（同步/快照/代码先行三态）
+
+---
+
+## Phase 4 — Flutter 收尾 + golden 补齐
+
+Flutter 已很干净（UI 层零裸 hex），只需收尾。
+
+- [ ] 4.1 清 `client/lib/widgets/adaptive_menu.dart` 唯 1 处裸 Material 色 → 走 token
+- [ ] 4.2 测试字体补 CJK 子集：用 `tools/fonts/make-cjk-subset.sh` 生成 Noto Sans SC 子集放
+  `client/test/fonts/`，`flutter_test_config.dart` 注册——消除 golden 中文与生产渲染差异
+- [ ] 4.3 处理现存 6 张 `client/test/golden/failures/` diff：逐张确认「原型对得上」后 `--update-goldens` 重录入库
+- [ ] 4.4 golden 覆盖扩容：desktop/tablet/mobile 全屏 × light/dark 双主题矩阵
+  （现有 `desktop_pages/tablet_pages/components/auth` → 补 mobile + 主题维度）
+- [ ] 4.5 `client/test/helpers/harness.dart` 对齐 jiu `golden_harness.dart` 手法：
+  多主题循环辅助 + 钉死 viewport/dpr + ProviderScope 固定数据（防动态值翻车）
+
+---
+
+## Phase 5 — 静态闸挂满 + 启用 pre-commit + fidelity 体检
+
+- [ ] 5.1 硬编码色扫描闸：
+  - Flutter `client/tool/check_ds_code.mjs`（照搬 jiu，含 `--changed` 供 pre-commit）：禁 `Color(0x..)`/裸 `Colors.x`
+  - Web hex 扫描并入 `check-l1-sync.mjs` ④
+- [ ] 5.2 原型校验闸 `design/prototype/tools/check-ds.mjs`（照搬 jiu 12 道，按 pangolin 断点/主题裁剪）
+- [ ] 5.3 CI 串起来（`.gitea/workflows/ci.yml` 增补）：
+  原型校验 → 跨端同源 → 代码色单源 → codegen 零 diff（已有）→ 测试含 golden（已有，补 mobile+主题）
+- [ ] 5.4 启用 pre-commit：`ci/install-hooks.sh` 纳入 onboarding 文档 + CLAUDE.md，
+  `.githooks/pre-commit` 增挂 `check-ds --changed`（只在动了 `design/prototype/` 时跑，轻量条件触发）
+- [ ] 5.5 fidelity 像素闸（本地体检，不进 CI）：`tools/screens.mjs` 屏注册表 + `tools/fidelity.mjs`
+  （原型 Chromium 截图 vs Flutter golden pixelmatch，逐屏阈值=实测残差+2pp，两边统一注入 CJK 字体）
+- [ ] 5.6 全景文档 `docs/frontend-overview.html`（照搬 jiu 十节）：一次 UI 改动标准路径 + 目录地图 +
+  三层分治 + 闸全景 + 像素验收体系 + 响应式范式 + 规则速查，登记进 docs/index.html
+
+---
+
+## Verification（端到端）
+
+- **原型**：`node design/prototype/serve.mjs` 起服务，浏览器逐屏目检 light/dark；`check-ds.mjs` 12 道全绿
+- **同源**：`node tools/check-l1-sync.mjs` 全绿（tokens 逐值 / icons 同集 / Web hex 白名单）
+- **Flutter**：`flutter analyze` + `flutter test`（含 golden ×双主题）；`check_ds_code.mjs` 全绿；codegen 重跑零 diff
+- **Web**：两端 `npm run build` 通过；token 同源闸绿；langsel/button/card 对齐 atoms
+- **fidelity**：`node tools/fidelity.mjs` 逐屏残差在阈内（首次校准记录各屏实测值）
+- **闸生效**：`ci/install-hooks.sh` 后改一处硬编码色/未登记组件 → pre-commit 或 CI 拦下
+
+## 不在本轮
+
+- 新功能/新屏开发（本轮是治理重构，不加业务）
+- iOS/iPad 专属布局深度优化（响应式已覆盖，超阈再单独立项）
+- 三主题扩展（保持 light/dark 双主题）