企业官网建设流程全解析

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.（需要补充上下文：质量门槛与交付约束。）

两条不可动摇的核心原则：

1. Polish 是 refinement，绝不是隐藏的重设计。必须保留既有的视觉世界、内容、行为和范围外的一切。如果概念本身错了，应当明确说出来，并建议重设计（redesign）或bolder，而不是偷偷塞进一个替代方案。
2. 检测器（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）先分类，再决定修法：

修复原则是：在最窄的正确层级修复根因。当无法从现有材料推断某个有约束力的系统原则时，应当提问而不是擅自假设。

三、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.rs）：latest子命令会对本地文件计算当前内容的精确指纹（sha256:前缀 + SHA-256 摘要），与 critique 记录在快照 frontmatter 中的target_fingerprint比对。任何字节变化、删除、或替换为非文件的操作都会关闭该快照对应的 backlog（保留其趋势历史），并以 exit 2 返回。URL 目标没有本地指纹，因此会一直保持「当前」状态，直到被显式关闭。

当快照仍然有效（当前）时：吸收body中相关的 P0/P1 发现，并在打磨中指明你读的是哪一份快照。

四、Step 3：分类处理（Triage）

把功能缺陷与外观问题分开，按以下顺序修复：

1. 损坏或被阻塞的任务、数据丢失、误导性状态、不可达的路径；
2. 缺失的 loading、empty、error、success、disabled、permission 状态；
3. 流程、层级、响应式与设计系统漂移；
4. 视觉与动效不一致；
5. 代码与资源清理。

一个容易被忽略的纪律是：不要只把一个角落打磨完美，却让其余部分低于同一质量门槛。打磨是全程一致的收尾，不是局部炫技。

五、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 finish）

6.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:<origin><pathname>（去尾部斜杠），避免latest/close时误配。测试target_identity_file_url_and_trailing_slash验证了三种形态。

指纹与新鲜度。对本地文件计算sha256:<hex>内容指纹并写入 frontmatter 的target_fingerprint；latest时重新计算当前文件指纹并做严格字符串比较，不等则自动关闭快照（保留趋势历史）并返回 exit 2——这正是 polish 参考文档中「任何字节变更都会使旧 backlog 关闭」的底层实现。

closed 标记。close子命令在快照 frontmatter 中插入closed: true（insert_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 context（Windows 无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 的本质是一道发布闸门：在功能完整的前提下，让整条路径的设计系统对齐、状态完备、代码干净，并把 critique 留下的问题账本干净地关掉。它不是一个万能美化命令，而是一套有边界、有纪律、可验证的收尾流程——「细化而非重设计」是它的灵魂，critique-storage 的新鲜度指纹与 close 归属校验是它的工程骨架。把本指南的五步流程与源码级机制结合起来，你就能在任何前端项目上稳定地产出一轮可追溯、可交接、真正达到 shipping 标准的打磨通过。

想要深入了解相关机制，可以继续阅读仓库中的：

• 命令总览与模式划分：.gemini/skills/impeccable/SKILL.md
• critique 快照的产生端：.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