wangjia
4d274aad7a
用 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>
164 lines
9.7 KiB
HTML
164 lines
9.7 KiB
HTML
<!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>
|