/impeccable extract实战：把组件和Token提炼进设计系统
【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable
impeccable 是一款面向 AI 编程代理的设计指导技能，一句话定位：让 AI 更会做设计的"设计语言"。它的/impeccable extract命令可以自动扫描代码，把散落各处的可复用组件和设计 Token（Design Tokens）提炼进你的设计系统——颜色、间距、字重不再是写死的魔法数字，而是有名字、有文档、可复用的资产。这篇文章带你完整走一遍 extract 的实战流程。
一、为什么需要 extract？
大多数项目的设计"债"长这样：
- 按钮写死了
#3B82F6，卡片写死了#1E293B，换个页面又抄一遍； - 同一个卡片在 5 个页面有 5 种圆角和阴影；
- 想改一个主色，全局搜索改 30 处，还总有漏网的。
extract就是干这件事的：它像一个老练的设计系统工程师，帮你发现模式 → 提炼组件 → 沉淀 Token → 迁移旧代码 → 补齐文档，全程由 AI 在你的项目里自动完成。
它的完整命令表可以在技能定义里查到：skill/SKILL.src.md，extract被归类在 Build（构建）类目下。
二、一条命令启动：/impeccable extract [target]
在项目根目录装好 impeccable（npx impeccable install）并跑过/impeccable init之后，直接在 AI 编程工具里输入：
/impeccable extract checkout[target]是可选参数，指定要提炼的区域（比如checkout、dashboard）。不给 target 时，它会先分析你的设计系统在哪里、结构如何，再决定提炼范围。
💡 小提醒：如果项目里还没有设计系统，它不会擅自替你创建一个，而是先问你希望放在哪个目录、按什么结构组织。
三、extract 的六步内部流程
这条命令背后是一套写死的流程规范，源码在 skill/reference/extract.md，共 6 步，理解它你就知道它"动了什么手脚"。
Step 1：发现设计系统
先定位你现有的设计系统、组件库或共享 UI 目录，摸清组件组织方式、命名习惯、Token 结构、导入导出约定。这是后续所有提炼的"宪法"——新东西必须长得像旧东西。
Step 2：识别可提炼的模式
它会在目标区域找 6 类"提炼机会"：
| 模式类型 | 典型例子 |
|---|---|
| 重复组件 | 同一按钮/卡片/输入框出现 3 次以上 |
| 硬编码值 | 应变成 Token 的颜色、间距、阴影 |
| 不一致变体 | 同一个概念有多种实现 |
| 组合模式 | 表单行、工具栏分组、空状态等重复布局 |
| 类型样式 | 重复出现的字号+字重+行高组合 |
| 动画模式 | 重复的缓动、时长、关键帧组合 |
这里有一条黄金阈值：只有被使用 3 次以上、且意图相同的，才值得提炼。原文说得很直白："过早抽象比重复更糟"。
Step 3：制定提炼计划
动手前先出方案：哪些元素变组件？哪些值变 Token？每个组件要支持哪些变体？命名如何贴合现有约定？旧代码怎么迁移？
它还强调一句反直觉的原则：设计系统是增量生长的。只提炼现在明显可复用的，别把"将来可能可复用"的东西一股脑塞进去。
Step 4：提炼与增强
这是产出质量最高的一步，产出的不是"复制粘贴的组件"，而是增强版：
- 组件：清晰的 props API + 合理默认值 + 场景化变体 + 内置无障碍（ARIA、键盘导航、焦点管理）+ 使用文档；
- Token：区分"原始值（primitive）"与"语义值（semantic）"，层级清晰，并写清每个 Token 的适用场景；
- 模式：标注何时使用、附代码示例和可组合的变体。
Step 5：迁移旧代码
提炼完不迁移等于白做。它会：搜索所有旧实现 → 逐处替换为共享版本 → 测试视觉与功能一致性 → 删除死代码。
Step 6：补齐文档
最后更新设计系统文档：新组件入册、Token 取值说明、使用范例，有 Storybook 就同步更新组件目录。
四、提炼成果长什么样？
以 impeccable 自己的仓库为例，提炼后的设计 Token 会沉淀在根目录的 DESIGN.md 里——每个颜色都有语义化命名（如kinpaku-gold主强调色、patina-deep深色氧化态），并明确标注"哪个文件才是唯一事实来源"。这种"有名字、有注释、有层级"的 Token 结构，正是 extract 第 4 步"原始值 vs 语义值"原则的落地效果。
设计系统相关的测试夹具也可以在 tests/fixtures/design-system.html 中查看。
五、extract 的"红线"清单
流程规范末尾有一份 NEVER 列表，值得每个开发者收藏：
- ❌ 不泛化就提炼一次性实现；
- ❌ 创建"太通用以至于没用"的组件；
- ❌ 无视现有设计系统约定；
- ❌ 跳过 TypeScript 类型或 props 文档；
- ❌ 给每个值都建 Token（Token 必须有语义）；
- ❌ 强行合并"长得像但意图不同"的组件。
六、相关资源速查
- 提炼流程规范：skill/reference/extract.md
- 技能主定义（命令表）：skill/SKILL.src.md
- Token 范例文件：DESIGN.md
- 项目说明与安装方式：README.md
- 产品上下文文档说明：PRODUCT.md
上手建议：先init建立设计上下文，再挑一个重复度最高的模块（比如按钮群或卡片群）跑/impeccable extract，最后配合/impeccable polish做一次设计系统对齐——这套组合拳下来，你的项目会从"每个页面一套皮肤"进化成"一套系统管全站"。
【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
