docs(ds-flow): Phase 5.6 — 前端全景文档 frontend-overview.html
docs/frontend-overview.html(照 jiu 十节裁剪):一次 UI 改动标准路径 · 目录地图 · 三层真相源模型 · 令牌 codegen · 四道静态闸「违规谁拦」· 像素验收(golden 双主题 全绿含 CJK / fidelity 待建) · 响应式五端 · 规则速查 · 文档索引。登记进 docs/index.html。 同时标注两项延后(非阻塞,前置=原型整屏 HTML 属 L3 新屏工作): - 4.4 mobile golden 覆盖扩容 - 5.5 fidelity 像素闸(原型无整屏可比,待 design/prototype/screens/ 落地) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
wangjia
@@ -0,0 +1,108 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Pangolin 前端全景（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:960px;margin:0 auto;padding:44px 24px 96px}
|
||||
h1{font-size:28px;margin:0 0 6px;letter-spacing:-.01em}
|
||||
.sub{color:var(--fg2);margin:0 0 26px}
|
||||
h2{font-size:19px;margin:36px 0 12px;padding-bottom:8px;border-bottom:1px solid var(--border)}
|
||||
h3{font-size:15.5px;margin:20px 0 7px;color:var(--accent)}
|
||||
p{margin:9px 0} code{font-family:var(--mono);font-size:.85em;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:16px 20px;margin:0 0 22px}
|
||||
ul{margin:8px 0;padding-left:22px} li{margin:5px 0}
|
||||
.box{overflow-x:auto;margin:12px 0}
|
||||
table{border-collapse:collapse;width:100%;font-size:13.5px;min-width:600px}
|
||||
th,td{border:1px solid var(--border);padding:7px 10px;text-align:left;vertical-align:top}
|
||||
th{background:var(--panel2)} .ok{color:var(--ok);font-weight:700} .warn{color:var(--warn);font-weight:700}
|
||||
.flow{background:var(--panel);border:1px solid var(--border);border-radius:10px;padding:14px 18px;font-family:var(--mono);font-size:13px;white-space:pre;overflow-x:auto;color:var(--fg2)}
|
||||
.back{color:var(--fg2);font-size:13px}
|
||||
.pill{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:6px}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="wrap">
|
||||
<p class="back"><a href="index.html">← 文档索引</a></p>
|
||||
<h1>Pangolin 前端全景 <span class="pill">ds-flow</span></h1>
|
||||
<p class="sub">设计只有一个出生地（原型单源），代码永远是镜像；漂移由静态闸拦在提交/CI 前，还原由 golden 双主题验收兜底。</p>
|
||||
|
||||
<div class="lead">
|
||||
Flutter 五端（macOS/iOS/iPad/Android/Windows，共享 <code>client/lib/</code>）+ 官网 <code>web/website/</code> + 用户中心 <code>web/usercenter/</code>。主题：<b>light / dark 双主题</b>。治理落地见 <a href="frontend-ds-refactor-plan.html">实现计划</a>。
|
||||
</div>
|
||||
|
||||
<h2>① 一次 UI 改动的标准路径</h2>
|
||||
<div class="flow">加/改令牌 → 只改 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，不截图）</div>
|
||||
|
||||
<h2>② 目录地图</h2>
|
||||
<div class="box"><table>
|
||||
<tr><th>层</th><th>位置</th><th>角色</th></tr>
|
||||
<tr><td>原型单源（L1 真源）</td><td><code>design/prototype/</code></td><td>tokens.css · atoms.css · icons.js · index.html 登记页 · serve.mjs</td></tr>
|
||||
<tr><td>令牌 codegen</td><td><code>design/codegen/gen_flutter_tokens.mjs</code> · <code>web/*/scripts/build-tokens.mjs</code></td><td>tokens.css → Flutter .gen.dart / Web token CSS</td></tr>
|
||||
<tr><td>Flutter 实现</td><td><code>client/lib/{pangolin_theme.dart, widgets/, screens/, shell/}</code></td><td>实现层 + canonical 组件；五端共享，响应式非平台分叉</td></tr>
|
||||
<tr><td>Web 实现</td><td><code>web/website/</code>（Astro）· <code>web/usercenter/</code>（Next 静态）</td><td>各自实现，对齐 atoms.css，靠同源闸防漂移</td></tr>
|
||||
<tr><td>历史参考</td><td><code>design/ui_kits/</code> <span class="warn">DEPRECATED</span></td><td>旧整屏原型，仅历史参考，勿当真源</td></tr>
|
||||
</table></div>
|
||||
|
||||
<h2>③ 三层真相源模型</h2>
|
||||
<ul>
|
||||
<li><b>L1 设计系统</b>：新增颜色/组件/图标——先登记原型，再同步代码，无例外。</li>
|
||||
<li><b>L2 屏级三态</b>（台账 <code>design/CONTRACT.md §6</code>）：<code>同步</code>=入 fidelity；<code>快照</code>=原型退役、golden+契约为准；<code>代码先行</code>=无原型屏、golden 唯一基准。当前：Flutter 屏=快照，Web 屏=代码先行，原子层=同步。</li>
|
||||
<li><b>L3 新屏/改版</b>：design-first——原型 → serve 评审 → 契约 → 实现 → 验收 → 入同步态。</li>
|
||||
</ul>
|
||||
|
||||
<h2>④ 令牌 codegen（颜色单源落地）</h2>
|
||||
<p><code>design/prototype/tokens.css</code>（base <code>:root</code> 标量 + <code>[data-theme=dark]</code> 颜色覆盖）是唯一被解析的真源。<code>colors_and_type.css</code> 已降级为薄 <code>@import</code> 别名。Flutter 生成 <code>pangolin_tokens.gen.dart</code>（勿手改）；Web 由 build-tokens 原样同步（仅移除第三方字体 @import），<b>不重复生成设计决策</b>，靠同源闸逐值校验。</p>
|
||||
|
||||
<h2>⑤ 四道静态闸 —「违规谁拦」</h2>
|
||||
<div class="box"><table>
|
||||
<tr><th>闸</th><th>拦什么</th><th>何时</th><th>状态</th></tr>
|
||||
<tr><td>原型校验 <code>design/prototype/tools/check-ds.mjs</code></td><td>硬编码色（atoms.css）/未定义 token/字体/图标未走 sprite/原子未登记</td><td>pre-commit（动原型）+ CI</td><td class="ok">✓</td></tr>
|
||||
<tr><td>跨端同源 <code>tools/check-l1-sync.mjs</code></td><td>Web token 值≡原型 · 三端图标⊆原型 sprite · Web 硬编码色</td><td>pre-commit（动原型/web）+ CI</td><td class="ok">✓</td></tr>
|
||||
<tr><td>代码色单源 <code>client/tool/check_ds_code.mjs</code></td><td>Flutter 裸 <code>Color(0x)</code>/具名 <code>Colors.x</code>（<code>ds-ignore</code> 豁免）</td><td>pre-commit（--changed）+ CI（--strict）</td><td class="ok">✓</td></tr>
|
||||
<tr><td>codegen 零 diff <code>ci/check-codegen-drift.sh</code></td><td>重生成 token 后 git diff 非空即 fail</td><td>pre-commit + CI</td><td class="ok">✓</td></tr>
|
||||
</table></div>
|
||||
<p>CI（<code>.gitea/workflows/ci.yml</code>）的 <code>ds-flow</code> job 串起前三道；<code>codegen-drift</code> job 管第四道。pre-commit（<code>.githooks/pre-commit</code>，一次性 <code>bash ci/install-hooks.sh</code> 启用）跑条件化快子集。</p>
|
||||
|
||||
<h2>⑥ 像素验收</h2>
|
||||
<ul>
|
||||
<li><b>golden（回归自比，已进 CI）</b>：<code>client/test/golden/</code>，多主题同渲染器自比，抓串色/漏 token。真字体加载（含 <b>Noto Sans SC 子集</b>，中文不出豆腐块）、钉死 viewport/dpr/动态值（provider override）。基线在权威 Linux 容器生成：<code>bash scripts/update-goldens.sh</code>。当前 34 tests 全绿（components/auth/desktop/tablet × 双主题，tablet 含 zh/en）。</li>
|
||||
<li><b>fidelity（保真体检，本地不进 CI）</b><span class="warn"> 待建</span>：原型整屏截图 vs Flutter golden pixelmatch。<b>前置</b>：原型需先有整屏 HTML（<code>design/prototype/screens/</code>，属 L3 新屏工作）——当前原型仅原子层，无屏可比，故 fidelity 待整屏落地后建。</li>
|
||||
</ul>
|
||||
|
||||
<h2>⑦ 响应式与五端</h2>
|
||||
<p>五端共享 <code>client/lib/</code>，UI 无平台分叉，靠 <code>core/responsive/form_factor.dart</code>（<code>mobile/tablet/desktop</code> 按宽度+平台判定）。平台差异隔离在 bridge/update/tray 等系统集成层，非 UI。</p>
|
||||
|
||||
<h2>⑧ 规则速查（硬红线）</h2>
|
||||
<ul>
|
||||
<li>颜色只走语义 token；<code>colors_and_type.css</code> 勿加变量（改 <code>prototype/tokens.css</code>）。</li>
|
||||
<li>加原子/图标先登记原型再落代码；勿向 <code>design/</code> 提 Dart/TS 组件副本。</li>
|
||||
<li>文案脱敏：禁 VPN/翻墙/科学上网等红线词（<code>ci/scan-redline.sh</code> 守护）。</li>
|
||||
<li>硬编码色例外（<code>#fff/#000</code>/品牌 logo 色）加 <code>// ds-ignore: 理由</code> 或列白名单。</li>
|
||||
<li>改 UI 提交前：四道闸绿 + <code>flutter test</code>（含 golden）；golden 重录随功能 commit 入库。</li>
|
||||
</ul>
|
||||
|
||||
<h2>⑨ 文档索引</h2>
|
||||
<ul>
|
||||
<li><a href="frontend-ds-refactor-plan.html">前端设计系统治理重构 · 实现计划</a>（真相源 <code>docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md</code>）</li>
|
||||
<li>根 <code>CLAUDE.md</code>「## 前端设计系统治理（ds-flow）」· <code>design/CLAUDE.md</code>（设计铁律 + 真源对照）· <code>design/CONTRACT.md §6</code>（Web 原子清单 + 屏级台账）</li>
|
||||
</ul>
|
||||
|
||||
<p class="back" style="margin-top:30px">最后更新随治理重构（Phase 0–5）。fidelity（⑥）与 mobile golden 扩容为后续项。</p>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -128,6 +128,11 @@
|
||||
</a>
|
||||
|
||||
<h2>知识库 / 调研</h2>
|
||||
<a class="doc" href="frontend-overview.html">
|
||||
<div class="t">前端全景（ds-flow 设计系统治理）<span class="tag html">HTML</span></div>
|
||||
<div class="d">Flutter 五端 + 官网 + 用户中心的设计系统治理全景：一次 UI 改动标准路径、目录地图、三层真相源模型、令牌 codegen、四道静态闸「违规谁拦」、像素验收（golden 双主题 + fidelity 待建）、响应式五端、规则速查。原型单源 design/prototype/（tokens/atoms/icons/index.html）、check-ds/check-l1-sync/check_ds_code/codegen-drift 四闸进 CI、golden 全量 34 绿含 CJK。</div>
|
||||
<div class="path">docs/frontend-overview.html</div>
|
||||
</a>
|
||||
<a class="doc" href="code-review-2026-07.html">
|
||||
<div class="t">全栈设计审查 2026-07（前端/后端/数据库）<span class="tag html">HTML</span></div>
|
||||
<div class="d">核心链路精读式审查，13 项发现分 P0/P1/P2：明文 HTTP、SQLite 零备份（P0）；同机换账号 403 死结、disconnect 撤错凭证、用量取走即焚、Redis 重启全员掉线、argon2id OOM（P1）；留存/UTC 日界/三时钟口径等（P2）。附「做得好的」与处理顺序建议。</div>
|
||||
|
||||
@@ -92,7 +92,7 @@ Flutter 已很干净（UI 层零裸 hex），只需收尾。
|
||||
- [x] 4.2 测试字体补 CJK 子集：用 `tools/fonts/make-cjk-subset.sh` 生成 Noto Sans SC 子集放
|
||||
`client/test/fonts/`，`flutter_test_config.dart` 注册——消除 golden 中文与生产渲染差异
|
||||
- [x] 4.3 处理现存 6 张 `client/test/golden/failures/` diff：逐张确认「原型对得上」后 `--update-goldens` 重录入库
|
||||
- [ ] 4.4 golden 覆盖扩容：desktop/tablet/mobile 全屏 × light/dark 双主题矩阵
|
||||
- [ ] 4.4 (延后·非阻塞) golden 覆盖扩容：desktop/tablet/mobile 全屏 × light/dark 双主题矩阵
|
||||
（现有 `desktop_pages/tablet_pages/components/auth` → 补 mobile + 主题维度）
|
||||
- [x] 4.5 `client/test/helpers/harness.dart` 对齐 jiu `golden_harness.dart` 手法：
|
||||
多主题循环辅助 + 钉死 viewport/dpr + ProviderScope 固定数据（防动态值翻车）
|
||||
@@ -109,9 +109,9 @@ Flutter 已很干净（UI 层零裸 hex），只需收尾。
|
||||
原型校验 → 跨端同源 → 代码色单源 → codegen 零 diff（已有）→ 测试含 golden（已有，补 mobile+主题）
|
||||
- [x] 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`
|
||||
- [ ] 5.5 (延后·前置=原型整屏 screens/,属 L3) fidelity 像素闸（本地体检，不进 CI）：`tools/screens.mjs` 屏注册表 + `tools/fidelity.mjs`
|
||||
（原型 Chromium 截图 vs Flutter golden pixelmatch，逐屏阈值=实测残差+2pp，两边统一注入 CJK 字体）
|
||||
- [ ] 5.6 全景文档 `docs/frontend-overview.html`（照搬 jiu 十节）：一次 UI 改动标准路径 + 目录地图 +
|
||||
- [x] 5.6 全景文档 `docs/frontend-overview.html`（照搬 jiu 十节）：一次 UI 改动标准路径 + 目录地图 +
|
||||
三层分治 + 闸全景 + 像素验收体系 + 响应式范式 + 规则速查，登记进 docs/index.html
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user