ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Impeccable `polish` 命令实战:发布前设计质量打磨的五阶段工作流

Impeccable `polish` 命令实战:发布前设计质量打磨的五阶段工作流 Impeccablepolish命令实战发布前设计质量打磨的五阶段工作流【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccablepolish是 Impeccable 设计技能design skill中 Refine 类别的核心命令定位是“发布前的最后一道质量关”final quality pass before shipping。它不重写视觉世界而是把既有界面沿着既有设计系统打磨到功能完整、状态齐全、细节一致。读完本文你将掌握polish的完整五阶段工作流建立系统、收集证据、分级分诊、沿整条路径打磨、验证收尾并能结合仓库源码理解 critique 快照存储、slug 派生与检测器回退机制的实际实现把polish真正用于你自己的前端项目收尾。polish 的定位refinementnever concealed redesignpolish的第一原则写在 reference/polish.md 开篇Polish 是精炼绝不暗藏重设计。必须保留在任incumbent的视觉世界、内容、行为以及一切范围之外的东西。如果“概念本身就是错的”应当直接说出来并推荐redesign或bolder而不是把替换方案偷偷塞进 polish 里。检测器结果是缺陷证据不是质量证明。不能因为扫描通过就认为质量达标必须检查渲染后的真实体验与真实交互路径。在 SKILL.md 的命令表中politch [target]位于 Refine 分类与bolder、quieter、distill、harden、onboard并列描述为 “Final quality pass before shipping”对应引用文件即 reference/polish.md。文档开头还要求使用者先提供两类上下文质量基线quality bar与交付约束shipping constraints——这两项决定了后面所有取舍的尺度。阶段一建立系统Establish the system动手修任何漂移drift之前先建立参照系读取DESIGN.md以及代表性的设计 token、共享组件、既有模式与邻近流程如果项目没有正式设计系统就以项目内一致的约定coherent project conventions为准——注意 SKILL.md 强调“DESIGN.md 缺失不等于项目是 greenfield”代码里的 token、组件与资产本身就是在任的设计权威。随后对每一处漂移先分类再修复文档给出四种漂移类型漂移类型含义正确修法missing token系统需要一个可复用的值把值提升为 tokenone-off implementation存在一次性实现而系统里已有共享组件/模式用共享组件替换它conceptual mismatch流程、信息架构或层级与同类产品区域不一致对齐邻近区域的模型local defect实现本身不完整或不一致就地修缺陷修复原则是“在最窄的正确层级修因”fix the cause at the narrowest correct level能用局部修复的不改系统能用系统值的不在局部堆补丁。当无法从上下文推断出某个约束性系统原则时问用户而不是自己猜。从源码结构看这一步的上下文由 context.mjs 统一供给它每会话运行一次把PRODUCT.md、DESIGN.md、匹配的 surface brief 与如平台为原生ios/android平台参考一并输出并在DESIGN.md缺失而代码中存在在任视觉实现时输出INCUMBENT_WORLD_UNDOCUMENTED指令提示“代码与资产是权威缺失的 DESIGN.md 只是文档缺口”。这与 polish“没有正式系统就用项目约定”的原则一一对应。阶段二收集证据Gather the evidencepolish 不依赖“看一张截图”下结论而是要求亲自使用这个功能在表面的代表尺寸上走一遍真实路径Web桌面与移动端都要覆盖原生平台ios/android/adaptive在模拟器、仿真器或真机上覆盖已发布的设备类device classes并按平台参考文档的Verifying the build一节采集——即 ios.md 与 android.md 中的同名小节。走查时确定四件事该路径功能上是否完整是否真的做完了预期的质量基线quality bar与可用时间已知约束以及刻意未完成的工作避免把“未排期”当成“缺陷”用户实际会遇到的状态、内容长度、角色与输入方式。读取上一轮 critique 快照如果之前跑过/impeccable critique用其输出作为其中一个输入node .agent/skills/impeccable/scripts/critique-storage.mjs latest resolved target退出码 0返回该目标最新一份快照应纳入其中相关的P0/P1发现并在汇报中点名你读的是哪份快照退出码 2该目标尚不存在快照。无论有无快照都要独立再走一遍完整检查——快照只是 backlog不是替代。源码级实现快照是怎么存的critique-storage.mjs 的头部注释说明了这个机制每次 critique 运行把一份快照写入.impeccable/critique/timestamp__slug.md附带记录分数与 P0/P1 计数的 YAML frontmatterpolish 工作流在启动时读取最新匹配的快照作为修复 backlog没有别的 skill 会自动读 critique 输出。关键实现细节快照文件名格式critique-storage.mjs 中用正则SNAPSHOT_FILENAMEUTC 时间戳 __ slug匹配时间戳经nowFilenameStamp()处理掉冒号保证 Windows 文件系统安全latest子命令readLatestSnapshot()按文件名排序取最后一份取不到时 CLI 以退出码 2结束critique-storage.mjs#L188-L193这正是 polish 文档里 “Exit 2 means none exists” 的实现来源slug 稳定性是趋势追踪的前提slug 由解析后的主产物文件路径或 URL机械派生绝不来自用户的自然语言措辞。target-slug.mjs 中slugFromTarget()会把相对路径或 URL 的 hostpathname 转成 kebab-caseURL 会去掉端口超过 50 字符时保留尾部截断空输入或项目根返回null。因此命令要求传入resolved target——即先把“首页”解析成具体文件/URL 再执行。仓库中的 tests/critique-storage.test.mjs 对这些行为做了回归验证路径/URL 的 slug 归一化、Windows 安全时间戳、writelatest的 round-trip 等测试直接 import skill/scripts/critique-storage.mjs即 skill 源目录版本。P0/P1 的判定标准在 reference/critique.md 的Issue Severity (P0–P3)一节P0 Blocking完全阻止任务完成showstopper立即修P1 Major造成显著困难或困惑发布前必须修P2/P3 依次降低。critique 文档也明确快照的定位“chat 回复是主要交付物快照只是存档/backlog供/impeccable polish免复制粘贴地继承优先级”。阶段三分诊Triage把功能缺陷与外观缺陷分开并严格按以下顺序修复已损坏或被阻塞的任务、数据丢失、误导性状态、不可访问的路径缺失的 loading / empty / error / success / disabled / permission 状态流程flow、层级hierarchy、响应式responsive、设计系统漂移视觉与动效不一致代码与资产清理。这条顺序的实质是“按用户价值降序”先修会丢任务、丢数据的再补齐状态机然后才轮到与设计系统的一致性最后才是纯外观与代码卫生。文档用一句收尾约束住常见偏科“不要只把一个角落打磨到完美而让其余部分停留在同一质量基线以下”。阶段四打磨整条路径Polish the whole path这是 polish 的正文按五个维度展开。注意其对象是“整条路径the whole path”而非单个屏幕。流程与层级Flow and hierarchy对齐邻近区域的心智模型术语、披露方式disclosure、路由、保存行为、乐观/悲观更新模式让主任务与当前状态显而易见但不把一切元素压成等权重到达arrival、过渡transition、空状态与恢复路径应连成一体而不是行为像孤立屏幕。布局与字体Layout and type对齐项目的栅格与间距尺度不仅修数学对齐也修光学对齐optical alignment相关内容紧凑成组不同组之间留足间隙同角色排版保持一致测试行宽measure、换行、本地化文本膨胀、缩放与字体加载验证每一个支持的视口而不是只修当前截图里的那一个。颜色、图像与图标Color, imagery, and icons使用语义 token跨主题保持颜色含义稳定在每一个状态下验证文本、控件与焦点的对比度图标家族、描边/粗细、尺寸与光学对齐保持连贯防止图片引起布局偏移正确的宽高比、响应式图源、有用的 alt 文本。交互与状态Interaction and state每个控件都需要得体的 default / hover / focus / active / disabled / loading / error / success 行为保留可见的键盘焦点、逻辑 tab 顺序、标签以及平台适当的触控目标尺寸动效要连贯、可中断、性能良好不要为了让“打磨”可见而加动画在产品真实会遇到长文本、缺失、本地化、离线、慢速、权限受限内容时验证这些输入。内容与代码Content and code术语、大小写、标点与事实性文案保持一致修改事实性声明之前先问删除调试输出、死代码、无用 import、过期样式以及打磨过程中新产生的重复系统拥有该模式时用共享组件替换自定义实现把真正可复用的值提升为 token但不要为一个局部例外发明系统级抽象——这是阶段一“最窄正确层级”原则在代码层面的呼应。可量化的机械底线craft-floor上述原则中有一部分带有硬性数值集中维护在 reference/craft-floor.md按 SKILL.md 的流程它在编辑 UI 前加载承载质量底线与检测器抓不到的反模式。与 polish 直接相关的机械判据包括对比度正文与占位符文本 ≥ 4.5:1大字号文本 ≥ 3:1彩色表面上的次要文本用该色相或前景色染色而不是灰色排版正文行宽 65–75chdisplay 上限 6rem字距tracking下限 -0.04em标题均衡断行明确的字阶与字重步进深度阴影必须带偏移与柔和模糊零偏移的彩色光晕属于装饰而非深度系统状态hover、disabled、loading、error、empty 齐全外加真实内容、可用控件、响应式构图与键盘焦点浏览器表面文本选中、光标、自定义滚动条、焦点环、下划线偏移、表格数字字体等“你没画的部分”也要从调色板主题化——craft-floor 称这是“页面是被造出来而非拼出来的”最便宜信号也是模型最容易跳过的一项。这些数值正好为 polish 阶段四里“验证对比度/行宽/状态”等要求提供了可直接执行的验收标准。阶段五验证与收尾Verify and finish再次走完整路径用鼠标、键盘、触摸如适用把完整路径再走一遍逐项核对Web移动、中间、宽屏布局原生手机与平板尺寸类且两种支持的方向都要看loading、empty、error、success、disabled、长内容、缺失内容各状态缩放zoom、对比度、焦点、语义、读屏名称控制台的报错、布局偏移layout shift、交互延迟、图片加载——在每一处Web 覆盖支持的浏览器原生覆盖支持的 OS 版本、运行时告警与掉帧与DESIGN.md、邻近功能、以及用户声明的范围达成一致。检测器与 hooks 的边界polish 文档对自动检测划了明确的边界遵循context.mjs与 hooks 提供的质量指引然后运行其他相关的 QA 命令。具体规则是只有当没有自动检测器在运行时context 才会请求一次人工扫描永远不要额外添加检测器 pass修真实的缺陷只对窄范围的刻意例外做记录干净的扫描不能替代视觉判断与开篇“detector result is defect evidence, not proof of quality”首尾呼应。从源码看这套逻辑在 context.mjs 中有直接实现automaticHookMode()先按平台判断原生平台无 hook因为检测器只读 HTML/CSS再经hookEnabledAt()读取.impeccable/config.json/config.local.json的hook.enabled并检查各 harness 的 hook 清单是否注册了hook.mjs只有当 hook 完全不活跃时appendDetectorFallback()才会输出MANUAL_DETECTOR_REQUIRED指令要求对改动的 Web UI 运行一次机械检测器node .agent/skills/impeccable/scripts/detect.mjs --json changed targets并明确“只运行一次且在概念选择期间不要提前跑”context.mjs#L1400-L1409。这就是 polish 文档中“Context requests a manual scan only when no automatic detector is active”的实现对应物。以 source diff 收尾最后交付一份源码级 diff删掉意外引入的改动churn、孤儿代码、冗余值与临时产物。放行ship的条件是功能完整且整条路径上的一致完成度达标——而不是某个最亮眼的屏幕达标。前提、限制与快速核对清单运行环境polish依附于 impeccable 技能当前仓库 SKILL.md 标注版本 4.1.2命令依赖 Node 执行.agent/skills/impeccable/scripts/下的脚本仓库同时保留 skill 源目录 skill/reference/polish.md.agent/skills/为安装/运行时副本。适用平台Web 项目覆盖桌面移动端ios/android/adaptive项目按平台参考的Verifying the build覆盖设备类原生项目没有机械检测器检测器只读 HTML/CSS验证完全依赖走查。与 critique 的配合critique 写快照、polish 读快照两者通过 slug 关联trend子命令还能按同一目标输出最近若干份快照的 frontmatter用于观察分数趋势。不要做的事不在 polish 里夹带重设计不为局部例外造系统抽象不加多余检测器 pass不因扫描干净而跳过视觉判断不未经确认就改动事实性文案。可复制的核对清单建立参照DESIGN.md / token / 共享组件已读无系统则确认项目约定每处漂移已归类missing token / one-off / conceptual / local。证据真实路径在代表尺寸上走通上轮快照已用critique-storage.mjs latest读取或确认退出码 2P0/P1 已列入 backlog。分诊五级修复顺序未倒置没有“角落完美、整体欠账”。打磨流程、布局/字体、颜色/图像/图标、交互/状态、内容/代码五维逐项过craft-floor 数值4.5:1 / 3:1、65–75ch、-0.04em作为验收线。验证鼠标/键盘/触摸全路径复核检测器按 context 指令执行且不多跑以 source diff 收尾churn 清零。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表