手帐 Blog

主题

15 · 设计系统与组件库工程 ​

目标：理解 Token、主题、文档站、共享包版本；能把「UI 规范」落成可复用工程，而不是一堆散样式。

1. 背景与目标 ​

Journal 已有 docs/ui/ 与 SCSS 变量——这是设计系统的雏形。进阶是：变量 → 组件 → 文档 →（可选）发包，让多应用共用同一语言。

2. 核心概念 ​

text
Design Token（色/间距/圆角/字号）
    → 主题（亮色/暗色或品牌变体）
    → 基础组件（Button/Input/Modal…）
    → 业务组件
    → 文档站（用法即契约）
层做什么
Token禁止魔法数字；改一处全局跟
组件 API变体用 props，不复制三份 CSS
文档站Storybook / Histoire / VitePress 展示状态
版本semver；breaking 升 major

Monorepo 里常见：packages/ui 被 apps/web、apps/admin 引用（对照 Journal 的 client/admin 也可抽共享，未必立刻做）。

3. 最小实践 ​

  1. 列 8～12 个 token：--color-text、--space-4、--radius-md…
  2. 用 token 重写 1 个按钮的 3 种状态
  3. 用文档页写清：primary / ghost、禁用、加载
  4. （可选）packages/ui + pnpm workspace 导出
scss
// token 示意
:root {
  --color-text: #1a1a1a;
  --color-bg: #fff;
  --space-3: 12px;
  --radius-md: 8px;
}

4. 踩坑与取舍 ​

  1. 一上来建完整 Design System：过度设计；先 token + 高频组件。
  2. 文档与实现脱节：文档站要跟 CI 或至少跟发版。
  3. 主题用「整份 CSS 复制」：用 token 覆盖，不要 fork 组件。
  4. 业务组件塞进基础库：边界糊掉，包会膨胀。

5. 验收清单 ​

  • [ ] 写出一小组 token 并接到真实组件
  • [ ] 至少一个组件有文档化变体说明
  • [ ] 能口述组件库版本与 breaking 策略
  • [ ] （可选）workspace 里抽出 packages/ui 被两处引用

6. 下一步 ​

→ 16 · 无障碍 a11y 与语义化

参考链接 ​