From 3311430db6e471bb35f24685de3052a48fee2436 Mon Sep 17 00:00:00 2001 From: wangjia <809946525@qq.com> Date: Tue, 7 Jul 2026 23:56:15 +0800 Subject: [PATCH] =?UTF-8?q?docs(ds-flow):=20Phase=200=20=E2=80=94=20CLAUDE?= =?UTF-8?q?.md=20=E5=A2=9E=E5=89=8D=E7=AB=AF=E8=AE=BE=E8=AE=A1=E7=B3=BB?= =?UTF-8?q?=E7=BB=9F=E6=B2=BB=E7=90=86=E7=AB=A0=E8=8A=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增「## 前端设计系统治理（ds-flow）」:心智模型(原型单源·代码镜像·静态闸 拦漂移·golden/fidelity 双级验收)、原型三件套(design/prototype/ tokens/atoms/ icons/index.html)、L1/L2/L3 三层治理、codegen(Flutter 生成 + Web 同源不重复 生成)、四道静态闸「违规谁拦」对照表、双级像素验收、pre-commit 启用说明。 ⏳ 标注部件为 Phase 1-5 建设中,诚实反映当前落地状态,指向计划 #19。 Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 44 +++++++++++++++++++ .../plans/2026-07-07-frontend-ds-refactor.md | 6 +-- 2 files changed, 47 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8348e5c..bddda7f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -90,6 +90,50 @@ cd web/website && npm run gen:tokens - `design/flutter/` 已删除；Flutter 组件 canonical 实现在 `client/lib/widgets/`，规格在 `design/preview/`。 - **禁止**再向 `design/` 提交 Dart/TS 组件代码副本（会漂移）。 +## 前端设计系统治理（ds-flow） + +> **落地中**（分阶段收口，见计划 `docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md` +> / 阅读版 `docs/frontend-ds-refactor-plan.html` / todo #19）。以下是**目标模型与硬规则**； +> 标注「⏳」的部件正在建，未标注的已生效。参考样板 `~/code/jiu`。 + +**心智模型**：设计只有一个出生地（**原型单源**），代码永远是镜像；跨端副本是否走样由 +**静态闸**在提交/CI 前拦截，像素是否还原由 **golden/fidelity 双级验收**兜底。主题：**light / dark 双主题**。 + +**原型单源** `design/prototype/`（⏳ 建设中，Phase 1）： +- `tokens.css` — 令牌真源：基础 `:root`（主题无关标量：间距/圆角/字号/字体/阴影/动效）+ `[data-theme=dark]` 颜色覆盖块。 + （当前真源仍是 `design/colors_and_type.css`，Phase 1 迁移后数值不变、结构规整） +- `atoms.css` — 公用组件原子（按钮/卡片/输入/语言下拉/徽章/状态药丸），**只引 `var(--token)`，禁硬编码**。 +- `icons.js` — SVG sprite 单源（``）；website/usercenter/Flutter 三处图标集须 ⊆ 此集。 +- `index.html` — 活登记页：主题切换 + 声明式色板 + 全组件/图标展示卡。**每个 atom 必须在此登记**。 +- `serve.mjs` — 零依赖热重载预览；评审给 URL，**不截图**。 + +**三层治理**： +- **L1 设计系统**：新增颜色/组件/图标——**先登记原型，再同步代码**，无例外。跨端映射（状态词→图标）两端同集要有闸。 +- **L2 屏级三态**（台账记 `design/CONTRACT.md`）：`同步`=入 fidelity；`快照`=原型退役、golden+契约为准；`代码先行`=无原型屏、golden 唯一基准。 +- **L3 新屏/改版**：design-first——原型 → serve 评审 → 契约 → 实现 → 验收 → 入同步态。 + +**codegen**： +- Flutter：`node design/codegen/gen_flutter_tokens.mjs` → `pangolin_tokens.gen.dart`（**勿手改**）。 +- Web：`build-tokens.mjs`（website→`src/styles/tokens.gen.css` / usercenter→`public/colors_and_type.css`）， + **只同源不重复生成设计决策**；靠同源闸逐值校验（不建跨端共享组件包，两端各自实现）。 + +**四道静态闸 —「违规谁拦」**（规则没上闸 = 没有规则）： + +| 闸 | 拦什么 | 何时 | +|---|---|---| +| 原型校验 `check-ds.mjs`（⏳ Phase 5） | 硬编码色/未定义 token/未登记组件/魔法数断点… 12 道 | pre-commit（动了原型）+ CI | +| 跨端同源 `check-l1-sync.mjs`（⏳ Phase 2） | tokens 逐值/icons 同集/Web hex 白名单 | CI | +| 代码色单源 `check_ds_code.mjs`（⏳ Phase 5） | Flutter 裸 `Color(0x)`/具名 `Colors.x`（`// ds-ignore: 理由` 豁免） | pre-commit（`--changed`）+ CI | +| codegen 零 diff `ci/check-codegen-drift.sh`（**已生效**） | 重生成 token 后 `git diff` 非空即 fail | pre-commit + CI | + +**双级像素验收**： +- **golden**（**已有**，`client/test/golden/`）：多主题回归自比（同渲染器），抓串色/漏 token；真字体加载防豆腐块、钉死 viewport/dpr/动态值。重录 `flutter test --update-goldens`，随功能 commit 入库。 +- **fidelity**（⏳ Phase 5，本地体检**不进 CI**）：原型 Chromium 截图 vs Flutter golden pixelmatch，逐屏阈值=实测残差+2pp；跨渲染器噪声大，故不入 CI。 + +**pre-commit**：`.githooks/pre-commit` 已写，**每台机需 `bash ci/install-hooks.sh` 启用一次**（设 `core.hooksPath=.githooks`）。 + +**发现硬编码色**：换 token；确属例外（`#fff/#000`/品牌 logo 固定色）加 `// ds-ignore: 理由` 或列白名单。 + ## client/ macOS 原生隧道(PacketTunnel 系统扩展 + 内嵌 libbox) 内嵌 sing-box(`Libbox.xcframework`)的 `NEPacketTunnelProvider` **系统扩展**(站外 Developer ID 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 436ee26..f1fd010 100644 --- a/docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md +++ b/docs/superpowers/plans/2026-07-07-frontend-ds-refactor.md @@ -21,14 +21,14 @@ ## Phase 0 — 更新 CLAUDE.md + 计划落库 -- [ ] 0.1 CLAUDE.md 新增「## 前端设计系统治理（ds-flow）」章节： +- [x] 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 + 收尾） +- [x] 0.2 本 `.md` 定稿 + 生成 HTML 阅读版 `docs/frontend-ds-refactor-plan.html`，登记进 `docs/index.html`「实现计划」 +- [x] 0.3 `/todo` 建 tier-1 条目跟踪本重构，拆 6 个子任务（对应 Phase 1-5 + 收尾） ---