设计系统
叶技能 范围：设计领域；通过其域名或名称可访问。
设计系统只有在团队信任它时才能节省决策成本。偏离会悄无声息地侵蚀这种信任：一个组件有三个名称，原始十六进制值与它们重复的令牌并列，无人记录的状态。一旦人们停止信任系统，他们就会绕开它。此方法以三种模式运行——审计 现有系统，记录 组件以便正确使用，扩展 系统以适配新模式——并将每种模式都扎根于实际源文件：令牌文件、组件代码和设计文件，而非一个泛泛的设计系统概念。
一个实际审计发现的示例
情景（虚构）： 一个带有令牌文件的React库；请求是“审计我们的按钮和卡片”。
命名 Button、IconBtn 和 .btn-link 三个名称指代同一个概念。
→ 采用带有 `icon` 和 `link` 变体的 Button；将旧名称作为别名保留一个发布版本。
令牌 Card 和 Modal 中有 23 个硬编码颜色。其中 18 个等于现有令牌（机械替换）；5 个不匹配任何令牌。
→ 这 5 个需要决策：是缺失的令牌，还是需要修复的设计错误。
状态 Card 没有焦点状态，尽管它是可点击的。
可复用的选择在于区分：一个值与现有令牌重复，这是机械修复；而一个值不匹配任何令牌，则是需要交给人员决定的设计问题。
收集系统信息
在评估之前先阅读现有内容：令牌源文件、组件代码或库、以及文档。例如，搜索 rg -n '#[0-9a-fA-F]{3,8}\b|[0-9]+px' src/components 可以找到代码中的硬编码值；请根据技术栈调整模式。
标有
~~的部分命名的是工具类别，而非具体产品：如~~设计工具（例如 Figma）或~~知识库（例如 Notion）。请使用宿主提供的该类别下的任何可用工具；如果没有可用工具，则跳过该步骤。
使用 ~~设计工具，检查设计文件中的组件名称、变体、图层结构和令牌使用情况，并与代码进行比较。使用 ~~知识库，查找现有的组件页面和使用指南，仅在用户要求时才将更新后的文档发布到那里。
一个系统包含三个层次；审计和文档覆盖每个层次：
| 层次 | 内容 |
|---|---|
| 令牌 | 颜色（品牌色、语义色、中性色）、排版、间距、圆角和边框、高度、动效持续时间和缓动函数 |
| 组件 | 变体、状态（默认、悬停、焦点、激活、禁用、加载、错误）、大小、行为、无障碍 |
| 模式 | 表单、导航、数据展示、反馈——组合起来解决常见问题的组件 |
当令牌在工具之间移动时，设计令牌社区组格式（首个稳定版本2025.10，2025年10月）是通用交换格式；请遵循项目已使用的格式。
原则
- 一致性优于新颖性。 系统存在是为了让团队不再重复决定相同的事情；一个一次性变体需要一个系统缺少的理由。
- 在约束内可组合。 优先使用变体或现有组件的组合，而不是创建新组件。
- 未记录即不可用。 一个没人能找到的状态或变体会被重做。
- 版本化与迁移。 破坏性的重命名或删除需要迁移路径，例如一个版本的别名和一个代码转换工具或搜索工具来查找所有使用点。
审计
报告数量和证据，而不是分数：没有标准的数字会掩盖哪个问题更重要。
## 设计系统审计：[范围]
**审核内容：** [组件、令牌文件] | **发现：** [按类别统计数量]
### 命名
| 问题 | 位置 | 建议 |
|---|---|---|
### 令牌覆盖
| 类别 | 已定义令牌 | 硬编码值 | 匹配现有令牌 |
|---|---|---|---|
### 组件完整性
| 组件 | 状态 | 变体 | 文档 | 无障碍 |
|---|---|---|---|---|
| Button | 完整 | 部分：无纯图标尺寸 | 缺失 | 存在焦点环 |
### 优先行动
1. [最高用户或团队影响优先，附所需工作量]
文档
为所有使用该组件的用户记录一个可复用的组件。属性（props）和代码示例应从真实组件中获取，而非虚构的 API。
## 组件：[名称]
[它是什么以及何时使用——以及何时使用其他组件]
### 变体
| 变体 | 使用场景 |
|---|---|
### 属性
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
### 状态
| 状态 | 视觉效果 | 行为 |
|---|---|---|
### 无障碍
- **角色：** [角色或原生元素]
- **键盘：** [Tab, Enter, Space, Escape, 方向键]
- **屏幕阅读器：** [宣告为…]
### 注意事项
| 做法 | 不要做 |
|---|---|
### 示例
[项目框架中的简短代码片段]
扩展
在提出任何新内容之前，列出接近的现有组件并说明为什么每个都不够；大多数请求最终会变成一个新的变体。新组件应重用现有令牌，并仅在必要时提出新令牌及其理由。
## 提议的组件：[名称]
### 问题
[用户需求或缺口]
### 现有选项
| 组件 | 共同点 | 不足之处 |
|---|---|---|
### 设计
属性、变体和状态参照文档模板；使用的令牌。
### 无障碍
角色、键盘和屏幕阅读器行为。
### 待定问题
[需要设计评审的决策]
系统的组件和令牌是此方法的主题。单个功能或屏幕的规范表，以及新产品的视觉方向，属于独立的设计工作；系统审计也不能替代 WCAG 审计。