Impeccable 的 Extract 流程：六步法把可复用组件与设计令牌沉淀进设计系统-育师

Impeccable 的 Extract 流程：六步法把可复用组件与设计令牌沉淀进设计系统

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

Impeccable 是一个面向前端 UI 的设计语言技能（skill），其命令体系中包含一条 Build 类别的extract [target]命令，用于从既有代码中识别重复出现的组件、硬编码值与交互模式，并将它们提炼、整合进设计系统以供系统性复用。本文完整拆解 extract.md 中定义的六步提取流程（发现设计系统、识别模式、制定计划、提取与增强、迁移、文档化），并结合仓库中的技能入口、命令元数据与示例 DESIGN.md 文件，说明每一步在真实项目中的落地方式、判断标准与红线约束。

extract 在 Impeccable 命令体系中的位置

在 plugin/skills/impeccable/SKILL.md 的 Commands 表中，extract [target]被归类为Build类别，描述为 “Pull reusable tokens and components into design system”（把可复用的令牌与组件抽入设计系统）。命令的完整元数据定义在 plugin/skills/impeccable/scripts/command-metadata.json 中：

"extract": { "description": "Pull reusable patterns, components, and design tokens into the design system. Identifies repeated patterns and consolidates them. Use when you have drift across the codebase and want to bring things back to a consistent system.", "argumentHint": "[target]" }

这段元数据点明了 extract 的典型触发场景：代码库中存在漂移（drift），希望把分散的实现拉回到一致的系统。它接收一个可选的[target]参数，用于圈定要扫描的目标区域。

值得注意的一点是，仓库中存在两份 extract 参考文档：.kiro/skills/impeccable/reference/extract.md 与 plugin/skills/impeccable/reference/extract.md，二者除第一步中的提问指令外完全一致——Kiro 版本要求“直接向用户提问以澄清无法推断的内容”，而插件版本则要求“STOP and call the AskUserQuestion tool to clarify”（停下并调用 AskUserQuestion 工具）。这体现了同一份流程文档按宿主环境（Kiro / 通用插件运行时）适配提问机制的做法。此外 skill/reference/extract.md 中还保留了一份带{{ask_instruction}}占位符的模板源，供发布管线在转换时注入对应的提问指令。

Step 1：发现现有设计系统

第一步的核心动作是找到设计系统、组件库或共享 UI 目录，并理解它的结构，具体包括四个维度：

组件如何组织（目录与分层方式）；
命名约定（组件、令牌、属性如何命名）；
设计令牌（design token）的结构；
导入/导出约定（import/export conventions）。

文档在此处给出了一个CRITICAL级别的硬约束：如果不存在设计系统，先不要创建。正确做法是先停下来向用户澄清无法推断的内容，弄清用户偏好的存放位置与结构后再动手。这条约束的意义在于：设计系统的归属位置与组织方式往往是团队决策，Agent 单方面创建一个目录结构可能与既有约定冲突。

从源码结构看，这个设计系统在本项目体系中的载体是DESIGN.md。例如 demos/landing-demo/DESIGN.md 演示了一个完整的系统文档格式：YAML frontmatter 中声明colors、typography、rounded、spacing、components等令牌层，正文则以自然语言描述“Creative North Star”（创意北极星）与关键视觉特征。SKILL.md 中的document命令（“Generate DESIGN.md from existing project code”）负责生成该文件，而 extract 的产出——组件与令牌——正是沉淀到这一层体系的。理解这一点有助于回答 Step 1 中“去哪找设计系统”的问题：优先看 DESIGN.md、共享组件目录与全局样式文件。

Step 2：识别可提取的模式

在圈定的目标区域内，文档列出了六类提取机会（extraction opportunities）：

模式类型	含义
Repeated components	相同 UI 模式被使用 3 次以上，如按钮、卡片、输入框
Hard-coded values	本应成为令牌的硬编码值：颜色、间距、排版、阴影
Inconsistent variations	同一概念存在多种实现
Composition patterns	重复的布局或交互模式（表单行、工具栏分组、空状态）
Type styles	重复出现的 font-size + weight + line-height 组合
Animation patterns	重复出现的 easing、duration 或 keyframe 组合

识别之后必须做价值评估，文档给出的判定标准非常明确：

只提取“使用 3 次以上且意图相同”的东西。过早抽象比重复更糟（Premature abstraction is worse than duplication）。

“3+ 次”是一个量化下限，“相同意图”是质性门槛——二者需同时满足。这一条与后文 NEVER 清单中“不要提取意图不同的东西”首尾呼应，构成 extract 流程中最核心的取舍判断。

Step 3：制定提取计划

动手之前必须形成一份系统性计划，覆盖五个维度：

Components to extract：哪些 UI 元素值得成为可复用组件？
Tokens to create：哪些硬编码值应升级为设计令牌？
Variants to support：每个组件需要支持哪些变体？
Naming conventions：组件名、令牌名、属性名如何与既有模式保持一致？
Migration path：如何把现有用法重构为消费新的共享版本？

文档在此处标注了IMPORTANT约束：设计系统是增量生长的。只提取当前明确可复用的部分，而不是把所有“将来可能可复用”的东西都抽出来。这与 Step 2 的 3+ 规则一致，共同防止 extract 变成一次性的“大重构”。

Step 4：提取与增强

这一步的目标是构建改进后的、可复用的版本，而非简单地把代码搬到新文件里。文档对三类产出分别提出了“增强”要求：

组件（Components）

清晰的 props API，带合理的默认值；
面向不同使用场景的恰当变体（variants）；
内建无障碍能力：ARIA、键盘导航、焦点管理；
文档与使用示例。

设计令牌（Design tokens）

命名区分primitive 与 semantic两层（如blue-500vscolor-accent）；
恰当的层级与组织方式；
记录每个令牌“何时使用”的说明。

仓库中的 demos/landing-demo/DESIGN.md 恰好示范了这种命名的分层效果：frontmatter 中定义了cream、ink、accent等具名颜色，而components层通过引用语法消费它们——例如button-primary的backgroundColor: "{colors.ink}"、rounded: "{rounded.pill}"、padding: "14px 28px"。组件定义不再写死十六进制色值，而是引用令牌，这正是“semantic 令牌 + 组件引用”的落地形态，也是 extract 完成后代码应当达到的状态。

模式（Patterns）

说明该模式何时使用；
提供代码示例；
记录变体与组合方式。

Step 5：迁移

提取完成后，必须用新的共享版本替换所有既有用法，文档列出了四个动作：

Find all instances：搜索被提取的模式的所有实例；
Replace systematically：逐一更新，使其消费共享版本；
Test thoroughly：确保视觉与功能上的对等（parity）；
Delete dead code：删除旧实现，避免新旧两套并存。

迁移阶段的关键风险在于“遗漏”与“半迁移”：搜索不充分会留下旧实现的残留，而不删除死代码则会让后续开发者继续消费错误版本。把“删除旧实现”列为第 4 步而非可选项，正是为了强制迁移闭环。

Step 6：文档化

最后一步是更新设计系统文档，包含四项工作：

把新组件加入组件库；
记录令牌的用法与取值；
添加示例与使用指引；
更新 Storybook 或组件目录（若存在）。

文档化不是收尾的“可选项”，而是 extract 流程的正式一步——组件与令牌只有在被文档覆盖后才真正可被团队（以及后续的 AI 会话）发现与复用。结合本仓库的体系来看，这一步的产出通常落在 DESIGN.md 的 frontmatter 令牌层与正文组件说明中，与document命令维护的格式保持一致。