Impeccable 方向构图轮次Comp Round从三选一审批到资产溯源的可视化构建工作流【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable导读本文讲解 Impeccable 项目中visualize.md定义的方向构图comp工作流——当构建是 comp-led以构图为先导且图像生成可用时如何产出三张高保真方向构图、通过唯一的审批点锁定方向并在审批后把已批准的构图量化为可执行的构建规范spec最终为每个栅格区域plate生成资产并写入可审计的溯源provenance。读完本文你将掌握impeccable build-phase、generate-image、comp-spec、embed-prompt、serve-question等命令在这一工作流中的完整调用关系与纪律约束。一、这份文档在什么时候被加载visualize.md不是一个随时都要执行的流程它的加载有严格的前置条件。从文档开头可以看出它只出现在两条路径都满足的时刻构建是comp-led以构图驱动的new-work.md中记录了buildPath默认值来自.impeccable/config.json或config.local.json前者被 gitignore 且在本机有更高优先级当图像生成存在时默认即为 comp-led图像生成可用要么是 harness 自带的图像工具要么是 API 回退方案impeccable context所报告的。反之code-led 契约会按设计跳过这份文档文档原文是 skipped by design, not by drift。不要因为看起来像是漂移而错误加载它。同时PRODUCT.md与DESIGN.md是前置条件视觉世界已经在new-work.md阶段解决这份文档不得重新打开视觉世界的问题——它不是一个第二次身份工作坊。还有一个特殊的已清偿discharged情况如果new-work.md的 surface-scope 结构轮次已经把三张可视化卡片放到了用户面前即已确立世界下的决策构图轮那么这一轮已经完成——被锁定的卡片的构图就是已批准的构图此时直接记录审批并跳到 After approval 阶段不再生成任何新内容。探测而非重新设计文档明确指出这一轮是一个探测probe它检验的是构图、叙事、层级、密度、焦点时刻、标志性用法与图像需求而不是再来一次身份identity工作坊。DESIGN.md中已经确定的调色板、排版方向、材质语言、组件性格、图像立场与动效语法都必须保持不变。二、生成三个构图选项阶段状态与生成纪律2.1 构图必须运行在 build-phase 状态机之内构图轮次发生在构建的相位状态里。文档强调impeccable build-phase start --direction seed key --kind ...必须先运行roll 的输出会指名具体命令且其comps阶段在生成第一张构图之前就已经打开。从源码实现看build-phase是一个跑在磁盘上的状态机。在 build_phase.rs 中定义了完整的相位序列pub const PHASES: [str; 8] [comps, spec, plates, hero, sections, motion, responsive, review];new_statebuild_phase.rs在start时把第一个相位置为open、其余置为pending状态写入.impeccable/build/state.json。如果通过start --comp approved comp启动surface 轮已锁定构图comps相位会被标记为skipped并记录原因注释。为什么必须在状态机内生成文档给了一个关键理由在start之前渲染的构图不在状态内从该点恢复的会话没有可跟随的相位。同时impeccable generate-image会拒绝在start运行之前向.impeccable/mocks/写入任何内容harness 自带的图像工具同样受此顺序约束。这保证每一张构图都归属于某个可审计的构建会话。2.2 三张构图的产出要求核心要求可以拆解为以下几条渲染三张彼此不同、高保真的 north-star 构图保存到.impeccable/mocks/下这样它们能在会话结束后存活。构图是构建线程自己的工作绝不能委托出去写提示词prompt的线程持有方向的完整上下文并且在构建开始时已经见过每一张构图。以表面自身的视口来构图原生 App 或移动优先的表面用设备尺寸的竖版portrait桌面 Web 用横版landscape。文档的原话是一张手机屏幕却以横版构图会在任何代码构建之前就错误陈述misstate这个构图。用相对路径打开每一张图片沙箱化的查看器会拒绝绝对路径而项目根目录下的一切都有相对路径。基于真实内容与已和用户开发的表面概念来构图。三这个数字本身是纪律一张构图会诱导橡皮图章式的点头rubber-stamping三张之间的差异才能暴露值得构建的构图。三张之间的铺开spread正是价值所在。comps阶段的门禁gate在 build_phase.rs 中实现gate_comps检查.impeccable/mocks/下是否有至少 3 张PNG/WebP/JPG 构图、每张是否有携带 prompt 的.jsonsidecar{ prompt: ... }、以及是否恰好一张被标记为approved: true。任何一项不满足都会以非零退出码拒绝推进。2.3 已确立世界用像素参考锚定真实身份在已确立世界established world上每张构图都必须锚定在真实身份上截取一张有代表性的现有页面的截图作为参考图像传入harness 图像工具的 input image或impeccable generate-image --ref。提示词以新表面的结构为先导而参考图承担调色板、字体与组件性格——因为DESIGN.md的文字转述会漂移而像素参考不会。文档对参考图贡献什么、不贡献什么做了明确划分应该继承chrome界面骨架、调色板、字体、组件性格绝不能继承参考页面自身的内容——一张被原样搬来的 banner、hero 或卡片是参考图泄漏the reference leaking而不是保真。2.4 三张中有一张是决策构图当方向轮已经产生了决策构图.impeccable/mocks/decision/下的那张它天然就是第一张它已经在这一纪律下以全保真度渲染了该方向。因此本轮只需再生成两张——对第一张已固定的变量做变化——然后把三张一起送到审批点。只有两种降级到达degraded arrival情况需要在这里渲染全部三张降级的 rolldegraded roll没有 challenger身份模式的页面identity-mode page方向被固定但没有经过决策轮a direction pinned without the decision round。2.5 构图纪律六条自检规则文档用相当紧凑的篇幅给出了六条构图评审标准这里逐条展开1. 构图是设计过的表面不是主题的照片。提示词必须以表面自身的结构为先导本设计的各个区域、按顺序命名、并给出它们之间的尺度关系。没有导航的页面要直接说没有导航而不是发明一个非常规的表面要说明它非常规的骨架。以氛围为先导的提示词得到的是一张氛围图vignette——模型会画出鱼市而不是鱼市的网站。自检方法如果这张图能当海报挂起来或者读起来像加了些文字的摄影作品那它就不是构图需要用更字面的布局脚手架layout scaffold重新生成。2. 反面同样是失败表面里没有任何主题内容。主题以区域所承载的内容出现世界world负责装扮画框但永远不能取代画框所展示的东西。这种删除通常搭着提示词的排除列表exclusion list混进来所以排除列表要用来约束虚构的主张invented claims而对某类媒介的禁令属于已承诺的影像立场imagery stance不属于谨慎。接受一张渲染前先指向主题一张描绘了世界的一切却与主题无关的渲染无论氛围多忠实都是失败。解决办法把主题的内容按区域逐一命名重新生成。3. 把构图当作上线后的屏幕来评判。访客的任务必须仅凭图像本身就能读出来。不看任何说明文字就能说出这张渲染是什么模式persuade/operate/read/experience——说不出来的渲染只是没有表面的艺术指导art direction without a surface。此时以访客的任务作为提示词的脊梁spine重新生成。4. 承诺是深度不是覆盖Commitment is depth, not coverage。世界通过一个主导动作one dominant move加上支撑它的材质、字体与间距进入其余区域保持静止好让那个动作能被读出来。一个只是在自己的语法里完成本职工作的区域比一个在表演概念的 区域更能承载方向。检查会削减竞争competition而不是削减内容被安静下来的区域保留信息、停止表演。如果第二个元素以同样的尺度与命名的焦点时刻竞争构图就是在喊叫shouting没有命名焦点时刻时多个区域同时表演概念同样是喊叫。保持最强的动作安静其余。文档有一句非常精辟的总结Busy is louder, not bolder嘈杂只是更大声不是更大胆。5. 当用户筛选了多个概念时把三张铺开覆盖它们。6. 当一个方向已承诺时变化图像能够解决的结构不确定性拓扑topology、序列sequence、密度、层级、焦点构图focal composition或交互框定interaction framing。7. 展示的必须超出开场瞬间opening moment足以证明这个概念能统摄整个表面。8. 禁止项不生成调色板产物、不问新的氛围问题、不引入不同的字体声音、不发明新的母题motif。如果已承诺的世界无法支撑这个概念回到概念短名单concept shortlist而不是改变世界。最后提醒每张构图都是方向测试不是截图规格。核心 UI 文本、响应式行为、可访问性、语义与交互状态始终是实现阶段的责任构图阶段不承担。三、唯一的审批点3.1 展示方式与问题三张构图必须一起呈现在决策页上impeccable serve-question每个构图一个选项构图作为该选项的 hero 图或者仅当 harness 能内联渲染图片时才在 harness 内展示。纯文本的表面不算展示。向用户提出的问题固定为三个什么应该被带向前carry forward什么对这个世界来说显得虚假feels false to the world选中的概念应该被批准approved、合并combined、修订revised还是拒绝rejected然后停下等待。一个结构化的模拟用户structured simulated user同样算作已出席并收到同样的问题。从实现看serve-question是一个可守护进程化的决策服务serve_question.rs它以--start启动后打印页面 URL 与 key 并退出--wait --key key收集答案ANSWER:以 JSON 输出。3.2 委托与降级路径在用户批准方向或明确委托选择之前不要开始写代码。如果用户委托了选择依据任务简报、PRODUCT.md和DESIGN.md来决定并陈述证据。审批细化的是任务概念它不修改 DESIGN.md。这个审批点没有替代品、没有跳过条件当结构化问题工具报错时回退到决策页只有两者都失败时才可以把选择视为已委托委托的选择与批准一样被记录并在你的第一条回复中披露而不是最后一条。finish-reviewer会把构图轮产出但无记录的批准视为实质性发现material finding。注意区分.impeccable/mocks/decision/下的决策构图是方向轮的产物不是构图轮的输出它们本身不暗示任何批准。3.3 审批后把选择记录到工具能找到的地方审批之后必须留下工具可读的记录共两步被批准构图的路径写入 surface brief其.jsonprompt sidecar 获得approved: true。每一张通过impeccable generate-image生成的构图都有这个 sidecarnative 工具没有的话要手动创建。为什么 sidecar 是关键因为sidecar 随 mocks 目录一起走审批因此在从未见过 brief 的会话和机器上也能存活——impeccable build-phase advance读取的正是这个标记来关闭 comps 阶段。这也与gate_comps的逻辑完全一致它要求恰好一个 comp 带approved: true多一个少一个都会拒绝。之后概括构图与不得被字面化literalized的部分回到new-work.md从已批准的概念记录方向契约direction contract然后开始构建。四、审批之后构图变成规范spec被批准的构图是翻译成语义化、响应式、可访问代码的北极星north star绝不是重新构图的许可。文档给出两条硬约束保持调色板与氛围的同时重画拓扑是第二次艺术指导——禁止不得栅格化rasterize核心 UI 文本或控件审批后不得未经询问替换视觉驱动visual driver。4.1 构图是被测量的不是被记住的new-work.md第 6 节将构建作为相位运行spec 阶段把构图变成区域框与采样调色板impeccable comp-spec。从 comp_spec.rs 的实现看流程是impeccable comp-spec --comp comp --grid在构图上叠加一个10×10 坐标网格render_gridcomp_spec.rs左上角 A0、右下角 J9并打印 PALETTE 与 BANDS打开网格图在 regions 文件里按网格跨度grid span命名每个显著区域然后impeccable comp-spec --comp comp --regions file测量生成.impeccable/build/spec.jsonimpeccable comp-spec --print从此是构建的参考。每个区域携带box相对坐标、px像素坐标、采样调色板、medium与note。spec 的用途是一切不在 spec 里的东西在页面上都不存在——没有构图未显示的边框、规则、容器或 chrome。文档只允许三个例外字体最近可得的字面、图标字形足够接近即可、以及构图中的真实缺陷如拼写错误。4.2 介质分类像素是什么就按什么交付每个区域的介质medium由像素本身决定而不是由什么感觉好构建决定区域内容medium交付方式图形、产品对象、机械、任何带透视/阴影/绘画技巧的插画plate/image栅格资产raster按名字提到的任何纹理织物、纸纹、皮革、拉丝金属texture栅格资产raster文本、控件、chrome、可数元素的图表、扁平形状系统、任何需要移动/缩放/响应的东西语义化semantic代码把雕刻面板的饰面写成 CSS、或为一个撕裂边缘写一个多顶点的clip-path都是对已批准设计的安静删除——设计系统检测器的organic-clip-path与buried-raster规则以及 hero 门禁的区域得分会抓住这类行为。删除一个图像原生image-native区域是用户在审批点做的范围决策绝不是在审批后默默扁平化。文档还特别强调生成的图像是一种材质material不是一种主张claim——证据规则约束的是被当作真实的断言、规格、证词与照片从不约束渲染保真度。五、Plates 与溯源provenance5.1 生产流程每个栅格区域的 plate 在plates 相位、任何页面代码之前产出由随附的资产生产者shipped asset producer或当前线程完成先用impeccable comp-spec --crop id写出参考裁切reference crop把impeccable comp-spec --plate-prompt id的输出保存为 prompt 文件把裁切与 prompt 交给 harness 图像工具或使用 API 回退命令impeccable generate-image --ref crop.png --prompt-file prompt.txt \ --out plate.png --size WxH --quality high从 generate_image.rs 的实现看--ref走 multipart 的/images/edits接口reference edit无--ref走/images/generations--size默认1536x1024--quality默认medium--model默认gpt-image-2.5-flaregenerate_image.rs。生成成功后它会自动写入两样东西在图片文件内嵌入 prompt调用 embed-prompt 逻辑写出out.jsonsidecar含 prompt、createdAt、tool、model、refs 等。透明与不透明隔离的剪影cutout要在 plate-prompt 与 API 生成命令上都加--background transparent——使用原生 PNG alpha保留白色油漆与清晰的空隙全幅图像用--background opaque。先创建输出目录再在浅色与深色底上检查 alpha。--background只接受transparent、opaque、auto三个值且要求输出路径是.png否则命令直接报错见 generate_image.rs。5.2 嵌入 prompt让意图活在文件里生成上下文本身就是资产的一部分。无论用什么工具生成图像都要运行.trae-cn/skills/impeccable/scripts/impeccable embed-prompt image --prompt prompt并且 prompt 必须是工具实际收到的原样字符串impeccable generate-image会自动完成这一步。从 embed_prompt.rs 的实现看PNG 以tEXt块写入关键字impeccable:prompt重复嵌入会幂等地替换旧块JPEG 以 COM 段写入其他格式回退到.jsonsidecar。配套的读取与扫描--read恢复被嵌入的 promptPNG/JPEG 内嵌优先sidecar 兜底--scan dir列出仍然缺少 prompt 的栅格资产退出码 3 表示有缺失。内嵌 prompt spec 中该区域的行 栅格的溯源provenance被 artifact 引用的每个栅格都必须携带它。来源明确的、图库的或既存的栅格嵌入的是它的来源origin而不是 prompt。在修复批次fix batch或 reviewer 重建中产生或替换的栅格必须以同样的方式生产被放弃的栅格在同一批次中删除。5.3 图像转换器使用impeccable context在启动时报告的转换器IMAGE_TOOLS 行来转换图像只有当它报告没有转换器时才探测probe每会话至多一次绝不逐图探测。5.4 门禁如何验证 platesplates 门禁gate_platesbuild_phase.rs逐区检查每个 raster 区域都有 plate 文件且是可解码的 PNGplate 至少是区域尺寸的 1.5 倍宽min_w min(1536, px_w * 1.5)——低于此会被拒绝a shipping plate needs at least Npx. Regenerate at asset size, do not crop the compplate 与构图的区域参考做结构/颜色/细节对比打分阈值 PLATE_MIN 0.4、PLATE_STRUCTURE_MIN 0.4打分逻辑在 comp_diff.rs 中按区域类型有不同的权重纹理区域texture按 50% 颜色 50% 细节的有效分评估要求至少 0.4构图裁切comp crop永远不是 plate如果 plate 与原区域像素的结构相似度 ≥ 0.95structure_score会被判定为comp 的重新采样而拒绝如果构图区域平静energy 12而 plate 增加了超过 45% 的细节也会被拒绝噪声/纹理噪点被看作不该有的添加。comp_diff的 parity 测试parity.rs确认这套打分与原始 JS 实现逐字节一致例如comp.png对build_flat.png的 overall 分 0.8374、verdict 为match。5.5 hero 门禁的承接在 plates 之后hero 门禁把 spec 中测量到的数字变成 CSS custom properties 与参考页impeccable build-phase scaffold生成.impeccable/build/scaffold/layout.css的--r-id-x/y/w/h与hero-reference.html然后只构建首屏comp-diff以72%总分为及格线HERO_MIN 0.72build_phase.rs并把每个文本区域的 cap height、行数、字重、墨色与位置、每个 chrome 条的规则高度、以及构图平静处冒出的墨迹逐一以数字形式报告——那些数字就是编辑指令those numbers are the edit。六、返回 new-work方向契约与收尾构图轮在审批与 plates 溯源之后结束。文档最后回到 new-work.md——方向契约、分阶段构建与收尾finishing pass都在那里继续。构图的地位在 new-work.md 中也被反复强化comp-led 构建下构图是测量过的契约只有用户能用明确的言辞降低它的权威构建以磁盘上的状态机运行门禁用屏幕对照构图做测量而不是让你凭记忆finish review 以comp-diff --comp approved comp --build .impeccable/review/desktop.png --spec .impeccable/build/spec.json --out-dir .impeccable/review/diff/final作为最终保真度证据在代码含 HTML 注释、data-*属性、序列化 props 等一切浏览器可达的产物中绝不复制方向契约——它只存在于 surface brief。七、关键命令速查命令作用关键参数impeccable build-phase start --direction seed key --kind ...打开 comps 阶段启动磁盘状态机--comp approved comp可跳过 comps 相位impeccable generate-imageAPI 回退图像生成--ref png、--prompt-file、--out、--size WxH、--quality high、--background transparent/opaque、--modelimpeccable serve-question决策页三选一审批点--start/--wait --key key/--schema/--updateimpeccable comp-spec把构图测量为 spec--grid、--regions json、--print、--crop id、--plate-prompt id、--backgroundimpeccable build-phase advance推进到下一相位exit 2 表示门禁失败record hero、scaffold等子动作impeccable embed-prompt嵌入/恢复/扫描 prompt 溯源--prompt ...、--read、--scan dirimpeccable context启动时报导能力IMAGE_TOOLS、图像生成可用性—所有命令都以.trae-cn/skills/impeccable/scripts/impeccable或 npm 安装后的impeccable为前缀调用。需要说明的适用前提是本工作流仅在 comp-led 构建路径且图像生成可用时启用code-led 契约按设计跳过构图轮其雄心转移到方向契约的 FIRST VIEWPORT 块与命名的标志性交互中由 finish reviewer 在行为层面审计。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考