diff --git a/design/SKILL.md b/design/SKILL.md index f39fc1f..994bd5a 100644 --- a/design/SKILL.md +++ b/design/SKILL.md @@ -13,3 +13,11 @@ If creating visual artifacts (slides, mocks, throwaway prototypes, etc), copy as If the user invokes this skill without any other guidance, ask them what they want to build or design, ask some questions, and act as an expert designer who outputs HTML artifacts _or_ production code, depending on the need. Hard rules: 一屏一个蓝色主按钮；无渐变；无 emoji；浮层永远深色玻璃；文案短、用"你"、无句号。 + +## 单源与闸（改 UI 前必读） + +- **登记先行（L1 无例外）**：新颜色/字号/间距 → `tokens/*.css`；新组件 → `components/` + 登记簿 `index.html` 加卡；新图标 → `icons.js` + `icon-map.json`。登记后跑 `node design-pipeline/export-tokens.mjs` 再写端代码。 +- **业务代码禁止**：字面色（hex/rgb/hsl，一律 var(--*) / DuduTheme）、内联 ``（走 `Icon` 组件）、未登记的 SF Symbol。确属例外加行内 `ds-ignore: 理由`。 +- **闸**：`node design-pipeline/check-ds.mjs`（真相源自检 7 道）· `check-code.mjs`（四端代码侧）· `export-tokens.mjs --check`（产物零 diff）。pre-commit（`git config core.hooksPath .githooks` 启用）与 CI 双挂。 +- **预览评审**：`node design/serve.mjs` → http://localhost:5180（登记簿 index.html 与 ui_kits）。 +- 全景说明：`doc/frontend-overview.html`。 diff --git a/doc/frontend-overview.html b/doc/frontend-overview.html new file mode 100644 index 0000000..e56f4d6 --- /dev/null +++ b/doc/frontend-overview.html @@ -0,0 +1,168 @@ + + + + + +dudu 前端全景：设计真相源与防漂移体系 + + + + +
+

dudu 前端全景

+

设计真相源（design/）· 五端消费 · 防漂移闸体系 —— 参考 jiu ds-flow 思想的非 Flutter 落地

+
+ 2026-07-11 + 登记簿：design/index.html + 闸：design-pipeline/check-ds · check-code · export-tokens --check +
+
+ +
+ +
+

一、一次 UI 改动的标准路径

+ 
改颜色/字号/间距   design/tokens/*.css 登记
+                     │
+                     ▼
+        node design-pipeline/export-tokens.mjs
+                     │（直写四端消费位置）
+   ┌──────────┬──────┴──────┬──────────────┐
+   ▼          ▼             ▼              ▼
+desktop    iOS Swift    Android Kotlin   官网 web/
+CSS 变量   DuduTheme    DuduTheme        tokens.css
+（直引源） （生成）      （生成）          （生成，含字体内嵌）
+
+改组件 / 图标      先在 design/ 登记（components/ + index.html 卡；
+                   icons.js + icon-map.json）→ 再到各端实现
+提交               pre-commit 自动跑对应闸；CI 三道闸复验
+
核心原则（ds-flow）：设计决策只有一个出生地（design/），代码永远是镜像；绕过单源的行为由闸在提交/CI 时拦截。规则写了没上闸 = 没有规则。
+
+ +
+

二、真相源结构（design/）

+ + + + + + + + + + +
路径角色
index.html登记簿（活文档主页）：token 色板 / 组件卡 / 图标映射 / guidelines / ui_kits 单一入口。新元素必须在此登记（check-ds ④ 强制）。评审：node design/serve.mjs
tokens/*.css令牌单源：colors（含 --brand-wechat / --overlay-wave）/ typography / spacing / effects / fonts（Outfit 自托管，禁 CDN）
icons.js + icon-map.json图标单源（Lucide 线条 24 网格）+ 语义名→三端实现映射表；业务代码禁内联 <path>
components/（core/forms/voice）参考组件（React），桌面端直接运行时消费；Icon.jsx 渲染 icons.js
ui_kits/（desktop/mobile）屏级交互原型（新屏 design-first 的出生地）
guidelines/*.card.html规范卡（品牌/色板/字体/间距/动效）
readme.md / SKILL.md设计基调、文案基调、视觉硬规则；agent 使用入口
_ds_manifest.jsonClaude 设计导出的机读清单——非权威、可能滞后，真相以 tokens/ 与登记簿为准
+
+ +
+

三、五端消费方式对照

+ + + + + + + +
端技术栈令牌组件/图标
桌面 Mac/WinTauri 2 + Reactvite alias @dudu/design 直引 tokens CSS（无生成层）直接 import design/components；Icon 组件渲染 icons.js
iOSSwiftUIios/dudu/Shared/DuduTheme.swift（codegen 直写）SF Symbols，须 ∈ icon-map ios 列（check-code 同集闸）
AndroidComposeDuduTheme.kt（codegen 直写）→ DuduPalette CompositionLocal暂无图标使用；启用后同集闸生效
官网静态单页web/tokens.css（codegen：custom props + Outfit data URI）页面只允许 var(--*)；深色板块挂 data-theme="dark" 复用 dark 令牌
原型自身React（浏览器内 Babel）styles.css @import tokens与桌面同一套组件源码
+
codegen 直写消费位置（2026-07-11 改）：此前生成到 design-pipeline/generated/ 再手工拷贝进 app，--check 守不到真实文件、拷贝已漂移。现直写 + CI 校验真实消费文件，漂移类型整个消除。
+
+ +
+

四、各道闸全景

+ + + + + +
闸拦什么何时跑
check-ds.mjs
真相源自检（7 道）		① dark 孤儿 token ② var() 断链/@import 缺失 ③ design/ 内裸色 ∉ tokens 值集 ④ 组件未登记登记簿 ⑤ icons.js 重复 key/填充色 ⑥ icon-map ↔ icons.js 双向不同集 ⑦ 界面文案 emojipre-commit（动 design/）+ CI
export-tokens.mjs --check四端令牌产物与源不一致（改了 tokens 忘 regen / 手改生成文件）pre-commit（动 design/）+ CI
check-code.mjs
代码侧单源（四端）		desktop 字面色/内联 <path>；iOS 字面色/未登记 SF Symbol；Android Color(0x；web 字面色pre-commit（动端代码）+ CI
+

豁免机制

+
    +
  • 行级 ds-ignore: 理由 注释——必须写理由（mac 红绿灯窗饰、手机外壳装饰、alpha 派生色等）
    • +
  • codegen 产物（DuduTheme.*、web/tokens.css）自动豁免
    • +
+

启用

+ 
# 一次性（每个 clone）
+git config core.hooksPath .githooks
+
+# 手动全量
+node design-pipeline/check-ds.mjs && node design-pipeline/export-tokens.mjs --check && node design-pipeline/check-code.mjs
+
+ +
+

五、三层分治规则（L1 / L2 / L3）

+ + + + + +
层规则
L1 设计系统元素
颜色/字号/间距/组件/图标		先登记 design/（tokens / components+登记簿 / icons+map）再写端代码，无例外。闸强制。
L2 屏级屏以 ui_kits 原型为基准；小迭代直改代码但不得引入 L1 违规（闸兜底）；整屏改版原型先行。
L3 新屏design-first：ui_kits 加屏（serve.mjs 起服务给 URL 评审，不截图）→ 各端实现 → 登记。
+
+ +
+

六、已知滞后与后续项

+
    +
  • todo #26桌面 fidelity 像素闸（Playwright 截 ui_kits 原型 vs Tauri 页面 pixelmatch）——静态闸先行，像素级验收后续补
    • +
  • 待治理ui_kits 预览页经 unpkg CDN 加载 React/Babel，离线/无代理网络不可用（评审时需网络；可选改为 vendor 本地化）
    • +
  • 说明_ds_manifest.json 为 Claude 设计导出产物，未纳入闸；以 tokens/ 与登记簿为权威
    • +
  • 说明移动端不做跨渲染器像素比对（字体度量漂移大，jiu 教训）；iOS/Android 一致性由 token codegen + 同集闸保障
    • +
+
+ +
dudu · 前端全景 · 2026-07-11 · 变更走 feat/design-truth-source
+ +
+ + diff --git a/doc/index.html b/doc/index.html index b0d142b..ca283aa 100644 --- a/doc/index.html +++ b/doc/index.html @@ -53,6 +53,7 @@