Design System Builder
一个设计系统是一组一次性做出的决定，这样每个屏幕就不必重新做决定。令牌承载决定，组件应用它们，文档解释它们。根据项目规模调整工作量：一个周末应用只需要一个 40 行的令牌文件和一个 DESIGN.md；一个多团队产品则需要管道和治理。从小处着手，通过提取不断成长。
流程
0. 阅读现有内容
查找：tokens/theme 文件、tailwind 配置或 @theme 块、components.json、CSS 变量、theme/ 模块、Figma 链接（如果已连接 Figma MCP，则使用 get_variable_defs/search_design_system）、DESIGN.md/.interface-design/system.md。在现有代码库中，先提取再创造：grep 实际使用的颜色、字号、间距和圆角，进行聚类，并提出合并后的规模。向用户展示改动前后的映射关系。
1. 定义方向（一段）
谁使用它，它应该给人什么感觉（用具体词语描述：“像交易终端一样密集”、“像阅读应用一样安静”）、平台、品牌约束、密度、浅色/深色模式。这将驱动下面的每一个比例选择。如果 interface-design 或 frontend-design 技能已启用，它们拥有这个美学步骤；本技能将方向转化为一个系统。
2. 基础（令牌）
按以下顺序构建——每个都依赖于前一个：
- 颜色 → 运行
color-theory技能的工具：python3 <skills-dir>/color-theory/scripts/palette.py system <brand-hex> --format tailwind|css|json（color-theory是本技能目录的兄弟目录）。它会生成原始色阶和经过验证的浅色/深色语义角色。 - 排版 → 字体族（≤2，外加等宽字体）、带有命名角色的字号比例、行高、字重、字间距。参见
references/scales.md。 - 间距 → 4px 基础网格；T 恤尺码或数字比例；布局间距与组件内边距分开。
- 形状 → 圆角比例（以及嵌套规则：内圆角 = 外圆角 − 内边距）、边框宽度。
- 层级 → 阴影比例（浅色）和表面亮度步进（深色）、z-index 层。
- 动效 → 持续时间和缓动函数作为令牌（以及减少动效行为）。
- 布局 → 断点、容器宽度、网格列数、安全区域（移动端）。
- 尺寸 → 控件高度（sm/md/lg）、图标尺寸、最小触摸目标。
3. 令牌架构
三个层级——组件必须只使用语义层（或组件层）的令牌：
原始层 --blue-600, --space-4, --radius-2 原始值，按“是什么”命名
语义层 --color-accent, --space-inset-md, --radius-control 按“做什么”命名，别名指向原始令牌，每个主题切换
组件层 --button-bg, --card-padding 可选；仅用于有真正主题需求的组件
主题切换（暗色模式、品牌、密度、高对比度）= 重新指向语义令牌。组件从不改变。完整的命名规则、DTCG 格式、模式：references/token-architecture.md。
4. 输出到平台
- 单一 Web 应用：手写 CSS 变量 + Tailwind v4
@theme就足够了。 - Web + 移动端，或多个应用：以 DTCG JSON（单一来源）编写令牌，使用 Style Dictionary v5 或 Terrazzo 构建输出为 CSS、Tailwind、TS、Swift、Kotlin/Compose、Flutter、RN。
每个平台的配方和输出示例：
references/platform-outputs.md。入门 DTCG 文件：assets/tokens.example.json。
5. 组件
基于无障碍的原语构建（参见 ui-stack-advisor）。一致的 API：variant（视觉意图）、size、tone/color（仅必要时使用）、通过数据属性表示状态、组合优于配置。每个组件都要记录所有状态：默认、悬停、激活、焦点可见、禁用、加载、错误、空、选中、只读。约定和检查清单：references/components.md。
6. 文档与治理
从 assets/DESIGN.template.md 在项目根目录编写 DESIGN.md——方向、令牌表、组件清单、该做什么/不该做什么，以及决策背后的原因。这个文件是未来会话阅读以保持一致性的依据；保持简短和最新。大型系统还会添加 Storybook（或 Ladle/Histoire）、视觉回归、带有语义化版本控制的变更日志，以及贡献流程（references/components.md#governance）。
可用的默认值（当用户没有偏好时）
| 基础要素 | 默认值 |
|---|---|
| 基础单位 | 4px；间距比例 0, 1, 2, 4, 6, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96 px |
| 字号比例 | 12, 14, 16（正文）, 18, 20, 24, 30, 36, 48, 60 px（≈1.2–1.25 比例）；产品 UI 可使用 14px 正文 |
| 行高 | 正文 1.5，标题 1.2–1.3，展示 1.1；大字号缩进字间距（−0.01 到 −0.03em） |
| 圆角 | 0, 4, 6, 8, 12, 16, 24, 完整——选择一种个性：锐利（2–4）、柔和（8–12）、圆润（16+）并一致应用 |
| 控件 | 高度 32 / 36–40 / 44–48 px；触摸目标 ≥ 44pt（iOS）/ 48dp（Android）/ 24px 最小 WCAG 2.2（目标 44） |
| 动效 | 100 / 150 / 200 / 300 / 500 ms；入场使用 cubic-bezier(0.23,1,0.32,1) ease-out，移动使用 ease-in-out，移动端使用弹簧 |
| 断点 | 640, 768, 1024, 1280, 1536（Tailwind）；组件优先使用容器查询 |
| 层级 | 4–5 级阴影；暗色模式使用更亮的表面和细微边框代替 |
| Z-index | base 0, dropdown 1000, sticky 1100, overlay 1300, modal 1400, popover 1500, toast 1600, tooltip 1700 |
默认值是基础，不是风格。独特性来自于变化的选项：字体、强调色、中性色温、圆角个性、密度和动效特征。
质量标准（完成前检查）
- 组件中没有原始值（十六进制颜色、px 字号、任意间距）——使用 grep 搜索它们
- 语义名称描述工作，而不是值或色调
- 浅色+深色都已设计并通过对比度验证（WCAG 2.2 AA）
- 每个交互式组件都有可见的焦点、禁用、加载、错误状态
- 字号比例有命名角色（展示、h1–h3、正文、标签、说明、代码），不仅仅是尺寸
- 间距一致：相同的关系 → 相同的令牌
- 动效令牌的减少动效变体
-
DESIGN.md已编写且准确 - 移动端：尊重 Dynamic Type / 字体缩放，安全区域已令牌化，触摸目标 ≥ 44/48
参考资料
references/token-architecture.md— 层级、命名语法、DTCG 2025.10 格式、模式/主题、别名规则references/scales.md— 排版（比例、流式排版、字体配对）、间距、圆角、层级、动效、密度、断点references/platform-outputs.md— CSS、Tailwind v4、shadcn 主题、React Native (NativeWind/Unistyles/Tamagui)、Flutter、SwiftUI、Compose、Style Dictionary/Terrazzo 管道references/components.md— 组件 API 规范、结构、状态矩阵、组合、文档、测试、治理assets/tokens.example.json— 入门 DTCG 令牌文件assets/DESIGN.template.md—DESIGN.md模板