Impeccable extract 命令实战把重复 UI 收敛为可复用设计系统的工作流【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable导读extract [target]是 Impeccable 设计技能体系中的Build 类命令它的目标不是新增功能而是反向工程从现有界面中识别重复出现的组件、硬编码值与组合模式将它们提取、富化并收敛进项目既有的设计系统实现一次构建、处处复用。本文以 extract.md同名副本见 plugin/skills/impeccable/reference/extract.md为骨架完整展开其六步工作流与NEVER禁忌清单并结合仓库中的 SKILL.src.md 命令路由与 DESIGN.md 令牌结构说明一套可落地的抽取原则。读完你能够掌握如何评估该不该抽、如何区分原始令牌与语义令牌、如何规划变体与迁移路径以及如何在抽离后保持视觉与功能对等。一、extract 在整个技能体系中的定位在 Impeccable 中所有能力都以命令 参考文档reference的形式封装。命令总表见 SKILL.src.md将命令按类别组织为 Build构建、Evaluate评估、Refine打磨、Enhance增强、Fix修复、Iterate迭代六大类其中命令类别职责craft [feature]Build普通新需求的别名已弃用shape [feature]Build写码前先规划 UX/UIinitBuild把持久化的产品上下文写入 PRODUCT.mddocumentBuild由现有代码生成 DESIGN.mdextract [target]Build把可复用令牌与组件抽进设计系统与之邻近的document解决的是逆向记录现状读代码、沉淀 DESIGN.md而extract解决的是逆向收敛复用把散落在页面里的重复实现提升为设计系统内一等公民。二者的落点都在 DESIGN.md 及其背后那套令牌与组件库。每次会话首先由 context.mjssetup 阶段运行加载 PRODUCT.md、DESIGN.md 与对应 surface briefextract 正是在系统上下文已就位的前提下被调用的。若收到无参数的impeccable调用则按 routing.md 的路由规则展示上下文感知菜单绝不自动执行命令。二、Step 1发现设计系统Discover抽取的第一步不是去改动任何页面而是先回答我们要把代码抽到哪里去。需要摸清的既有事实包括设计系统 / 组件库 / 共享 UI 目录是否存在找到它的物理位置仓库路径与配套入口组件如何组织目录层级、一个组件一个文件还是多组件共文件命名约定组件名、文件名、CSS class 前缀、令牌名的既定拼写习惯设计令牌结构颜色 / 间距 / 字号 / 圆角 / 阴影各自放在哪里、用什么层级表达导入导出约定组件如何被消费、CSS 如何进入全局作用域。关键拦截条件系统不存在时不要擅自创建文档对这一步给出CRITICAL级约束如果项目尚不存在设计系统不要顺手创建一个而是立即停下通过question工具向用户澄清偏好的存放位置与结构再决定是否进入抽取。原因是设计系统的目录位置、命名习惯、令牌粒度都属于长期架构决策Agent 单方面拍板会造成后续迁移成本抽取工作必须嵌入既有惯例而不是另立一套惯例。这一约束在仓库中有直接体现项目根目录的 DESIGN.md 采用 frontmatter 承载便携导出令牌正文第 272 行起声明所有值逐字镜像site/styles/kinpaku-tokens.css该文件才是唯一事实来源source of truth并在第 355 行明确Kit 原语消费令牌文件里的令牌。也就是说抽取出的任何令牌若要落地都必须汇入既有的kinpaku-tokens.css并同步 DESIGN.md 的 frontmatter——这就是先理解再动手的仓库级范例。三、Step 2识别抽取机会Identify Patterns在目标区域内系统性地寻找六类抽取机会机会类型判据典型例子重复组件同一 UI 模式出现 3 次及以上按钮、卡片、输入框硬编码值本应成为令牌的颜色 / 间距 / 字阶 / 阴影#FF5F56、0 18px 48px rgba(...)不一致变体同一概念被多套实现描述三种长得不同的空状态组合模式反复出现的布局或交互拼装表单行、工具栏分组、空状态骨架字体样式反复出现的 font-size weight line-height 组合卡片标题字重档位动画模式反复出现的 easing / duration / keyframe 组合统一 hover 位移动画价值评估3 次复用 同一意图文档给出了一个非常克制的量化闸门只有当同一模式以相同意图被使用 3 次以上才值得抽取——过早抽象比重复更糟Premature abstraction is worse than duplication。两点都关键3 次过滤掉一次性页面特例为一个只在 hero 用一次的丝带抽组件只换来自增抽象层同一意图过滤掉形似而神异的案例两个视觉相近但语义不同的按钮应当各留原地见文末 NEVER 清单的对应条目。四、Step 3系统化抽取计划Plan进入动手前先产出计划书明确五件事要抽取的组件哪些 UI 元素升级为可复用组件要创建的令牌哪些硬编码值转正为设计令牌要支持的变体每个组件将来需要哪些形态差异primary / secondary / ghost、尺寸档位等命名约定组件名、令牌名、prop 名必须贴合既有模式不能自造平行词汇迁移路径如何把现存使用点重构到共享版本谁先谁后。IMPORTANT级提醒在此出现设计系统是增量生长的。只抽当下明确可复用的不要抽将来或许可复用的一切。这与 Step 2 的 3 次闸门一脉相承——计划的对象是已证实的需求而非脑补的需求。仓库中的 DESIGN.md 恰好示范了命名约定要贴合既有体系的产物长什么样frontmatter 里 color 区定义了kinpaku-gold、lacquer-black、champagne等原始颜色值而components区用花括号引用语法把语义别名指向原始令牌例如components: button-primary: backgroundColor: {colors.kinpaku-gold} textColor: {colors.dark-ink} typography: {typography.title} rounded: {rounded.xs}这里button-primary、button-secondary、input-text、card、nav-link就是组件级语义令牌——它们抽象了主按钮该用什么底色/文字色/圆角这一整套决策页面代码不必逐条拼原始值。这就是 Step 3/4 的命名与结构在真实仓库里的落地样本DESIGN.md。五、Step 4抽取并富化Extract Enrich抽取不是把代码原样搬到共享目录而是构建更好的可复用版本。文档按三类对象分别给出富化要求组件清晰的 props API 与合理的默认值sensible defaults为不同使用场景提供合适变体内建可访问性ARIA、键盘导航、焦点管理附带文档与用法示例。设计令牌命名清晰区分原始令牌primitive与语义令牌semantic。原始令牌描述有什么色值、字号、间距语义令牌描述何时用token 对应的角色与场合层级与组织得当可被索引文档化每个令牌的使用时机避免同一个颜色语义散落成三个名字。模式patterns说明何时使用该模式、配套代码示例、变体与组合方式——让未来读者能判断这里该不该套用。DESIGN.md 对原始 / 语义二分的阐释值得作为注脚第 385-391 行强调文本层champagne/body/muted/faint/mute-deep任何层级都不携带暖色暖色由金色强调与表面承担第 402-410 行的 Color Rules 则规定了金代表品牌、绿代表改进状态、纸面light mode上小尺寸金色必须降级为 patina 深绿以保证对比度。这些规则的存在意味着令牌不只是值还捆绑了何时可用 / 何时禁止的语义约束——抽取令牌时必须连语义一起带走否则就会产生 DESIGN.md 中明确批评的naive read 把金色当成 body 文字色式的误用。六、Step 5迁移Migrate共享版本就绪后用工程化方式替换既有使用点Find all instances搜索目标模式的所有出现位置组件引用、样式类、硬编码值Replace systematically逐一更新为消费共享版本保持替换顺序可控Test thoroughly确保视觉与功能对等visual and functional parity——替换后外观与行为不得漂移Delete dead code清理旧实现避免新旧两套并存造成二次分叉。迁移是整条链路里最容易产生回归的环节文档要求先系统性替换再彻底测试最后才是删死代码——顺序颠倒先删后换会留下不可回滚的窗口。测试手段在仓库中有现成支撑tests 目录包含大量视觉对等验证设施例如 live-browser-source.test.mjs、framework-fixtures.test.mjs 用 fixture 工程验证改动后的渲染结果fixtures/antipatterns 下还有一批应被识别 / 应通过的对照样例如 design-system.html、should-pass.html可推断这类 fixture 正是迁移后用于抽查没把系统改坏的比对基线。七、Step 6文档化Document抽取闭环的最后一环是把成果写回知识层否则下一位维护者依然会重复发明把新组件登记进组件库记录令牌的取值与使用场景补示例与使用指南更新 Storybook 或组件目录等展示面。在 Impeccable 仓库中这一步的文档载体可落到三处设计令牌与组件原语写回 DESIGN.md并同步其镜像的 CSS 令牌文件命令语义更新至对应 reference 文档extract.md 与其多份部署副本包括 .opencode/skills/impeccable/reference/extract.md、plugin/skills/impeccable/reference/extract.md若要在用户项目中落地则对应项目自身的 DESIGN.md / 组件目录——这正是 Step 1 先找既有系统的接续。八、NEVER六条不可逾越的边界文档以一组硬性禁令收尾它们共同定义了负责任的抽取与破坏性重构的分界线不要抽取一次性、强上下文绑定的实现而不做泛化——特例不该升格为组件不要创建过于通用而失去意义的组件——万金油组件的抽象接口最终会让每个使用者各写一套 override不要无视既有设计系统的惯例去抽取——惯例不一致等于制造第二套系统不要跳过 TypeScript 类型或 prop 文档——缺类型的共享组件会立刻退化为不可靠的复制粘贴源不要为每个数值都建令牌——令牌必须承载语义含义只为某个间距值建--space-13px只会让令牌表失去信噪比不要抽取意图不同的东西——两个看起来相似但用途不同的按钮应当保持分离。把第 6 条与 Step 2 的同一意图闸门对照看能读出这套方法论的核心立场复用性以意图为单位而不是以视觉相似度为单位。视觉趋同是抽取的必要信号却不是充分条件——只有当什么场景下该用它、它的语义是什么都一致时合并才成立。九、与其他流程的衔接与适用前提何时轮到 extract按 routing.md 与 SKILL 总表的建议extract属于 Build 类命令通常在需要从既有 target 收敛复用时被显式调用{{command_prefix}}impeccable extract [target]它依赖 setup 阶段已加载的 DESIGN.md / PRODUCT.md 上下文因此运行顺序应在context.mjs之后。与 document 的分工document生成 DESIGN.md描述现状extract改造设计系统改变现状。若项目尚无 DESIGN.md应先走document捕获视觉体系再评估抽取避免在无系统认知的前提下盲目动手。适用限制extract 描述的是面向组件库 / 令牌的工作流主要用于 Web 前端代码对 iOS / Android / adaptive 原生平台命令语义需按对应 reference如 adapt.native.md、audit.native.md 的同类原生变体另行判断。它以当前仓库实际暴露的 reference/extract.md 与其部署副本内容为准。十、小结Impeccable 的extract流程把把重复代码抽成设计系统这件容易失控的事拆解为六步可控流水线发现系统 → 识别机会 → 制定计划 → 抽取富化 → 系统迁移 → 文档回写并由三条纪律兜底——不存在的系统不擅自创建、不够 3 次的复用不抽取、意图不同绝不合并。落到工程实践上它要求的核心能力其实只有两条对复用边界的克制判断该不该抽以及对组件/令牌质量的富化意识抽出后好不好用。配合 DESIGN.md 中原始令牌与语义令牌的分层组织这套工作流可以作为任何前端项目做设计系统收敛时的可执行检查表。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
