@@ -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 : 15 px }
. wrap { max-width : 960 px ; margin : 0 auto ; padding : 44 px 24 px 96 px }
h1 { font-size : 28 px ; margin : 0 0 6 px ; letter-spacing : -.01 em }
. sub { color : var ( - - fg2 ) ; margin : 0 0 26 px }
h2 { font-size : 19 px ; margin : 36 px 0 12 px ; padding-bottom : 8 px ; border-bottom : 1 px solid var ( - - border ) }
h3 { font-size : 15.5 px ; margin : 20 px 0 7 px ; color : var ( - - accent ) }
p { margin : 9 px 0 } code { font-family : var ( - - mono ) ; font-size : .85 em ; background : var ( - - panel2 ) ; padding : 1 px 6 px ; border-radius : 5 px ; color : #f0d9c4 }
a { color : var ( - - accent2 ) ; text-decoration : none } a : hover { text-decoration : underline }
. lead { background : linear-gradient ( 180 deg , rgba ( 224 , 136 , 79 , .10 ) , transparent ) ; border : 1 px solid var ( - - border ) ; border-radius : 12 px ; padding : 16 px 20 px ; margin : 0 0 22 px }
ul { margin : 8 px 0 ; padding-left : 22 px } li { margin : 5 px 0 }
. box { overflow-x : auto ; margin : 12 px 0 }
table { border-collapse : collapse ; width : 100 % ; font-size : 13.5 px ; min-width : 600 px }
th , td { border : 1 px solid var ( - - border ) ; padding : 7 px 10 px ; 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 : 1 px solid var ( - - border ) ; border-radius : 10 px ; padding : 14 px 18 px ; font-family : var ( - - mono ) ; font-size : 13 px ; white-space : pre ; overflow-x : auto ; color : var ( - - fg2 ) }
. back { color : var ( - - fg2 ) ; font-size : 13 px }
. pill { display : inline-block ; font-size : 11 px ; font-weight : 700 ; padding : 1 px 8 px ; border-radius : 999 px ; background : rgba ( 94 , 194 , 122 , .14 ) ; color : var ( - - ok ) ; margin-left : 6 px }
< / 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（ ）
加/改原子 → 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（ ）
评审原型 → 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 > （ < code > web/usercenter/< / code > （ < / 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 > ： < / li >
< / ul >
< h2 > ④ 令牌 codegen（颜色单源落地）< / h2 >
< p > < code > design/prototype/tokens.css< / code > （ < 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） < / 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） < / 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（ ） （ ） < / 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 × < / 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 > ， < 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 > （ < / li >
< / ul >
< p class = "back" style = "margin-top:30px" > 最后更新随治理重构（Phase 0– < / p >
< / div >
< / body >
< / html >