diff --git a/docs/frontend-overview.html b/docs/frontend-overview.html new file mode 100644 index 0000000..252c6b4 --- /dev/null +++ b/docs/frontend-overview.html @@ -0,0 +1,108 @@ + + + + + +Pangolin 前端全景（ds-flow 设计系统治理） + + + +
+

← 文档索引

+

Pangolin 前端全景 ds-flow

+

设计只有一个出生地（原型单源），代码永远是镜像；漂移由静态闸拦在提交/CI 前，还原由 golden 双主题验收兜底。

+ +
+Flutter 五端（macOS/iOS/iPad/Android/Windows，共享 client/lib/）+ 官网 web/website/ + 用户中心 web/usercenter/。主题：light / dark 双主题。治理落地见 实现计划。 +
+ +

① 一次 UI 改动的标准路径

+
加/改令牌 → 只改 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，不截图）
+ +

② 目录地图

+
+ + + + + + +
层位置角色
原型单源（L1 真源）design/prototype/tokens.css · atoms.css · icons.js · index.html 登记页 · serve.mjs
令牌 codegendesign/codegen/gen_flutter_tokens.mjs · web/*/scripts/build-tokens.mjstokens.css → Flutter .gen.dart / Web token CSS
Flutter 实现client/lib/{pangolin_theme.dart, widgets/, screens/, shell/}实现层 + canonical 组件；五端共享，响应式非平台分叉
Web 实现web/website/（Astro）· web/usercenter/（Next 静态）各自实现，对齐 atoms.css，靠同源闸防漂移
历史参考design/ui_kits/ DEPRECATED旧整屏原型，仅历史参考，勿当真源
+ +

③ 三层真相源模型

+ + +

④ 令牌 codegen（颜色单源落地）

+

design/prototype/tokens.css（base :root 标量 + [data-theme=dark] 颜色覆盖）是唯一被解析的真源。colors_and_type.css 已降级为薄 @import 别名。Flutter 生成 pangolin_tokens.gen.dart（勿手改）；Web 由 build-tokens 原样同步（仅移除第三方字体 @import），不重复生成设计决策，靠同源闸逐值校验。

+ +

⑤ 四道静态闸 —「违规谁拦」

+
+ + + + + +
闸拦什么何时状态
原型校验 design/prototype/tools/check-ds.mjs硬编码色（atoms.css）/未定义 token/字体/图标未走 sprite/原子未登记pre-commit（动原型）+ CI✓
跨端同源 tools/check-l1-sync.mjsWeb token 值≡原型 · 三端图标⊆原型 sprite · Web 硬编码色pre-commit（动原型/web）+ CI✓
代码色单源 client/tool/check_ds_code.mjsFlutter 裸 Color(0x)/具名 Colors.x（ds-ignore 豁免）pre-commit（--changed）+ CI（--strict）✓
codegen 零 diff ci/check-codegen-drift.sh重生成 token 后 git diff 非空即 failpre-commit + CI✓
+

CI（.gitea/workflows/ci.yml）的 ds-flow job 串起前三道；codegen-drift job 管第四道。pre-commit（.githooks/pre-commit，一次性 bash ci/install-hooks.sh 启用）跑条件化快子集。

+ +

⑥ 像素验收

+ + +

⑦ 响应式与五端

+

五端共享 client/lib/，UI 无平台分叉，靠 core/responsive/form_factor.dart（mobile/tablet/desktop 按宽度+平台判定）。平台差异隔离在 bridge/update/tray 等系统集成层，非 UI。

+ +

⑧ 规则速查（硬红线）

+ + +

⑨ 文档索引

+ + +

最后更新随治理重构（Phase 0–5）。fidelity（⑥）与 mobile golden 扩容为后续项。

+
+ + diff --git a/docs/index.html b/docs/index.html index 2c8a8fb..2131854 100644 --- a/docs/index.html +++ b/docs/index.html @@ -128,6 +128,11 @@

知识库 / 调研

+ +
前端全景（ds-flow 设计系统治理）HTML
+
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。
+
docs/frontend-overview.html
+
全栈设计审查 2026-07（前端/后端/数据库）HTML
核心链路精读式审查，13 项发现分 P0/P1/P2：明文 HTTP、SQLite 零备份（P0）；同机换账号 403 死结、disconnect 撤错凭证、用量取走即焚、Redis 重启全员掉线、argon2id OOM（P1）；留存/UTC 日界/三时钟口径等（P2）。附「做得好的」与处理顺序建议。
diff --git a/docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md b/docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md index f839ba2..b7834e4 100644 --- a/docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md +++ b/docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md @@ -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 ---