Web Design System Pipeline

从 Pencil 设计规范到租户可定制主题的完整管线 · 更新于 2026-02-08

1. 背景：为什么需要这条管线

Web 端存在三个问题：

1. 没有设计规范文件 — 28 个 UI 组件没有视觉规范，一致性靠开发者记忆
2. Token 体系混乱 — 两套 CSS 变量系统并存（design-tokens.css + globals.css），组件同时还硬编码 Tailwind 颜色类
3. 租户主题色无法生效 — 硬编码的 bg-blue-600 不会跟着主题变量走

这条管线的目标：让租户 Super Admin 改一个颜色值，全站所有组件自动跟着变，零代码改动。

2. 完整管线架构

3. 核心原理：CSS 变量级联覆盖

整条管线能工作的基石是 CSS Custom Properties 的级联（Cascade）特性：

/* Step 1: globals.css 定义默认值 */
:root {
  --primary: oklch(0.205 0 0);        /* 默认深色 */
}

/* Step 2: @theme inline 把 CSS 变量桥接为 Tailwind 类 */
@theme inline {
  --color-primary: var(--primary);     /* bg-primary 现在能用了 */
}

/* Step 3: 组件使用语义化类 */
<Button className="bg-primary" />     /* 编译时不知道具体颜色 */

/* Step 4: 运行时，租户主题色覆盖 :root 变量 */
:root {
  --primary: oklch(0.65 0.18 55);     /* 租户的金色 */
}
/* 所有 bg-primary 的元素自动变成金色，无需重新编译 */

4. 两层 Token 设计（非三层）

Flutter 端用了 Material 的三层 Token（Reference → System → Component）。Web 端只用两层：

为什么不要第三层（Component Token）？

Component Token（如 --button-bg: var(--primary)）在 Web 端不值得：

• Tailwind 的组件样式在 JSX 中用 className 定义（bg-primary text-primary-foreground），不在 CSS 中
• 你不会单独改按钮的主色而不改其他地方的主色
• 额外一层间接引用增加了调试复杂度但没有实际收益

5. 为什么用 oklch 色彩空间

globals.css 用 oklch 而非 hex，有两个关键原因：

5.1 感知均匀（Perceptual Uniformity）

/* oklch: 改亮度 0.5 → 0.7，人眼感知均匀变亮 */
--primary: oklch(0.5 0.15 250);  /* 深蓝 */
--primary: oklch(0.7 0.15 250);  /* 亮蓝 — 感知上刚好亮了"一档" */

/* hex: 加亮 10%，视觉变化不可预测 */
--primary: #1a5276;  /* 深蓝 */
--primary: #2e86c1;  /* 亮蓝 — 感知上可能变了 30%，也可能只变了 5% */

这对租户自定义主题色至关重要 — 系统需要根据主色自动生成 hover 态、disabled 态、前景色（文字色），oklch 让这些计算可预测。

5.2 Tailwind 的透明度语法

/* bg-primary/90 需要色彩空间支持 alpha 分解 */
<button className="bg-primary/90 hover:bg-primary">
/* oklch 原生支持: oklch(0.205 0 0 / 0.9) */
/* hex 需要额外转换: #000000 → rgba(0,0,0,0.9) — Tailwind 处理不了 */

6. 历史遗留：两套 Token 系统并存

决策：以 globals.css 的 shadcn/ui 变量体系为正式标准。design-tokens.css 标记为 legacy，不再新增变量。

原因：shadcn/ui 体系已经和 Tailwind 深度整合（通过 @theme inline），组件可以直接用 bg-primary 这样的语义化类，开发体验最好。

7. Pencil 在管线中的角色

8. Storybook 的定位

Storybook 保留并升级，增加 Theme Switcher decorator：在 Storybook 中实时切换不同租户主题预览。

9. 组件清单与优先级

现有 Storybook 组件（28 个）

业务组件（已有 Storybook Stories）

10. 实施阶段

Phase 1 统一 Token 层 ✅

目标：让 globals.css 的 :root 变量成为唯一 Token 来源

• 扩展 globals.css 中的 :root — 补充 --success、--warning、--info 等语义色
• 扩展 @theme inline — 映射所有新增 Token 到 Tailwind 类
• 标记 design-tokens.css 为 legacy

影响范围：仅 CSS 文件

Phase 2 组件 Token 消费改造 ✅

目标：消除组件中的硬编码颜色

<button className="bg-blue-600
  hover:bg-blue-700 text-white">

<button className="bg-primary
  hover:bg-primary/90
  text-primary-foreground">

影响范围：28 个 UI 组件文件，按 P0 → P1 → P2 分批

Phase 3 建立 Pencil Web 设计系统 ✅

目标：创建 designs/web-design-system.pen

• ✅ 定义 35 个 Token 变量（对齐 globals.css oklch 值）
• ✅ 构建 36 个可复用组件（13 个分类框架）
• ✅ 组件类别：Buttons(5), Inputs(4), Badges(4), Alerts(4), Cards(1), Controls(4), Tabs(1), Avatars(3), Separators(2), Dialogs(1), Tables(1), Selects(2), Toasts(4)

Phase 4 Storybook 升级 ✅ 已完成

目标：Storybook 成为可交互的主题预览工具

• ✅ 安装 Storybook 8.6.15 + @storybook/nextjs framework adapter
• ✅ 创建 .storybook/main.ts — stories 路径、framework、addons 配置
• ✅ 创建 .storybook/preview.tsx — Theme Switcher decorator + next-intl provider
• ✅ 三个主题预设：Light (默认)、Dark (oklch 反转)、Brand (teal accent 示例)
• ✅ Locale 切换器：en / zh，实时切换 Storybook 组件语言
• ✅ npm scripts: npm run storybook (端口 6006)、npm run storybook:build

Theme Switcher 工作原理

利用 CSS Custom Properties 级联特性，在 decorator 的包裹 <div> 上通过 style 属性覆盖 :root 变量。 Light 模式不做覆盖（使用 globals.css 默认值），Dark/Brand 模式设置对应的 oklch 色值。零 JS 运行时成本。

11. 优点总结

12. 与 Flutter 端的关系

两端共享的只有 Pencil MCP 工具链（同一套 Pencil 操作 API），以及 "设计规范 → 手动对齐 → 代码实现 → 活文档验证" 的工作流模式。具体的 Token 值、色盘、组件实现完全独立。