extract

识别可复用的模式、组件和设计令牌，然后将其提取并整合到设计系统中，以便系统化复用。

目标不是收录代码库中的每个值，而是构建有限的系统，减少未来的设计决策，让界面保持一致。

请参阅设计系统对齐，了解令牌、组件与模式之间的区别、偏离情况，以及如何避免将不一致转化为令牌泛滥。

强制准备

阅读 frontend-design，并遵循其中的上下文收集协议。复用现有上下文，仅针对影响重大的信息缺口提问。

探索

分析目标区域，找出提取机会：

1. 找到设计系统：定位设计系统、组件库或共享 UI 目录（搜索“design system”“ui”“components”等）。了解其结构：

   • 组件组织方式和命名惯例
   • 设计令牌结构（如有）
   • 文档模式
   • 导入/导出惯例

   关键：如果不存在设计系统，请先询问，再创建。首先了解首选的位置和结构。

2. 识别模式：查找以下内容：

   • 重复组件：多次使用的相似 UI 模式（按钮、卡片、输入框等）
   • 硬编码值：应设为令牌的颜色、间距、排版、阴影
   • 不一致的变体：同一概念的多种实现（3 种不同的按钮样式）
   • 可复用模式：值得系统化的布局模式、组合模式、交互模式

• 缺失的系统：团队明显反复重新设定间距、字体、颜色、圆角或层级的地方

3. 评估价值：并非所有内容都适合提取。请考虑：
   • 使用次数是否达到 3 次以上，或是否可能重复使用？
   • 系统化是否有助于提升一致性？
   • 这是通用模式，还是特定上下文才适用？
   • 维护成本与收益相比如何？

制定提取计划

制定系统化的提取计划：

• 要提取的组件：哪些 UI 元素应成为可复用组件？
• 要创建的令牌：哪些硬编码值应转为设计令牌？
• 系统边界：哪些令牌集应刻意保持精简，以便引导决策，而不是记录混乱？
• 要支持的变体：每个组件需要支持哪些变体？
• 命名惯例：组件名、令牌名、属性名应符合现有模式
• 迁移路径：如何重构现有用法，以使用新的共享版本

重要：设计系统应循序渐进地扩展。现在提取明确可复用的内容，而不是所有将来可能有用的内容。

已有组件库时的提取方式

如果项目已经使用 shadcn/ui 等组件库，优先提取：

• 本地封装
• 可复用的组合
• 有文档说明的模式

除非项目确实需要稳定且定制化的抽象，否则不要用冗余的本地副本替换上游基础组件。

好的提取通常比组件库的基础组件高一层：不是再造一个通用的 Button，而是创建产品专用的操作栏、筛选面板、设置区域或空状态模式，并一致地使用现有基础组件。

提取与丰富

构建经过改进、可复用的版本：

• 组件：创建设计完善的组件，并具备：

  • 清晰的 props API 和合理的默认值
  • 针对不同使用场景的适当变体
  • 内置无障碍支持（ARIA、键盘导航、焦点管理）
  • 文档和使用示例

• 设计令牌：创建令牌，并具备：

  • 清晰的命名（基础令牌与语义令牌）
  • 合理的层级和组织结构
  • 说明每个令牌的适用场景
  • 为间距、排版、颜色、圆角和层级效果制定受约束的尺度（如适用）

优先采用以下系统：

• 间距：采用较小的尺度，档位之间有明确的跨度，而不是涵盖 4 到 64 之间的每个数字

• 排版：为 UI 角色精心设计一组字号和字重

• 颜色：使用定义好的色阶，而不是临时调整明暗

• 层级效果：采用少量具有语义含义的阴影，而不是无穷无尽的自定义 box-shadow

• 模式：记录模式，并说明：

  • 何时使用此模式
  • 代码示例
  • 变体和组合方式

切勿：

• 提取未经泛化的一次性、特定上下文实现
• 创建过于通用、毫无实用价值的组件
• 提取时不考虑现有设计系统惯例
• 忽略完善的 TypeScript 类型或属性文档
• 为每个单独的值都创建令牌（令牌应具有语义含义）
• 将不一致性整理成令牌目录，而不是简化并归纳为一个系统

迁移

将现有用法替换为新的共享版本：

• 查找所有实例：搜索已提取的模式
• 系统地替换：逐一更新用法，使其使用共享版本
• 全面测试：确保视觉和功能保持一致
• 删除无用代码：移除旧实现

编写文档

更新设计系统文档：

• 将新组件添加到组件库
• 记录令牌的用法和值
• 添加示例和指南
• 更新 Storybook 或组件目录

请记住：优秀的设计系统是一个不断演进的系统。随着模式的出现及时提取，审慎地丰富它们，并保持一致的维护。