impeccable polish 实战指南发布前的设计系统对齐与最终质量打磨【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable导读/impeccable polish是 Impeccable 设计技能skill中面向「发布前收尾」的细化命令用于在功能完整的前提下对一条真实用户路径做系统化打磨对齐设计系统、修复漂移、补齐状态、清理代码并最终将本轮处理的 critique 快照闭环。本指南以 Impeccable 仓库内的 polish 参考文档 为骨架结合 critique_storage.rs、SKILL.md、craft-floor.md 等源码与配套参考完整讲解 polish 的五步流程、critique-storage 命令的用法与底层原理以及「细化而非重设计」的边界纪律。读完你可以在自己的前端项目上独立执行一轮合规的 polish 通过pass。一、polish 的定位与核心原则在 Impeccable 的 23 个命令中polish属于Refine细化类别与bolder放大、quieter收敛、distill精简、harden生产就绪并列。命令元数据 command-metadata.json 和 SKILL.md 对它的定位是「final quality pass before shipping」发布前的最终质量通过。README.md 中则将其描述为「final pass, design system alignment, and shipping readiness」。运行前polish 参考文档要求你明确一句附加上下文Additional context needed: quality bar and shipping constraints.需要补充上下文质量门槛与交付约束。两条不可动摇的核心原则Polish 是 refinement绝不是隐藏的重设计。必须保留既有的视觉世界、内容、行为和范围外的一切。如果概念本身错了应当明确说出来并建议重设计redesign或bolder而不是偷偷塞进一个替代方案。检测器detector的结果是缺陷证据不是质量证明。检测通过 ≠ 体验合格。必须亲自检查渲染出的真实体验与真实交互路径。这也与 SKILL.md 中「Refinement preserves; redesign replaces」细化保留重设计替换的总原则完全一致细化保留既有身份、行为、文案和范围外的一切重设计则保留产品事实、内容、功能、原生能力和约束但把旧外观当作证据与反参考。永远不要把差异拆成「对废弃外观的打磨」。二、Step 1建立系统Establish the system在动手修复任何漂移之前先建立「系统」这个参照系阅读DESIGN.md以及有代表性的 token、共享组件、模式与相邻流程如果项目里不存在正式的设计系统则采用连贯的项目约定coherent project conventions。关于读取机制可以从源码印证load_context见 crates/context/src/context.rs会解析PRODUCT.md/DESIGN.md大小写变体Product.md/product.md/Design.md/design.md均被识别并在 monorepo 场景下沿pnpm-workspace.yaml、turbo.json、nx.json、lerna.json等标记向上定位项目根。DESIGN.md的实际形态可以参考仓库根目录的 DESIGN.md——它是一份带 frontmatter 的可移植 token 导出如kinpaku-gold: oklch(84% 0.19 80.46)并有明确的单一事实来源约定“All values below mirror site/styles/kinpaku-tokens.css verbatim”。建立系统后对每一处漂移drift先分类再决定修法漂移类型含义正确修法missing token缺 token系统需要一个可复用的值把它提升为设计 tokenone-off implementation一次性实现本应复用某个共享组件或模式用共享组件/模式替换conceptual mismatch概念错位流程、信息架构或层级与同类产品区域不一致修正概念层面local defect局部缺陷实现本身不完整或不一致就地补齐修复原则是在最窄的正确层级修复根因。当无法从现有材料推断某个有约束力的系统原则时应当提问而不是擅自假设。三、Step 2收集证据Gather the evidence打磨不是对着截图工作。polish 要求你「自己用一遍这个功能」覆盖表面的代表性尺寸Web 端桌面 移动原生平台ios/android/adaptive模拟器、仿真器或真机上的实际出货设备类别按平台参考文档的 “Verifying the build” 一节采集证据。要确定四件事路径是否功能完整预期的质量门槛与可用时间已知约束或刻意未完成的工作用户实际会遇到的状态、内容长度、角色与输入方式。3.1 利用既有 critique 快照如果此前存在 critique把它作为一个输入而不是唯一输入。核心命令.gemini/skills/impeccable/scripts/impeccable critique-storage latest resolved target --json退出码语义Exit 0返回 JSON包含最新快照的body和精确的snapshot_file标识。snapshot_file必须一直保留到本轮 pass 结束。Exit 2不存在快照或目标已变更。无论哪种情况都必须独立执行一遍完整打磨。本地文件目标的新鲜度校验这是源码级事实见 crates/context/src/critique_storage.rslatest子命令会对本地文件计算当前内容的精确指纹sha256:前缀 SHA-256 摘要与 critique 记录在快照 frontmatter 中的target_fingerprint比对。任何字节变化、删除、或替换为非文件的操作都会关闭该快照对应的 backlog保留其趋势历史并以 exit 2 返回。URL 目标没有本地指纹因此会一直保持「当前」状态直到被显式关闭。当快照仍然有效当前时吸收body中相关的 P0/P1 发现并在打磨中指明你读的是哪一份快照。四、Step 3分类处理Triage把功能缺陷与外观问题分开按以下顺序修复损坏或被阻塞的任务、数据丢失、误导性状态、不可达的路径缺失的 loading、empty、error、success、disabled、permission 状态流程、层级、响应式与设计系统漂移视觉与动效不一致代码与资源清理。一个容易被忽略的纪律是不要只把一个角落打磨完美却让其余部分低于同一质量门槛。打磨是全程一致的收尾不是局部炫技。五、Step 4打磨整条路径Polish the whole path这是 polish 的核心实操章节覆盖五个维度。5.1 流程与层级Flow and hierarchy对齐相邻区域的思维模型、术语、信息揭露方式disclosure、路由、保存行为、乐观/悲观更新模式让主任务与当前状态显而易见但不要把每个元素都压平成同等的视觉权重确保到达arrival、过渡transition、空态empty、恢复recovery路径彼此连通而不是像孤立的屏幕。5.2 布局与排版Layout and type对齐项目的网格与间距刻度既修数学对齐也修视觉光学对齐相关内容紧密分组不同组之间慷慨留白同角色排版保持一致测试 measure行长、换行、本地化扩展、缩放与字体加载验证每一个受支持的视口而不是只修正当前这张截图。5.3 颜色、图片与图标Color, imagery, and icons使用语义化 token跨主题保持颜色含义稳定验证每一种状态下的文本、控件与焦点对比度保持图标家族、描边/字重、尺寸与光学对齐的连贯防止图片布局偏移layout shift使用正确的宽高比、响应式资源、有意义的 alt 文本。5.4 交互与状态Interaction and state每个控件都需要合适的 default、hover、focus、active、disabled、loading、error、success 行为保留可见的键盘焦点、逻辑 Tab 顺序、标签以及符合平台习惯的触控目标尺寸动效要连贯、可中断、高性能不要为了「让打磨可见」而添加动画在产品可能遇到的情况下验证长内容、缺失内容、本地化、离线、慢速与权限受限内容。5.5 内容与代码Content and code保持术语、大小写、标点与事实性文案一致改动事实性表述前先征询确认移除调试输出、死代码、未使用的 import、过时样式以及打磨过程中产生的重复凡是系统拥有该模式的用共享组件替换自定义实现把真正可复用的值提升为 token不要为单点例外制造一个系统级抽象。六、Step 5验证与收尾Verify and finish6.1 全路径复走用鼠标、键盘、触控如适用把完整路径再走一遍检查Web移动、中等、宽版布局原生两种支持方向下的手机与平板尺寸类别loading、empty、error、success、disabled、长内容、缺失内容状态缩放、对比度、焦点、语义与读屏器名称控制台错误、布局偏移、交互延迟与各处的图片加载Web 覆盖受支持的浏览器原生覆盖受支持的 OS 版本、运行时警告与掉帧与DESIGN.md、相邻功能以及用户明确的范围保持一致。6.2 借力自动检测器与上下文遵循impeccable context和 hooks 提供的质量指引再运行其他相关 QA 命令context 只会在没有自动检测器激活时请求一次手动扫描绝不要追加额外的检测器 pass修复真实缺陷只为极窄的、刻意的例外做文档化豁免干净的扫描结果不能替代视觉判断再次呼应开篇原则。关于检测器你还可以知道设计检测器 hook见 reference/hooks.md会在.tsx/.jsx/.html/.vue/.svelte/.astro/.css/.scss/.sass/.less/.ts/.js等设计相关文件被编辑后自动运行机械层规则broken images、溢出/裁剪、对比度与可读性、渐变文字、辉光阴影、设计系统漂移等Stop事件上还会跑全量规则集的深度 pass。无 hook 的会话会收到MANUAL_DETECTOR_REQUIRED指令要求收尾时执行一次扫描。6.3 源码差异收尾以源码 diff 收尾移除意外改动churn、孤儿代码、冗余值与临时产物。只有当功能在整条路径上功能完整且一致地完成时才允许发布。6.4 关闭快照close当本轮 pass 清除了从快照中接手的每一个 Priority Issue 时关闭该快照.gemini/skills/impeccable/scripts/impeccable critique-storage close resolved target snapshot_file returned by latest关闭纪律与源码实现严格对应只关闭本轮实际处理的那一份快照如果期间落入了更新的 critique其 backlog 仍然保持活跃没有读取快照、没有保留snapshot_file、或仍有 Priority Issue 未清时不得关闭。七、源码级原理critique-storage 是如何工作的polish 与 critique 之间的状态衔接全部由critique-storage子命令实现源码位于 crates/context/src/critique_storage.rs。几个值得展开的实现事实快照的落盘形态。快照文件写入项目根的.impeccable/critique/目录由get_critique_dir拼出resolve_project_root(cwd) .impeccable/critique命名形如2026-05-12T18-30-00Z__slug.md文件名以now_filename_stamp生成的 UTC 时间戳打头冒号与点替换为-__之后是目标 slug。同秒冲突时使用定宽~0001~9999后缀create_new(true)独占创建保证同一 UTC 秒内的第二次 critique 不会覆盖历史——这一点有明确的单元测试snapshot_name_accepts_collision_suffix佐证。目标身份target identity。本地文件被解析为file:绝对路径URL 被解析为url:originpathname去尾部斜杠避免latest/close时误配。测试target_identity_file_url_and_trailing_slash验证了三种形态。指纹与新鲜度。对本地文件计算sha256:hex内容指纹并写入 frontmatter 的target_fingerprintlatest时重新计算当前文件指纹并做严格字符串比较不等则自动关闭快照保留趋势历史并返回 exit 2——这正是 polish 参考文档中「任何字节变更都会使旧 backlog 关闭」的底层实现。closed 标记。close子命令在快照 frontmatter 中插入closed: trueinsert_closed_flag只有带 frontmatter 的快照才可关闭否则报错。关闭过的快照在latest中不再返回exit 2二次 close 是静默 no-op。close_verb_round_trip_and_ownership测试完整验证了「错误目标被拒、正确目标关闭、二次关闭为 no-op」的闭环。close 的归属校验。现代快照要求传入的snapshot_file与解析后的目标身份精确匹配且文件名必须通过is_snapshot_name的命名格式校验、位于 critique 目录内slug 文件名不足以证明归属。这是防误关的关键安全边界。趋势trend。trend target [limit]默认 limit 5返回最近 N 条 frontmatter 的 JSON 数组供 critique 结束后展示分数趋势。八、把 polish 放进整个工作流8.1 与impeccable context的关系每会话一次先运行.gemini/skills/impeccable/scripts/impeccable contextWindows 无sh的 shell 用.cmd版本。它加载PRODUCT.md、DESIGN.md、匹配的 surface brief 与原生平台指引polish 必须遵循其指令且不要重跑。launcher 不可用时的降级路径是直接读取现有 PRODUCT.md/DESIGN.md 继续但不得虚构缺失的上下文。8.2 与 critique 的接力critique.md 明确规定critique 的持久化产物含启发式评分表、P0–P3 优先级问题写入.impeccable/critique/正是为了让/impeccable polish无需复制粘贴就能接手这些 Priority Issues。polish 读取 → 修复 → 关闭形成闭环趋势线如24 → 28 → 32则记录同一目标随轮次改善的轨迹。8.3 与 craft-floor 的互补craft-floor.md 承载「任何扫描器都抓不到」的反射与质量底线对比度 ≥4.5:1 / 大文本 ≥3:1、正文字宽 65–75ch、display 最大 6rem、tracking 下限 -0.04em、动效一次一个作者时刻、浏览器原生表面也要被主题化等。SKILL.md 要求在任何 UI 编辑包括小优化之前先读 craft-floor——polish 作为发布前收尾正是这套「地板」的最终检验场。而检测器 hook 的机械规则与 craft-floor 的手感规则分工明确hook 覆盖可中断编辑的机械问题剩余的口吻、调色板与排版品味留给收尾的深度 pass 与人工判断。8.4 实际调用形态按 README.md 的用法命令聚焦具体区域/impeccable polish the checkout form常用命令如polish可先pin成独立快捷方式/impeccable pin polish→/polish。如果偏好 CLI 而非斜杠命令所有能力都收敛在同一个 launcher 上.gemini/skills/impeccable/scripts/impeccable verb例如本指南中的critique-storage latest/close。九、常见误区与自查清单误区正确做法借 polish 之名替换概念/视觉世界概念错了就明说建议 redesign 或bolder检测器干净就宣布完成干净 ≠ 质量必须人工复走真实交互路径只修当前截图里的视口验证每一个受支持视口与设备类别只打磨一个角落全程保持一致的质量门槛为「可见的打磨」添加动画动效必须连贯、可中断、高性能、有意义忘记保留snapshot_file没有它就无法在收尾时安全 close未清完 Priority Issue 就 close只关闭本轮真正处理完的快照追加额外 detector passcontext 只请求一次手动扫描不重复结语polish 的本质是一道发布闸门在功能完整的前提下让整条路径的设计系统对齐、状态完备、代码干净并把 critique 留下的问题账本干净地关掉。它不是一个万能美化命令而是一套有边界、有纪律、可验证的收尾流程——「细化而非重设计」是它的灵魂critique-storage 的新鲜度指纹与 close 归属校验是它的工程骨架。把本指南的五步流程与源码级机制结合起来你就能在任何前端项目上稳定地产出一轮可追溯、可交接、真正达到 shipping 标准的打磨通过。想要深入了解相关机制可以继续阅读仓库中的命令总览与模式划分.gemini/skills/impeccable/SKILL.mdcritique 快照的产生端.gemini/skills/impeccable/reference/critique.md质量底线craft floor.gemini/skills/impeccable/reference/craft-floor.md检测器 hook 管理.gemini/skills/impeccable/reference/hooks.md快照存储的 Rust 实现与测试crates/context/src/critique_storage.rs上下文加载PRODUCT.md/DESIGN.md 解析crates/context/src/context.rs【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 impeccable polish 实战指南：发布前的设计系统对齐与最终质量打磨
impeccable polish 实战指南发布前的设计系统对齐与最终质量打磨【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable导读/impeccable polish是 Impeccable 设计技能skill中面向「发布前收尾」的细化命令用于在功能完整的前提下对一条真实用户路径做系统化打磨对齐设计系统、修复漂移、补齐状态、清理代码并最终将本轮处理的 critique 快照闭环。本指南以 Impeccable 仓库内的 polish 参考文档 为骨架结合 critique_storage.rs、SKILL.md、craft-floor.md 等源码与配套参考完整讲解 polish 的五步流程、critique-storage 命令的用法与底层原理以及「细化而非重设计」的边界纪律。读完你可以在自己的前端项目上独立执行一轮合规的 polish 通过pass。一、polish 的定位与核心原则在 Impeccable 的 23 个命令中polish属于Refine细化类别与bolder放大、quieter收敛、distill精简、harden生产就绪并列。命令元数据 command-metadata.json 和 SKILL.md 对它的定位是「final quality pass before shipping」发布前的最终质量通过。README.md 中则将其描述为「final pass, design system alignment, and shipping readiness」。运行前polish 参考文档要求你明确一句附加上下文Additional context needed: quality bar and shipping constraints.需要补充上下文质量门槛与交付约束。两条不可动摇的核心原则Polish 是 refinement绝不是隐藏的重设计。必须保留既有的视觉世界、内容、行为和范围外的一切。如果概念本身错了应当明确说出来并建议重设计redesign或bolder而不是偷偷塞进一个替代方案。检测器detector的结果是缺陷证据不是质量证明。检测通过 ≠ 体验合格。必须亲自检查渲染出的真实体验与真实交互路径。这也与 SKILL.md 中「Refinement preserves; redesign replaces」细化保留重设计替换的总原则完全一致细化保留既有身份、行为、文案和范围外的一切重设计则保留产品事实、内容、功能、原生能力和约束但把旧外观当作证据与反参考。永远不要把差异拆成「对废弃外观的打磨」。二、Step 1建立系统Establish the system在动手修复任何漂移之前先建立「系统」这个参照系阅读DESIGN.md以及有代表性的 token、共享组件、模式与相邻流程如果项目里不存在正式的设计系统则采用连贯的项目约定coherent project conventions。关于读取机制可以从源码印证load_context见 crates/context/src/context.rs会解析PRODUCT.md/DESIGN.md大小写变体Product.md/product.md/Design.md/design.md均被识别并在 monorepo 场景下沿pnpm-workspace.yaml、turbo.json、nx.json、lerna.json等标记向上定位项目根。DESIGN.md的实际形态可以参考仓库根目录的 DESIGN.md——它是一份带 frontmatter 的可移植 token 导出如kinpaku-gold: oklch(84% 0.19 80.46)并有明确的单一事实来源约定“All values below mirror site/styles/kinpaku-tokens.css verbatim”。建立系统后对每一处漂移drift先分类再决定修法漂移类型含义正确修法missing token缺 token系统需要一个可复用的值把它提升为设计 tokenone-off implementation一次性实现本应复用某个共享组件或模式用共享组件/模式替换conceptual mismatch概念错位流程、信息架构或层级与同类产品区域不一致修正概念层面local defect局部缺陷实现本身不完整或不一致就地补齐修复原则是在最窄的正确层级修复根因。当无法从现有材料推断某个有约束力的系统原则时应当提问而不是擅自假设。三、Step 2收集证据Gather the evidence打磨不是对着截图工作。polish 要求你「自己用一遍这个功能」覆盖表面的代表性尺寸Web 端桌面 移动原生平台ios/android/adaptive模拟器、仿真器或真机上的实际出货设备类别按平台参考文档的 “Verifying the build” 一节采集证据。要确定四件事路径是否功能完整预期的质量门槛与可用时间已知约束或刻意未完成的工作用户实际会遇到的状态、内容长度、角色与输入方式。3.1 利用既有 critique 快照如果此前存在 critique把它作为一个输入而不是唯一输入。核心命令.gemini/skills/impeccable/scripts/impeccable critique-storage latest resolved target --json退出码语义Exit 0返回 JSON包含最新快照的body和精确的snapshot_file标识。snapshot_file必须一直保留到本轮 pass 结束。Exit 2不存在快照或目标已变更。无论哪种情况都必须独立执行一遍完整打磨。本地文件目标的新鲜度校验这是源码级事实见 crates/context/src/critique_storage.rslatest子命令会对本地文件计算当前内容的精确指纹sha256:前缀 SHA-256 摘要与 critique 记录在快照 frontmatter 中的target_fingerprint比对。任何字节变化、删除、或替换为非文件的操作都会关闭该快照对应的 backlog保留其趋势历史并以 exit 2 返回。URL 目标没有本地指纹因此会一直保持「当前」状态直到被显式关闭。当快照仍然有效当前时吸收body中相关的 P0/P1 发现并在打磨中指明你读的是哪一份快照。四、Step 3分类处理Triage把功能缺陷与外观问题分开按以下顺序修复损坏或被阻塞的任务、数据丢失、误导性状态、不可达的路径缺失的 loading、empty、error、success、disabled、permission 状态流程、层级、响应式与设计系统漂移视觉与动效不一致代码与资源清理。一个容易被忽略的纪律是不要只把一个角落打磨完美却让其余部分低于同一质量门槛。打磨是全程一致的收尾不是局部炫技。五、Step 4打磨整条路径Polish the whole path这是 polish 的核心实操章节覆盖五个维度。5.1 流程与层级Flow and hierarchy对齐相邻区域的思维模型、术语、信息揭露方式disclosure、路由、保存行为、乐观/悲观更新模式让主任务与当前状态显而易见但不要把每个元素都压平成同等的视觉权重确保到达arrival、过渡transition、空态empty、恢复recovery路径彼此连通而不是像孤立的屏幕。5.2 布局与排版Layout and type对齐项目的网格与间距刻度既修数学对齐也修视觉光学对齐相关内容紧密分组不同组之间慷慨留白同角色排版保持一致测试 measure行长、换行、本地化扩展、缩放与字体加载验证每一个受支持的视口而不是只修正当前这张截图。5.3 颜色、图片与图标Color, imagery, and icons使用语义化 token跨主题保持颜色含义稳定验证每一种状态下的文本、控件与焦点对比度保持图标家族、描边/字重、尺寸与光学对齐的连贯防止图片布局偏移layout shift使用正确的宽高比、响应式资源、有意义的 alt 文本。5.4 交互与状态Interaction and state每个控件都需要合适的 default、hover、focus、active、disabled、loading、error、success 行为保留可见的键盘焦点、逻辑 Tab 顺序、标签以及符合平台习惯的触控目标尺寸动效要连贯、可中断、高性能不要为了「让打磨可见」而添加动画在产品可能遇到的情况下验证长内容、缺失内容、本地化、离线、慢速与权限受限内容。5.5 内容与代码Content and code保持术语、大小写、标点与事实性文案一致改动事实性表述前先征询确认移除调试输出、死代码、未使用的 import、过时样式以及打磨过程中产生的重复凡是系统拥有该模式的用共享组件替换自定义实现把真正可复用的值提升为 token不要为单点例外制造一个系统级抽象。六、Step 5验证与收尾Verify and finish6.1 全路径复走用鼠标、键盘、触控如适用把完整路径再走一遍检查Web移动、中等、宽版布局原生两种支持方向下的手机与平板尺寸类别loading、empty、error、success、disabled、长内容、缺失内容状态缩放、对比度、焦点、语义与读屏器名称控制台错误、布局偏移、交互延迟与各处的图片加载Web 覆盖受支持的浏览器原生覆盖受支持的 OS 版本、运行时警告与掉帧与DESIGN.md、相邻功能以及用户明确的范围保持一致。6.2 借力自动检测器与上下文遵循impeccable context和 hooks 提供的质量指引再运行其他相关 QA 命令context 只会在没有自动检测器激活时请求一次手动扫描绝不要追加额外的检测器 pass修复真实缺陷只为极窄的、刻意的例外做文档化豁免干净的扫描结果不能替代视觉判断再次呼应开篇原则。关于检测器你还可以知道设计检测器 hook见 reference/hooks.md会在.tsx/.jsx/.html/.vue/.svelte/.astro/.css/.scss/.sass/.less/.ts/.js等设计相关文件被编辑后自动运行机械层规则broken images、溢出/裁剪、对比度与可读性、渐变文字、辉光阴影、设计系统漂移等Stop事件上还会跑全量规则集的深度 pass。无 hook 的会话会收到MANUAL_DETECTOR_REQUIRED指令要求收尾时执行一次扫描。6.3 源码差异收尾以源码 diff 收尾移除意外改动churn、孤儿代码、冗余值与临时产物。只有当功能在整条路径上功能完整且一致地完成时才允许发布。6.4 关闭快照close当本轮 pass 清除了从快照中接手的每一个 Priority Issue 时关闭该快照.gemini/skills/impeccable/scripts/impeccable critique-storage close resolved target snapshot_file returned by latest关闭纪律与源码实现严格对应只关闭本轮实际处理的那一份快照如果期间落入了更新的 critique其 backlog 仍然保持活跃没有读取快照、没有保留snapshot_file、或仍有 Priority Issue 未清时不得关闭。七、源码级原理critique-storage 是如何工作的polish 与 critique 之间的状态衔接全部由critique-storage子命令实现源码位于 crates/context/src/critique_storage.rs。几个值得展开的实现事实快照的落盘形态。快照文件写入项目根的.impeccable/critique/目录由get_critique_dir拼出resolve_project_root(cwd) .impeccable/critique命名形如2026-05-12T18-30-00Z__slug.md文件名以now_filename_stamp生成的 UTC 时间戳打头冒号与点替换为-__之后是目标 slug。同秒冲突时使用定宽~0001~9999后缀create_new(true)独占创建保证同一 UTC 秒内的第二次 critique 不会覆盖历史——这一点有明确的单元测试snapshot_name_accepts_collision_suffix佐证。目标身份target identity。本地文件被解析为file:绝对路径URL 被解析为url:originpathname去尾部斜杠避免latest/close时误配。测试target_identity_file_url_and_trailing_slash验证了三种形态。指纹与新鲜度。对本地文件计算sha256:hex内容指纹并写入 frontmatter 的target_fingerprintlatest时重新计算当前文件指纹并做严格字符串比较不等则自动关闭快照保留趋势历史并返回 exit 2——这正是 polish 参考文档中「任何字节变更都会使旧 backlog 关闭」的底层实现。closed 标记。close子命令在快照 frontmatter 中插入closed: trueinsert_closed_flag只有带 frontmatter 的快照才可关闭否则报错。关闭过的快照在latest中不再返回exit 2二次 close 是静默 no-op。close_verb_round_trip_and_ownership测试完整验证了「错误目标被拒、正确目标关闭、二次关闭为 no-op」的闭环。close 的归属校验。现代快照要求传入的snapshot_file与解析后的目标身份精确匹配且文件名必须通过is_snapshot_name的命名格式校验、位于 critique 目录内slug 文件名不足以证明归属。这是防误关的关键安全边界。趋势trend。trend target [limit]默认 limit 5返回最近 N 条 frontmatter 的 JSON 数组供 critique 结束后展示分数趋势。八、把 polish 放进整个工作流8.1 与impeccable context的关系每会话一次先运行.gemini/skills/impeccable/scripts/impeccable contextWindows 无sh的 shell 用.cmd版本。它加载PRODUCT.md、DESIGN.md、匹配的 surface brief 与原生平台指引polish 必须遵循其指令且不要重跑。launcher 不可用时的降级路径是直接读取现有 PRODUCT.md/DESIGN.md 继续但不得虚构缺失的上下文。8.2 与 critique 的接力critique.md 明确规定critique 的持久化产物含启发式评分表、P0–P3 优先级问题写入.impeccable/critique/正是为了让/impeccable polish无需复制粘贴就能接手这些 Priority Issues。polish 读取 → 修复 → 关闭形成闭环趋势线如24 → 28 → 32则记录同一目标随轮次改善的轨迹。8.3 与 craft-floor 的互补craft-floor.md 承载「任何扫描器都抓不到」的反射与质量底线对比度 ≥4.5:1 / 大文本 ≥3:1、正文字宽 65–75ch、display 最大 6rem、tracking 下限 -0.04em、动效一次一个作者时刻、浏览器原生表面也要被主题化等。SKILL.md 要求在任何 UI 编辑包括小优化之前先读 craft-floor——polish 作为发布前收尾正是这套「地板」的最终检验场。而检测器 hook 的机械规则与 craft-floor 的手感规则分工明确hook 覆盖可中断编辑的机械问题剩余的口吻、调色板与排版品味留给收尾的深度 pass 与人工判断。8.4 实际调用形态按 README.md 的用法命令聚焦具体区域/impeccable polish the checkout form常用命令如polish可先pin成独立快捷方式/impeccable pin polish→/polish。如果偏好 CLI 而非斜杠命令所有能力都收敛在同一个 launcher 上.gemini/skills/impeccable/scripts/impeccable verb例如本指南中的critique-storage latest/close。九、常见误区与自查清单误区正确做法借 polish 之名替换概念/视觉世界概念错了就明说建议 redesign 或bolder检测器干净就宣布完成干净 ≠ 质量必须人工复走真实交互路径只修当前截图里的视口验证每一个受支持视口与设备类别只打磨一个角落全程保持一致的质量门槛为「可见的打磨」添加动画动效必须连贯、可中断、高性能、有意义忘记保留snapshot_file没有它就无法在收尾时安全 close未清完 Priority Issue 就 close只关闭本轮真正处理完的快照追加额外 detector passcontext 只请求一次手动扫描不重复结语polish 的本质是一道发布闸门在功能完整的前提下让整条路径的设计系统对齐、状态完备、代码干净并把 critique 留下的问题账本干净地关掉。它不是一个万能美化命令而是一套有边界、有纪律、可验证的收尾流程——「细化而非重设计」是它的灵魂critique-storage 的新鲜度指纹与 close 归属校验是它的工程骨架。把本指南的五步流程与源码级机制结合起来你就能在任何前端项目上稳定地产出一轮可追溯、可交接、真正达到 shipping 标准的打磨通过。想要深入了解相关机制可以继续阅读仓库中的命令总览与模式划分.gemini/skills/impeccable/SKILL.mdcritique 快照的产生端.gemini/skills/impeccable/reference/critique.md质量底线craft floor.gemini/skills/impeccable/reference/craft-floor.md检测器 hook 管理.gemini/skills/impeccable/reference/hooks.md快照存储的 Rust 实现与测试crates/context/src/critique_storage.rs上下文加载PRODUCT.md/DESIGN.md 解析crates/context/src/context.rs【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考