extract

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

目标并非收录代码库中的每个值，而是创建有约束的系统，减少未来需要做出的设计决策，并保持界面一致。

请参阅设计系统对齐，了解令牌、组件与模式的区别、设计偏差，以及如何避免不一致导致令牌泛滥。

必要准备

用户通过 /extract 启动此工作流。此技能启用后，加载 $frontend-design ——其中包含设计原则、反模式和上下文收集协议。继续之前，请遵循该协议。如果目前还没有设计上下文，则必须先加载 $setup。

探索

分析目标区域，寻找可提取的内容：

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 或组件目录

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