design-system

设计系统

构建、演进或审查设计系统。原则上不受技术栈限制。具体实现取决于技术栈（Figma、Storybook、代码库等），但其结构和治理原则具有通用性。

此技能用于构建设计系统。若要将系统应用于特定页面或组件，请使用 design-standards。若要打造品牌视觉识别，请使用 brand-identity。

---

适用场景

• 从头构建设计系统
• 审查现有系统，查找缺失或碎片化之处
• 在系统层面定义设计令牌
• 规划组件库的结构
• 建立贡献和治理模式
• 将临时拼凑的组件迁移到有文档记录的系统中

不适用场景

• 设计单个页面或组件（使用 design-standards）
• 品牌识别设计（使用 brand-identity）
• 前端组件级实现（使用 frontend-component-build）
• 纯粹用于营销的设计文档（使用 brand-style-guide）

---

所需输入

• 品牌识别（令牌、语气、图像方向）
• 系统需要支持的产品界面（Web、移动端、营销、应用、内部工具）
• 团队及其工作工具（Figma、代码框架、文档平台）
• 现有组件，即使尚未编写文档
• 约束（无障碍要求、性能目标、浏览器支持）

如果尚未定义品牌识别，请先运行 brand-identity。

---

框架：5 个层级

完整的设计系统由五个层级组成，逐层叠加。每一层都为上一层提供支撑。

1. 基础（令牌）

最基本的设计决策：颜色、字体、间距、圆角、阴影、动效、断点。

这一层的重要性：

• 令牌是所有上层内容的事实来源
• 令牌的更改会自动传递到各处
• 没有令牌，系统就没有基础

输出：

• 有文档记录的令牌集合（参见 design-standards/references/design-tokens-template.md）
• 代码中的令牌实现（CSS 变量、JS 对象、Style Dictionary 等）
• Figma 中的令牌实现（变量和样式）
• 说明何时使用哪些令牌的入门文档

常见模式：

• 两层令牌：基础令牌（原始值）+ 语义令牌（命名用途）。例如：color-blue-600（基础）+ color-text-link（语义）。组件引用语义令牌。主题更改时，更新的是语义令牌，而非基础令牌。

2. 元素（原子）

最小的功能构建块：按钮、输入框、标签、徽章、图标、链接、分隔线。

每个元素应记录：

• 视觉变体（主要、次要、幽灵等）
• 尺寸变体（小、中、大）
• 状态（默认、悬停、焦点、激活、禁用、错误、加载中）
• 组成结构（构成该元素的部分）
• 间距和比例
• 无障碍性（键盘支持、屏幕阅读器行为、ARIA）
• 代码用法（属性、示例）

输出：

• Figma 元素库
• 代码中的元素组件
• 每个元素对应的文档

3. 组件（分子 + 有机体）

由多个元素组合而成、可识别的 UI 模式，例如卡片、警示框、模态框、导航、表单、数据表格、页眉、页脚。

每个组件应记录：

• 组合方式（使用了哪些元素）
• 变体和配置
• 使用场景（何时选用此组件，而非其他替代方案）
• 布局行为（响应式、固定容器、全宽）
• 反模式（何时不应使用）

输出：

• 组件库
• 每个组件对应的文档及使用指南

4. 模式（模板）

由组件组合而成的较大结构，例如登录流程、设置页面、仪表板布局、营销页面区块。

每个模式应记录：

• 结构及所用组件
• 支持的用户旅程
• 布局网格和间距
• 响应式行为
• 变体（例如“带侧边栏”“全屏”“模态框”）

输出：

• 模式库或页面模板
• 展示完整示例的文档

5. 文档与治理

系统如何被使用、如何参与贡献，以及如何维护。

文档包括：

• 新团队成员入门指南
• 如何使用与如何扩展
• 贡献模式
• 版本策略
• 发生破坏性变更时的迁移路径
• 重大系统决策的决策日志

治理包括：

• 系统的负责人（团队或轮值人员）
• 如何提议和批准新组件
• 如何解决冲突
• 系统如何演进，以及如何保持稳定
• 审查和更新的频率

---

工作流

对于新的设计系统

1. 盘点现有 UI。 为产品中的每个组件、按钮、表单和模态框截图。不同 UI 模式的清单就是你的初始范围。
2. 找出重复项。 同一个组件在产品中以 5 种不同方式构建。这些是最值得优先整合的目标。
3. 定义基础规范。 建立包含基础层和语义层的令牌集，并为每个令牌编写文档。
4. 审查元素。 根据清单找出实际元素（按钮、输入框等），并将变体精简到一组受管理的范围内。
5. 构建元素库。 使用 Figma + 代码，并为每个元素编写文档。
6. 找出优先组件。 找出出现频率最高的 10 到 15 个组件，并优先构建这些组件。
7. 记录模式。 编写展示系统实际用法的页面级模板。
8. 建立治理机制。 明确负责人、贡献模式和审查频率。
9. 逐步推出。 将现有界面逐步迁移到系统中。

对于现有设计系统审计

1. 盘点现有内容。 哪些内容有文档记录、哪些在 Figma 中、哪些在代码中，以及哪些实际上已在生产环境中使用。
2. 梳理差距。 找出系统不完整之处，以及团队因系统无法满足需求而在系统之外构建的地方。
3. 梳理碎片化情况。 找出系统实现不一致的地方（Figma 与代码、Web 与移动端、多个团队之间）。
4. 找出偏离。 找出偏离文档规范的组件。
5. 确定修复优先级。 优先修复基础规范的缺失，其次是高频组件的偏离问题，最后清理罕用组件。
6. 制定推出计划。 重大变更需要迁移路径。

---

失败模式

• 品牌尚未确定就开始构建系统。 令牌取决于品牌。先确定品牌。
• 极端地自底向上构建。 花 6 个月打磨令牌和元素，却没有产出任何人会用的组件。先交付人们需要的组件，再迭代完善令牌。
• 单人维护系统。 没有治理机制的系统会在原设计师离职后立即失效。尽早明确负责人。
• 文档过时。 代码与文档不一致的系统比没有系统更糟。要么保持同步，要么删除文档。
• 所有内容都做版本管理。 认为每个组件都需要主版本号。大多数组件可以原地演进。仅在发生破坏性变更时才进行版本管理。
• 教条式采用“原子设计”。 原子、分子、有机体是有用的思维模型，而非僵化的分类法。不要争论某个东西究竟是分子还是有机体。
• 闭门造车。 不听取使用团队意见而设计的系统会被忽视。与使用方共同设计。
• 没有弃用路径。 旧组件会永远留在代码中，因为没人知道是否可以安全移除。明确记录弃用信息。
• 令牌膨胀。 为只有 10 种颜色的品牌定义 200 个颜色令牌。要保持克制。大多数产品所需的令牌比现有数量少。

---

输出格式

设计系统有多项交付物，通常包括：

• 文档站点（Notion、专用站点、GitHub Pages、Storybook 插件等）
• Figma 库（或同类设计工具）
• 代码库（npm 包、monorepo 工作区、可复制粘贴的组件）
• 决策日志（系统级决策及其依据）
• 路线图和变更日志

对于设计系统审计，输出内容为 Markdown 报告 design-system-audit.md：

1. 现有内容清单（基础、元素、组件、模式）
2. 差距分析
3. 碎片化分析
4. 偏离分析
5. 按优先级排列的整改计划
6. 治理建议

---

如果无法获取所需数据

此技能的输出依赖于其无法自行生成的数据、测量结果或工具结果。如果无法获取或核实必需的输入、工具或数据源，合规的输出应是交付物，并说明其中的差距：需要哪些内容、实际获取或核实了哪些内容，以及输出的哪些部分受到影响。绝不允许为了完成交付物而捏造、估算或插值推算必需的数字。说明差距本身就是完整的答复。

---

参考文件

• references/system-architecture.md - 四层模型（令牌、基元、模式、模板），以及如何判断新增工作应归属哪一层。
• references/system-audit-template.md - 审计现有设计系统的模板。
• references/governance-playbook.md - 活跃系统的贡献模式、所有权和决策流程。