企业官网建设流程全解析

Impeccable polish 精修实战指南：发布前最后一个质量关卡

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

Impeccable 的polish是 Refine（精修）类别下的收尾命令，定位是"发布前的最终质量检查"（见 SKILL.md 命令表 与 command-metadata.json 中对 polish 的描述："fixing alignment, spacing, consistency, and micro-detail issues before shipping"）。它接管 critique 留下的优先问题、harden 加固后的成品，沿完整用户路径把布局、排版、色彩、交互、状态与代码逐项打磨到一致的质量水准。读完本文，你将掌握 polish 的精修原则、漂移分类、证据收集与分诊方法、五维打磨清单、快照关闭流程，以及它和 critique、harden、hooks、craft-floor 之间的协作边界。

1. 先立规矩：精修（refine）永远不等于换皮（redesign）

polish 参考文档（reference/polish.md）开宗明义给出三条铁律，任何打磨动作都必须在此框架内进行：

• Polish is refinement, never concealed redesign.精修必须保留现有的视觉世界、内容、行为以及范围之外的一切。如果概念本身错了，应当直说，并推荐 redesign 或bolder，而不是夹带一个替换方案偷偷上线。这与 SKILL.md 的"如何设计" 完全一致：refinement 保留现有身份、行为、文案与范围外的一切；redesign 才允许更换视觉世界。
• 检测器结果只是缺陷证据，不是质量证明。检测器（detector）能机械地发现对比度不足、内容溢出、设计系统漂移等问题，但"干净"不代表体验好。真正的判断必须落到渲染后的实际体验与真实交互路径上。
• 不要为打磨而打磨。不要在已经一致的系统里为单一局部例外硬造一套抽象，也不要为了让打磨"看得见"而添加动画。

2. 建立系统：先认清现状，再给漂移分类

打磨的第一步不是改代码，而是建立判断基准。打开 DESIGN.md（仓库根目录即存在此文件）与代表性的 token、共享组件、模式和相邻流程；如果项目没有正式的视觉系统，就采用项目中一致的自有约定。这里隐含了 impeccable 的上下文机制：会话开始时应先运行impeccable context加载 PRODUCT.md、DESIGN.md、surface brief 等上下文，并遵循其指令（见 SKILL.md Setup 段）。

面对每一个漂移，先分类再动手，polish 文档给出了四类：

修复原则是在最窄的正确层级修根因（fix the cause at the narrowest correct level），而不是在同一层级反复打补丁；当无法从现有资料推断出系统级原则时，应当询问用户而不是擅自决定。这与 craft-floor 的"从已确定的提交世界出发，而非自己的习惯"（reference/craft-floor.md）互为表里。

3. 收集证据：亲身体验 + 读取 critique 快照

在动手前，必须"用产品本身"在代表性尺寸上走一遍：Web 端覆盖桌面与移动端；原生平台（ios/android/adaptive）则在模拟器、仿真器或真机上按平台参考文档（ios.md 的Verifying the build、android.md 的Verifying the build）所描述的方式截图。需要确认四件事：

1. 路径功能是否完整；
2. 预期质量门槛与可用时间；
3. 已知约束或刻意未完成的工作；
4. 用户实际会遇到的状态、内容长度、角色与输入方式。

3.1 用 critique-storage 读取既有评审

如果之前有过 critique 评审，polish应当把它作为输入之一，而不是无视它：

.claude/skills/impeccable/scripts/impeccable critique-storage latest "<resolved target>" --json

• 退出码 0：返回 JSON，包含最新快照的body与精确的snapshot_file标识。必须把snapshot_file保留到本轮结束，因为收尾时关闭快照需要它。
• 本地文件目标：helper 会把文件当前精确内容指纹（SHA-256）与 critique 记录时的指纹比对。未改动的已暂存、未暂存或未跟踪内容视为"仍为当前"；任何字节变化、删除或替换为非文件，都会关闭它此前识别的 backlog（同时保留趋势历史）并退出码 2。
• URL 目标：没有本地指纹，会一直保持"当前"，直到被显式关闭。
• 退出码 2：表示不存在快照或目标已变更。无论哪种情况，都要独立执行一轮精修，不能依赖旧快照直接改。

这套语义在源码中有完整实现，见 crates/context/src/critique_storage.rs：指纹为sha256:<hex>（L229-L238），目标身份为file:<解析后的绝对路径>或url:<origin + pathname>（L214-L227）；latest在本地指纹不一致时会先关闭该快照再返回 2（L580-L597）。快照文件命名形如2026-05-12T18-30-00Z__<slug>.md，同一秒内的并发写入用~NNNN四位定宽后缀防碰撞（L509-L525），这一行为在测试 close_verb_round_trip_and_ownership 中有完整覆盖。快照体存在.impeccable/critique/目录下，由slug（对目标路径/URL 派生的稳定标识）组织。

当快照仍然有效时，把其中的P0/P1 优先问题纳入本轮，并在最终报告中注明"读取了哪个快照"。

4. 分诊：先修功能，再修观感

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

1. 断裂或阻塞的任务、数据丢失、误导性状态、不可达路径——这是 P0，优先于一切；
2. 缺失的 loading、空、错误、成功、禁用、权限状态——状态不全会让用户误判；
3. 流程、层级、响应式与设计系统漂移——结构性一致性问题；
4. 视觉与动效不一致——观感层；
5. 代码与资源清理——死代码、重复值、临时产物。

关键约束是：不要把一个角落打磨到完美，而让其余部分低于同一质量门槛（"Do not perfect one corner while leaving the rest below the same quality bar"）。严重度分级（P0–P3）的定义可参照 reference/critique.md 的 Issue Severity 一节：P0 阻止任务完成、P1 造成显著困难、P2 有绕行方案、P3 锦上添花。

5. 全路径打磨：五个维度逐一过检

polish 的核心章节把打磨拆成五个维度，每个维度都是一份可直接执行的检查清单。

5.1 流程与层级（Flow and hierarchy）

• 匹配相邻区域的心智模型、术语、披露方式、路由、保存行为，以及乐观/悲观更新模式；
• 让主任务与当前状态显而易见，但不要把所有元素压成同等权重；
• 到达路径、过渡、空状态与恢复路径必须互相衔接，而不是各自孤立的"屏"。

5.2 布局与排版（Layout and type）

• 对齐项目的网格与间距尺度，同时修正光学对齐与数学对齐（视觉重心对齐往往比像素对齐更重要）；
• 相关内容紧凑成组、不同分组慷慨分隔；
• 同角色的排版保持一致；测试 measure（行长）、换行、本地化扩展、缩放与字体加载；
• 逐个验证所有支持的视口，而不是只修正当前这张截图。

5.3 色彩、图像与图标（Color, imagery, and icons）

• 使用语义化 token，让颜色含义跨主题稳定；
• 在每个状态下验证文本、控件与焦点对比度；
• 保持图标家族、描边/字重、尺寸与光学对齐的连贯；
• 防止图片布局偏移（layout shift）：正确的宽高比、响应式图片来源、有意义的 alt 文本。

5.4 交互与状态（Interaction and state）

• 每个控件都要有恰当的默认、hover、focus、active、disabled、loading、error、success 行为；
• 保留可见的键盘焦点、逻辑 tab 顺序、标签与平台适配的触控目标；
• 动效保持连贯、可中断、性能良好——不要为了让打磨看得见而加动画；
• 在产品可能遇到的场景中验证长内容、缺失内容、本地化内容、离线、慢速与权限受限内容。

5.5 内容与代码（Content and code）

• 保持术语、大小写、标点与事实性文案一致；修改事实声明前先询问；
• 移除调试输出、死代码、未用 import、过时样式与打磨引入的重复；
• 系统已拥有该模式时，用共享组件替换自定义实现；
• 真正可复用的值才提升为 token；不要为单一局部例外创建系统抽象。

6. 验证与收尾：三通道走查 + 源码 diff + 关闭快照

6.1 完整路径的三通道走查

用鼠标、键盘、触控（如适用）重新走完整条路径，检查：

• 布局：Web 端覆盖移动、中间与宽屏；原生端覆盖手机与平板两种尺寸类别、两个支持方向；
• 状态：loading、空、错误、成功、禁用、长内容、缺失内容；
• 可达性：缩放、对比度、焦点、语义、屏幕阅读器可读名称；
• 运行时：控制台错误、布局偏移、交互延迟、图片加载——Web 端覆盖支持浏览器，原生端覆盖支持 OS 版本、运行时警告与掉帧；
• 一致性：与 DESIGN.md、相邻功能、用户既定范围是否一致。

6.2 遵循质量指引与 hooks

遵循impeccable context与 hooks 提供的质量指引，再运行其他相关 QA 命令。这里有一条明确的边界：只有当没有自动检测器在运行时，context 才要求手动扫描一次；绝不额外增加一次检测器扫描。这与 hooks 的设计吻合（reference/hooks.md）：每条编辑触发 per-edit 层、Stop 事件触发全量深度扫描，无自动 hook 的会话会收到一条MANUAL_DETECTOR_REQUIRED指令。此外要记住：干净的扫描结果不能替代视觉判断（"A clean scan does not replace visual judgment"）。

6.3 源码 diff 与交付标准

收尾时做一次源码 diff：清除意外改动、孤立代码、冗余值与临时产物。只有功能完整、且整条路径一致地达到同一完成度时，才能交付。

6.4 关闭快照（critique-storage close）

当本轮把从快照接手的所有 Priority Issue 全部清除后，关闭该快照：

.claude/skills/impeccable/scripts/impeccable critique-storage close "<resolved target>" "<snapshot_file returned by latest>"

关闭语义（源码见 close_snapshot 实现 与 close verb）：

• 只关闭本轮实际处理过的那个快照；若期间落入了更新的 critique，它的 backlog 保持存活；
• 未读取任何快照、未保留snapshot_file、或仍有 Priority Issue 未清时，不得关闭；
• close会在快照 frontmatter 中写入closed: true（insert_closed_flag），二次关闭是静默 no-op；错误目标身份会被拒绝（退出码 2），这一所有权校验在测试 close_verb_round_trip_and_ownership 中得到验证。

7. 与相邻能力的协作边界

polish不是孤立的命令，它处于一条完整工作流的末端，正确使用它需要理解与周围能力的边界：

• critique → polish 的数据链路：critique 通过critique-storage write持久化快照（记录total_score、max_score、P0/P1 计数与目标指纹，见 reference/critique.md），polish 通过latest --json无缝接管 Priority Issues，完成后用close归还。趋势可通过critique-storage trend "<target>" 5查看最近 5 次的分数演变。
• harden → polish 的移交：harden 参考文档（reference/harden.md）明确写道"当边缘情况覆盖完毕后，移交/impeccable polish做最终打磨"——即 polish 站在加固之后的成品上做一致性与细节收尾。
• craft-floor 的机械底线：打磨时的对比度（正文与占位文本 ≥4.5:1、大文本 ≥3:1）、行长（65–75ch）、间距、动效与状态检查，都已有机械化的检查清单，见 reference/craft-floor.md；hook 激活时这些检查由 hook 强制执行，打磨时应处理其发现而非重新审计每条规则。
• bolder / redesign 的分流：当问题不是"细节不精"而是"概念本身错了"，polish 的纪律要求停止精修、明确建议 redesign 或bolder——这保证了 polish 始终服务于既有视觉世界，而不是悄悄替换它。

结语

一次合格的 polish 是克制的：它不改文案事实、不重建系统、不为局部例外发明抽象，而是把整条用户路径提升到同一质量线。判断依据永远是渲染后的真实体验与真实交互路径，检测器与快照只是证据；最终交付标准是"功能完整 + 全路径一致 + 无临时痕迹"，并以关闭快照、留下干净的源码 diff 作为收尾标志。把 polish 放在 critique、harden 与 hooks 的协作链末端使用时，它就是你发布前最后一道、也是最值得信赖的一道质量关卡。

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