Impeccable extract 流程详解从 AI Agent 技能文档看设计系统提取的六步方法论【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable本篇技术指南基于 Impeccable 技能/impeccable前端设计命令集中的 Extract Flow 参考文档展开完整解析从目标代码区域识别可复用的组件、设计令牌与模式并合并进设计系统的六步流程何时该停手询问用户、哪些重复模式值得提取3 次使用门槛、如何做提取规划与迁移以及仓库中DESIGN.md与cli/engine/design-system.mjs如何把提取出的令牌变成可被自动检测器校验的白名单。读完你将掌握一套可复制的设计系统收敛extract consolidate操作规范并理解令牌命名的语义层级为何会直接影响后续的自动化审计。extract 命令在 Impeccable 中的定位Impeccable 是一个面向 AI 编码工具Codex、Claude 等 harness的前端设计技能包通过/impeccable command形式暴露 23 个子命令。在 SKILL.md 的 Commands 表中extract被归入 Build 类别命令分类说明参考文档extract [target]BuildPull reusable tokens and components into design systemreference/extract.md命令的元数据argumentHint为[target]定义在 command-metadata.json 中其描述明确了 extract 的适用场景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.—— 即当代码库中出现了视觉漂移drift、同一个概念存在多套实现时用 extract 把它们收回一致的系统里。需要注意 extract 与相邻命令document的分工差异documentreference/document.md负责从零扫描现有代码生成DESIGN.md文档而 extract 负责把散落的目标区域内可复用实现收敛为共享组件与令牌并迁移既有调用点。前者是记录系统后者是建立系统。Step 1发现既有的设计系统Discover the Design System流程的第一步是定位现有的设计系统、组件库或共享 UI 目录并理解其结构组件组织方式、命名约定、设计令牌结构、import/export 约定。原文强调理解既有约定优先于动手因为后续所有命名都要对齐这些约定。这里有一条关键的控制流原文标注为 CRITICAL如果项目中不存在设计系统先不要创建。立即停止STOP如果运行时提供了结构化提问工具如 Codex 的 user-input/question 工具就使用它否则直接在对话中提问澄清你无法自行推断的信息。先弄清用户偏好的存放位置和结构再开始提取。这条规则的意义在于设计系统的存放位置根目录DESIGN.mddocs/下某个ui/包是项目约定Agent 不应擅自假设。仓库源码中也印证了这一点——cli/engine/design-system.mjs 中解析设计系统的查找顺序是当前目录的DESIGN.md含大小写变体再回退到.agents/context/与docs/两个候选目录FALLBACK_DIRS常量并支持.impeccable/design.json、DESIGN.json等 sidecar 伴生文件。也就是说设计系统在哪本身就是项目级状态必须先行确认。Step 2识别可提取的模式Identify Patterns在目标区域内寻找提取机会原文给出六类机会清单重复组件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。同一意图这个限定词很重要两个长得相似但目的不同的按钮不应合并这一点在文末 NEVER 清单中再次强调。从源码结构看仓库自带的检测引擎实际上执行着反向的 3 判定例如 tests/fixtures 下的repeated-container-text.html、overused-font.html等 fixture 正是为重复出现的模式/字体设计的测试场景说明重复计数 意图归并是整个项目检测与提取共用的核心判据。Step 3制定提取计划Plan Extraction动手前先产出一份系统性计划覆盖五个维度要提取的组件哪些 UI 元素会变成可复用组件要创建的令牌哪些硬编码值会变成设计令牌要支持的变体每个组件需要哪些变化命名约定组件名、令牌名、prop 名如何与既有模式保持一致迁移路径现有使用点如何重构为消费共享版本文档同时给出增量原则设计系统是增量生长的——提取现在明显可复用的东西而不是所有将来某天可能可复用的东西。值得注意的是第 4 项命名约定并非空话而是有下游约束的。DESIGN.md的 frontmatter 是机读的令牌层示例见 demos/landing-demo/DESIGN.mdLumina 演示项目colors: cream: #faf6ef ink: #1f1a15 accent: #c8552b accent-deep: #a8431f typography: display: fontFamily: Fraunces, Georgia, serif fontSize: clamp(3rem, 7vw, 5.5rem) fontWeight: 400 lineHeight: 1.05 letterSpacing: -0.02emdocument.md 中的 frontmatter 规则要求颜色键使用描述性语义 slug如oxblood-deep、editorial-magenta而不是blue-800这类裸值编号——这正是 extract 文档tokens 应有语义含义primitive vs semantic 分层在真实文件中的体现。仓库根目录的 DESIGN.md 则是同一结构的完整实例品牌锚点色kinpaku-gold、verdigris-patina、表面色lacquer-black等、中性阶梯neutral-100…neutral-22均带注释说明用途且文件头声明了frontmatter 是 portable exportCSS 文件才是 source of truth的双向同步约定。Step 4提取并富化Extract Enrich构建改进后的、可复用的版本原文对三类产物分别提出质量要求组件清晰的 props API 与合理默认值针对不同用例的恰当变体内建可访问性ARIA、键盘导航、焦点管理配套文档与用法示例。设计令牌清晰命名primitive 与 semantic 分层、恰当的层级与组织、每个令牌的何时使用文档。模式Patterns该模式何时使用、代码示例、变体与组合方式。这里富化Enrich一词提示了 extract 与简单剪切粘贴的区别提取出的共享版本应当比原有的散落实现更完善默认值、a11y、文档否则迁移只会把缺陷也集中化了。Step 5迁移Migrate替换既有使用点四个动作缺一不可找出所有实例搜索被提取模式的既有实现系统性替换逐一更新为消费共享版本充分测试确保视觉与功能等价parity删除死代码移除旧实现避免双份真相。视觉与功能等价是这一步的验收标准。可以推断这与 Impeccable 全局有界验证bounded passes的验证哲学一致——SKILL.md 要求构建完成后以批量方式做有上限的验证轮次而不是无休止的自我 QA。Step 6文档化Document最后更新设计系统文档本身将新组件加入组件库记录令牌的用法与取值补充示例与使用指南更新 Storybook 或组件目录。文档化不是可选尾巴在本仓库的证据链中DESIGN.md的 frontmatter 才是被自动检测消费的机器可读层详见下节跳过文档化等于让提取成果对后续所有 Agent 会话和检测器不可见。红线清单NEVER 条款原文以 7 条 NEVER 收尾是对前六步的负向约束不要提取一次性、场景绑定的实现而不做泛化不要创建泛化到毫无用处的组件不要在不考虑既有设计系统约定的情况下提取不要跳过 TypeScript 类型或 prop 文档不要为每个值都建令牌令牌必须有语义含义不要提取意图不同的东西两个相似但目的不同的按钮应各自独立。这 7 条与 Step 2 的3 次同一意图门槛、Step 4 的语义令牌分层共同构成 extract 的决策边界宁可保留重复不可制造错误的抽象。源码印证令牌如何被下游检测器消费extract 的产出并非止步于代码整洁而是接入了仓库的自动化检测闭环。cli/engine/design-system.mjs 展示了这一闭环的实现解析层loadDesignSystemForCwd()读取DESIGN.md的 YAML frontmatter内置了一个支持引号、转义与注释的parseYamlSubset解析器并合并 sidecarDESIGN.json/.impeccable/design.json中的colorMeta、roundedMeta、shadows等扩展字段归一化为normalizeDesignSystem()输出的白名单结构allowedFonts、allowedColorKeys、allowedRadii、allowedFontSizes、allowedShadowColors。判定层isAllowedFont()、isAllowedColorRaw()、isAllowedRadiusRaw()、fontSizeStepStatus()逐一校验源码中的字面量是否在白名单内。颜色比较允许每通道 ±6 的容差COLOR_CHANNEL_TOLERANCE 6阴影色则额外要求 alpha 容差 0.02SHADOW_ALPHA_TOLERANCE因为同一黑色在不同 alpha 下是不同令牌——这正是 extract 文档令牌要有语义层级在数值层面的体现。发现层越界的字体字面量会被makeDesignFinding(design-system-font, ...)生成带ignoreValue的发现项finding例如 Frauncesis not declared in DESIGN.md typography。作用域控制findDesignRoot()从扫描目标自身位置向上查找设计系统根处理 monorepo workspace glob、嵌套package.json与独立.git边界避免用项目 A 的 DESIGN.md 去判项目 B的跨项目污染。这条链路的含义是extract 步骤中哪些值该成为令牌、令牌怎么命名直接决定了后续detect检测器的判定基准——语义命名、层级清晰的令牌让白名单准确而为每个值建令牌的泛滥做法会制造大量误报。文档中 Step 4 的令牌分层要求由此获得了工程上的必要性证明。一个工程细节文档的模板化分发仓库中同时存在两份 extract 文档安装版 .agents/skills/impeccable/reference/extract.md 与源模板版 skill/reference/extract.md。两者仅一行差异——源模板中 Step 1 的 CRITICAL 条款写作{{ask_instruction}}占位符安装到具体项目时被解析为宿主工具特定的提问指令Codex 版本展开为use Codexs structured user-input/question tool when available; if unavailable, ask directly in chat。这说明 Impeccable 的分发管线见 scripts/lib/transformers会按目标 harness 适配同一份流程文档而发现设计系统前先询问用户这一控制流是所有平台变体共享的不变量。小结可复用的六步检查表找到或确认不存在设计系统不存在时停手询问不擅自创建。按六类机会清单扫描目标区域用3 次同一意图过滤。产出五维计划组件、令牌、变体、命名、迁移路径。构建富化版本props API、语义令牌、内建 a11y、文档。系统性替换全部使用点验证 parity删除旧实现。更新设计系统文档与组件目录让成果进入可被工具和 Agent 消费的状态。配套红线不泛化一次性实现、不造过度泛化的组件、不违背既有命名约定、不跳过类型与文档、不为无语义的值建令牌、不合并意图不同的相似组件。在 Impeccable 的完整工作流里extract 的输出物DESIGN.md既是给人看的文档也是cli/engine/design-system.mjs一类检测引擎的判定基准——设计系统的提取因此不只是重构而是把视觉一致性固化为可持续校验的契约。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考