Impeccable Visualize 实战指南：Comp 方向稿的三选一审批与资产生产管线

Impeccable Visualize 实战指南：Comp 方向稿的三选一审批与资产生产管线

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

visualize.md是 Impeccable 技能系统中 comp 主导（comp-led）构建流程的核心参考文档。它定义了一条完整且强约束的视觉工作流：在确认方向之后、编写任何页面代码之前，围绕指定页面产出三张高保真方向稿（comp），交由用户通过单一审批点裁决，随后把获批的 comp 转译为可测量的规格（spec），并在 plates 阶段生产所有栅格资产，同时通过嵌入 prompt 为每张图建立可追溯的 provenance。读完本文，你将掌握 comp 轮次的触发条件与状态机前提、三选一方案的设计纪律、审批记录的持久化机制、comp 转规格时 plate 与语义区域的判类标准，以及资产生产与 prompt 溯源的全套命令与目录约定。

本文的关联文档位于 .hermes/skills/impeccable/reference/visualize.md，它的上级流程定义在 .hermes/skills/impeccable/reference/new-work.md，命令入口与版本声明见 .hermes/skills/impeccable/SKILL.md。

Comp 轮次的前提：状态机、前置文档与加载边界

什么时候加载 visualize.md，什么时候明确跳过

visualize.md 并不是无条件加载的参考文件，它有严格的加载边界，而这一边界由构建路径（build path）决定：

• Comp 主导（comp-led）：当新表面（new surface）的构建以 comp 为法定基准，且具备图像生成能力（harness 原生的图像工具，或impeccable context报告的 API 回退能力）时，从 new-work.md 加载本文件，并完整执行 comp 轮次。
• 代码主导（code-led）：按设计契约跳过本文件——这是契约，不是漂移（drift）。code-led 的野心不体现在 comp 上，而是转移进方向契约（direction contract）的FIRST VIEWPORT块与具名签名交互中，由 finish reviewer 在行为层面审计。
• 前置条件：PRODUCT.md与DESIGN.md必须已经就绪（缺失PRODUCT.md时先走 init.md）。
• 禁止重新打开视觉世界：new-work 已经解决了视觉世界（visual world）的归属问题，本文件不得重新开启身份工作坊。

一个特殊的放电条款（discharge）值得注意：如果 surface 范围的架构轮次（surface-scope structure round）已经通过 new-work.md 第 3 节把三张已可视化的卡片放在用户面前，且用户锁定了某张卡片，那么该锁定卡片的 comp 就是已获批的 comp：记录批准并直接从 "After approval" 继续，不再生成任何新图。这避免了两次独立的审批点。

probe 是验证，不是第二次身份工作坊

comp 轮次的本质是方向验证（probe），它测试的是构图（composition）、叙事（narrative）、层级（hierarchy）、密度（density）、焦点时刻（focal moment）、签名使用（signature use）与图像需求（image requirements）——而不是重新讨论身份。因此 DESIGN.md 中已固定的调色板、字体方向、材料语言、组件性格、图像立场（imagery stance）与动效语法，在 comp 轮次中必须保持不动。

生成三张方向稿：从状态机约束到构图纪律

状态机前提：comps 阶段必须已经打开

comp 轮次运行在构建的阶段状态（phase state）之内。命令impeccable build-phase start --direction <seed key> --kind <...>必须先于首张 comp 执行——roll 的输出会给出确切的命令。其 Rust 实现位于 crates/comp-verbs/src/build_phase.rs，定义了八个阶段的显式序列：

pub const PHASES: [&str; 8] = ["comps", "spec", "plates", "hero", "sections", "motion", "responsive", "review"];

comps阶段在生成第一张 comp 前必须处于 open 状态：在 start 之前渲染的 comp 位于状态之外，会话从此处恢复时将无阶段可循；impeccable generate-image也会拒绝在.impeccable/mocks/下写入任何文件，直到 start 已运行。harness 原生图像工具同样受此顺序约束。

三张 comp 的产出规则

三张 comp 需符合以下硬性要求：

• 落盘位置：保存在.impeccable/mocks/下，以跨会话存活。
• 视口纪律：按表面自身的视口构图——原生 App 或移动优先表面用竖版（portrait，设备尺寸）；桌面端用横版（landscape）。把手机屏幕 comp 成横版，是在任何代码构建之前就错误陈述了构图。
• 不委托：comp 是构建线程自己的工作，绝不外包。撰写 prompt 的线程持有方向的完整上下文，并在构建开始时见过每一张 comp。
• 打开方式：一律使用工作区相对路径打开图片；沙箱化的查看器拒绝绝对路径，而项目根目录下的所有内容都有相对路径。
• 内容真实：基于真实内容以及已经与用户共同发展的表面概念。

既有世界（established world）的锚定：每张 comp 都必须锚定在真实身份上——截取一张有代表性的现有页面截图，作为参考图传入（harness 图像工具的 input image，或impeccable generate-image --ref）。prompt 以新表面的结构开头，而参考图承载调色板、字体与组件性格——因为 DESIGN.md 的文字转述会漂移，而像素参考不会。同时要明确参考图贡献什么、不贡献什么：

• 继承：chrome、调色板、字体、组件性格。
• 禁止：参考页面自身的内容；照搬 banner、hero 或卡片是参考图泄漏（reference leaking），不是保真。

为什么是"三"：决策 comp 机制

三张的数量有其设计理由：一张 comp 诱导橡皮图章式通过（rubber-stamping）；三张之间的差异（spread）才暴露值得构建的构图。具体机制是：

• 若本轮已有决策 comp（来自 direction 轮次），它必须是三张中的第一张——它已经在同一纪律下以全保真渲染了这个方向。此时只需再生成两张，在第一个已固定的维度上做变化，然后三张一起送到审批点。
• 只有在本轮根本没有决策 comp 时（降级 roll、身份模式页面、未经过决策轮就固定方向），才在这里完整渲染三张。

构图自检的六条纪律

visualize.md 对每一张 comp 都给出可执行的评判标准，每条失败都对应"重新生成"的指令：

1. comp 是设计的表面，不是主体的照片。prompt 必须以表面自身的结构开头：这个设计有哪些区域、按顺序命名、给出比例关系；没有导航的页面直接声明没有导航，而不是发明一个；非常规表面要陈述其非常规骨架。以氛围开头的 prompt 会得到一张氛围图——模型画的是鱼市，而不是鱼市的网站。每次渲染后自检：如果它能像海报一样挂起来，或者读起来像一张贴了文字的摄影图，它就不是 comp，请用更字面的布局骨架重新生成。

2. 反方向的失败同样成立：表面里完全没有主体。主体以区域所承载的内容形式出现；世界装饰画框，但绝不顶替画框所展示的内容。删除通常藏在 prompt 的排除列表（exclusion list）里——排除项约束的是发明的主张，媒介禁令属于已承诺的图像立场，绝不属于谨慎。接受渲染前，指着主体说得出它是谁；只描绘世界而主体缺席的渲染，无论氛围多忠实都是失败。

3. 以成品屏幕来评判：访客的任务必须仅凭图像就能读出来。不加说明地读出表面的模式；读不出模式的渲染只是没有表面的艺术指导。

4. 承诺是深度，不是覆盖面。世界通过一个主导动作（dominant move）加支撑它的材料、字体与间距进入；其余区域保持静止，让那个动作可读。检查削减的是竞争，不是内容：被安静下来的区域保留信息，只是停止表演。两个元素以相同尺度与命名的焦点时刻竞争，意味着 comp 在喊叫；没有命名的焦点时刻而多个区域同时表演概念，同样是喊叫。保留最强的动作、安静其余部分。"热闹不等于大胆。"

5. 用户短名单多个概念时，把三张分散到这些概念上；方向已承诺时，在图像能解决的结构不确定性上做变化：拓扑、序列、密度、层级、焦点构图或交互取景。

6. 展示足够超出开场时刻的内容，证明概念能统治整个表面；不生成调色板产物、不问新的氛围问题、不引入不同的字体声音、不发明新母题。如果已承诺的世界无法支撑概念，回到概念短名单，而不是改变世界。

每个 comp 的边界

每张 comp 都是方向测试，不是截图规格。核心 UI 文案、响应式行为、可访问性、语义和交互状态仍是实现责任。

唯一的审批点：如何呈现、如何等待、如何记录

呈现方式与提问

三张 comp 必须在决策页上一起展示（impeccable serve-question，每个 comp 一个选项、以 comp 作为 hero），或者仅在 harness 能内联渲染图像时用 harness 呈现——纯文本表面不算展示。提问必须覆盖：什么应该带向前、什么对世界来说是假的、选中的概念应该批准、合并、修订还是拒绝。然后停下并等待。结构化模拟用户（structured simulated user）也算已出席，收到同样的问题。

impeccable serve-question的 Rust 实现位于 crates/context/src/serve_question.rs，通过.impeccable/下的状态文件（<key>.state.json、<key>.answer.json、<key>.flip.json、<key>.next.json）管理心跳与答案回收，并以ANSWER: <json>的形式输出选择结果。

等待与委托

用户批准方向或明确委托选择之前，不得开始写代码。若用户委托，则依据任务简报、PRODUCT.md与DESIGN.md选择，并陈述证据。批准细化的是任务概念，不修改 DESIGN.md。

该审批点没有替代品、没有跳过条件：

• 结构化问题工具出错时，回退到决策页；
• 只有两者都失败，才可以把选择视为委托；
• 委托的选择与批准完全一致地记录，并在第一条回复中披露（不是最后一条）。

finish reviewer 会把 comp 轮次产出但无批准记录的 comp 视为实质发现（material finding）；.impeccable/mocks/decision/下的决策 comp 是 direction 轮次的手笔，不是 comp 轮次的产出，本身不暗示任何批准。

批准后的记录机制

批准之后，选择必须记录在工具能找到的地方：

1. surface brief：获批 comp 的路径写入 surface brief（impeccable surface-brief read <primary-target>/impeccable surface-brief write <primary-target> <body-file> [related-target ...]，见 new-work.md 第 5 节）。
2. prompt sidecar：获批 comp 的.jsonsidecar 增加"approved": true。凡经impeccable generate-image生成的 comp 都有 sidecar；native 工具生成的若没有，需要创建。

sidecar 与 mocks 目录一起迁移，因此批准状态能跨会话、跨机器存活，即使那台机器从未见过 brief。它也正是impeccable build-phase advance读取以关闭 comps 阶段的依据。从源码看，crates/comp-verbs/src/build_phase.rs 的gate_comps会扫描.impeccable/mocks/下的图像，校验三张 comp 齐备、每张都有携带 prompt 的 sidecar、恰好一张带"approved": true，任何一条不满足都会让 gate 失败并打印原因。

批准后：总结构图与不得被字面化的部分，回到 new-work.md，从获批概念记录方向契约，然后开始构建。

审批之后：comp 变成规格

转译，而不是重新构图

获批的 comp 是翻译成语义化、响应式、可访问代码的北极星，绝不是重新构图的许可：保持调色板与氛围而重画拓扑，是第二次艺术指导。不得把核心 UI 文本或控件栅格化；未经询问不得在批准后替换不同的视觉驱动者。

comp 显示什么，就测量什么

new-work.md 第 6 节把构建作为阶段运行（impeccable build-phase）：

• spec 阶段把 comp 变成区域框与采样调色板（impeccable comp-spec，先--comp <comp> --grid写坐标网格、命名区域，再--regions <file>提交；--print是此后的构建参考）；
• 每个区域的媒介（medium）由像素决定，而非由"什么好构建"决定：
  • 图（figure）、产品对象、机械、任何含透视/阴影/绘画技巧的插画，以及任何具名纹理（织物、纸纹、皮革、拉丝金属）→plate/image/texture区域，以栅格形式交付；
  • 文本、控件、chrome、可数元素的图示、扁平形状系统、任何需要移动/缩放/响应的东西 → 语义代码。

静默删除的三种形态：为雕花面板的饰面写 CSS、为撕裂边缘写多顶点clip-path，都是对已批准设计的静默删除——检测器的organic-clip-path与buried-raster规则（定义于 crates/foundation/src/registry.rs）以及 hero 门的区域得分会抓住它。具体地：

• organic-clip-path（quality）："用多任意顶点的 clip-path 多边形或曲线 path() 近似撕裂边缘、blob 或剪影，是效果的廉价版本"；应从真实图像派生 alpha 蒙版或直接交付剪影栅格，clip-path 只留给几何（切角、对角线、六边形）。
• buried-raster（quality）："背景图被近乎不透明的渐变 wash 覆盖，或栅格以近零透明度存在，永远到不了屏幕"——生产的纹理或照片沦为合规标记。

删除一个图像原生（image-native）区域，是用户在审批点做出的范围决策，绝不是审批后的静默扁平化。另外，生成的图像是材料而非主张：证据规则约束断言、规格、证言与以真实呈现的照片，但绝不约束渲染保真度。

Plates 与 provenance：每个栅格的出身证明

plates 阶段的产出方式

每个栅格区域的 plate 在plates 阶段、任何页面代码之前产出，两种途径：

1. 交付的资产生产者（shipped asset producer，impeccable-asset-producer）；
2. 当前线程直接生成：impeccable generate-image --plate <id>，或 harness 图像工具以 comp 裁剪（impeccable comp-spec --crop <id>）为输入图、以 spec 的 plate prompt（impeccable comp-spec --plate-prompt <id>）为 prompt。

plates 门的检查从源码（crates/comp-verbs/src/build_phase.rs 的gate_plates）可见：每个 plate 必须存在、至少是区域尺寸的 1.5 倍宽、与区域读起来一致；区域得分低于 40% 或结构与 comp 区域不一致会失败；comp 区域的再采样（resample）永远不能充当 plate（"a crop of the comp is never a plate"），plate 必须以裁剪为参考重新生成。

embed-prompt：生成上下文是资产的一部分

用任何工具生成任何图像之后，立即运行：

.hermes/skills/impeccable/scripts/impeccable embed-prompt <image> --prompt "<prompt>"

prompt 必须是工具实际收到的精确字符串（impeccable generate-image自动完成这一步）。这样意图就活在文件内部：

• --read恢复已嵌入的 prompt；
• --scan <dir>列出仍然缺失 prompt 的栅格。

其 Rust 实现位于 crates/context/src/embed_prompt.rs：prompt 以 PNGtEXt块（keyword 与 prompt 文本）写入文件，EMBEDDED: <file> (png tEXt, <len> chars)输出确认；读取与扫描模式分别解析这些块并报告。

Provenance 的定义：嵌入的 prompt 加上 spec 中该区域的所在行，就是栅格的 provenance——artifact 引用的每个栅格都必须携带它。采源、库存或既有栅格改嵌入其出处（origin）而非 prompt。之后在修复批次或 reviewer 重建中创建或替换的栅格，以同样方式产出；修复放弃的栅格在同一批次中删除。

图像转换器

用impeccable context在启动时报告的转换器（IMAGE_TOOLS行）转换图像；只有当它报告没有转换器时才 probe——每会话至多一次，绝不要逐图 probe。

命令速查与目录约定

回到 new-work：构建与收尾

comp 轮次结束后，返回 new-work.md 获取方向契约、分阶段构建（spec → plates → hero → sections → motion → responsive）与收尾检查（finishing pass）。其中 hero 门以 72% 为总通过线、responsive 门以 65% 为线，且 comps 门对三张 comp 的 sidecar 与"approved": true标记做强制校验——这些阈值与阶段定义都编码在 crates/comp-verbs/src/build_phase.rs 的常量中：

const HERO_MIN: f64 = 0.72; const RESPONSIVE_MIN: f64 = 0.65;

从 comp 的三选一审批，到像素级测量、plate 生产与 prompt 溯源，整个管线保证了：已批准的构图以测量过的数字进入代码，而不是以模糊的记忆——这正是 Impeccable 让 AI 构建出的页面真正忠于设计方向的底层机制。

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