Impeccable

Impeccable 快速入门：把「让它好看点」变成可以点名的设计动作

这是什么？适合谁？

Impeccable 官方给自己的定位是「the design vocabulary for your coding agent」——给编码 Agent 的一套设计词汇。它要解决的是一个具体到有点难看的现象：你不给额外指导、只让 Agent 做一个页面，它就会稳定地产出同一套东西——Inter 打天下、紫蓝渐变、卡片套卡片、彩底灰字、每个标题上一个圆角方形图标块。官方把这类痕迹统称为 AI slop，Impeccable 的作用是在它发出去之前抓住它。

它由三块组成：

• 24 条命令：polish（发版前最后一轮）、bolder / quieter（放大或收敛视觉）、distill、colorize、typeset、layout、animate、delight、overdrive（引导向），critique（打分式 UX 评审）、audit（技术质量报告），harden、clarify、adapt、optimize、onboard（收尾向），live / generate（在浏览器里现场迭代），shape / init / document / extract（规划与建档）。第 24 条 craft 是已废弃的别名。
• 62 条确定性规则：就是那个 slop detector。官方明确写着「No LLM, no API key」——它跑的是规则，不是模型判断。
• 两种上下文文件：/impeccable init 读你的代码、只问它推不出来的事（产品面向谁、要做什么、有什么约束），写进 PRODUCT.md；/impeccable document 把你现有的视觉系统写进 DESIGN.md，让后续改动不跑偏。

适合谁：

• 已经在用编码 Agent 写前端、但每次都要手工把审美拉回来的开发者；
• 要把「设计验收」做成可复跑、可进 CI的检查项的团队（规则是确定性的，能给 GitHub Actions 注释、能给退出码）；
• 有人维护设计系统、最怕 Agent 每次都重新发明一套间距与字号的前端负责人。

不适合谁：完全不懂设计、期望「一键出好看的官网」的人。官方自己也说了，它在已经存在的界面上最强——指一个页面或组件去迭代；新页面也能做，但那是更难的模式。

与站内同类条目对比：anthropic-frontend-design（本站 8.5）是这套东西的起点——Impeccable 官方在许可段写明「started from Anthropic’s frontend-design skill」；vercel-web-design-guidelines（本站 8.4）给的是 Web 界面规范清单；anthropic-frontend-ui-engineering（本站 8.5）偏工程实现。Impeccable 的差异在「把设计动作变成命令 + 把 slop 变成可机检规则」。

核验日期：2026-10-30。依据 官方仓库 README、官方站点、官方文档、GitHub API。

准备工作

• 一个支持的编码工具。官方列了 20 多个入口：Claude Code、Cursor、Codex CLI、GitHub Copilot、Devin、Replit Agent、Gemini CLI、Grok Build、OpenCode、Google Antigravity、Kiro、Trae、Rovo Dev、Qoder、Mistral Vibe、Pi、Hermes Agent、DeepSeek Harness、Veto。
• Node（只为 npx 用）。技能本身跑的是随包分发的自包含引擎二进制，首次会下载到 ~/.impeccable/bin/。
• 一个已经能跑起来的前端项目（Vite / Next / SvelteKit / Astro / Nuxt / 纯 HTML 都行），最好有 dev server——扫描渲染态页面要用到它。
• 一个 dev server 或线上 URL：有些规则（低对比度、过小字号）只在扫描渲染后的页面时才生效，只扫源码会漏。
• 时间预算：装 + init + 第一个 critique 大约 15–30 分钟；把 24 条命令用熟是几周的事。

费用：代码 Apache-2.0，检测器不调模型所以不产生模型费用；只有你让 Agent 执行 polish / bolder 这类命令时，才消耗你自己 Coding Agent 的额度。

安装与首次启用

1. 在项目根目录安装

npx impeccable install

安装器会自动检测你装了哪些编码工具，问你是装在当前项目还是全局，并在工具支持时提议装「设计 hook」——官方建议你接受这个 hook（原因见下一节）。装完重载你的编码工具。升级用 npx impeccable update；脚本化安装可以传 --providers=claude,codex,cursor 与 --scope=project|global。

2. 初始化项目上下文

在你的 Agent 里跑：

/impeccable init

Codex 上用 $impeccable init。它会读代码、问几个推不出来的问题，然后写 PRODUCT.md。之后每条命令都会读这份文件——这是效果差异最大的一步，跳过它等于让它盲改。

3. 给现有视觉系统建档（可选但推荐）

/impeccable document

写出 DESIGN.md，把已有的颜色、字体、间距规则固化下来，避免 Agent 每轮都重新发明。

成功判定

跑 /impeccable（不带参数）能列出命令清单，并且 PRODUCT.md 已经出现在仓库里，就算装好了。

首个任务：让 critique 给你的定价页打分，再按 P0/P1 修

1. 指一个小目标，别指整站：

   /impeccable critique the pricing cards
   

2. 它会按可用性启发式给分，并给出「先修哪个」的排序。

3. 想要技术面报告就换 audit：

   /impeccable audit the pricing page
   

   官方说明 audit 检查无障碍、性能、主题化与响应式，findings 按 P0（阻断）到 P3（打磨） 分级。

4. 按 P0 → P1 逐条修，改完再跑一次 critique 对比分数。

预期产出：一份带优先级的评审，加上修完后的第二份评审——两份之间的差异就是这个工具的价值，不是那份报告本身。

成功判定：critique 指出的问题里，至少有一条是你自己没注意到的真实问题；如果它只是复述你已知的东西，说明目标选得太大或 PRODUCT.md 写得太空。

初级用法

1. 用 quieten / bolder 做「一句话方向调整」

/impeccable bolder the pricing cards 会把「让它更抓人」翻译成一套针对该组件、该动作的 playbook，指向一个目标。窄目标效果明显好于整页——官方原话是「一个 section 被仔细审一遍，胜过整页扫一眼」。

2. 把常用命令 pin 成快捷方式

/impeccable pin audit

之后直接 /audit 就是它，适合每天都要跑的那一条。

3. 在终端或 CI 里只跑规则

不需要 Agent，也不需要模型：

npx impeccable detect src/
npx impeccable detect https://example.com
npx impeccable detect --json .
npx impeccable detect --github src/
npx impeccable detect --list-rules

退出码约定：2 表示有 findings，1 表示某个目标扫不了——CI 里按这两码分流，别把「扫不了」当「通过」。

高级玩法

1. 接受设计 hook，让 slop 在写出时就死掉

hook 会在 Agent 每次改 UI 文件时扫一遍，并把 findings 在「宣布完工」之前交回给 Agent。官方说得很直白：没有 hook 时，检测器只在有人记得跑的时候才跑。支持 hook 的是 Claude Code、Cursor、Codex、GitHub Copilot、Grok Build 与 Hermes Agent。

2. 用 live 模式在浏览器里挑变体

/impeccable live

打开你正在跑的 dev server，加一层 overlay，选元素 → 选方向 → 原地热替换变体，接受后写回源码。支持 Vite、Next、SvelteKit、Astro、Nuxt 与纯 HTML。只能在本地 checkout 上用，官方明确警告不要注入到已部署站点、也不要为了让它在生产跑而放宽 CSP。

3. 把规则收进 GitHub Actions

npx impeccable detect --github src/ 会把 findings 输出成 Actions 注解。配上 --json 还能自己算「本次 PR 新增了几条 slop」，做趋势而不只是门禁。

4. 用 ignores 处理「品牌例外」

npx impeccable ignores add-value overused-font Inter --reason "Brand font"

单文件级可以用注释关掉某条规则（官方给了 <!-- impeccable-disable overused-font: 导出品牌文档 --> 的形式）。例外要留理由，否则半年后没人知道为什么关的。

五个小技巧

1. 一次只指一个组件：the pricing cards 好过 the whole site。
2. 先 init 再 critique：没有 PRODUCT.md，评审只能拿通用启发式打分。
3. 源码 + URL 都扫：对比度、字号这类规则需要渲染态；只扫 JSX/TSX 会漏掉它们。
4. CI 里把退出码 2 与 1 分开处理：一个是「有问题」，一个是「没扫到」。
5. .impeccable/ 里只有一部分该进仓库：config.json、live/config.json、design.json、surfaces/*.md、critique/*.md 与 PRODUCT.md、DESIGN.md 要提交；截图、缓存、运行时状态按官方给的 .gitignore 片段排除。

常见踩坑

坑 1：装完命令不出现

现象：输 /impeccable 没反应。 原因：多数工具要重载才加载新技能；Codex 不是斜杠命令，要用 $impeccable。 解决：先重载；Codex 上改用 $ 前缀。

坑 2：hook 装上了却不执行

现象：改了 UI 文件，检测结果没有出现。 原因：三个工具需要额外信任步骤——Codex 里打开 /hooks 批准项目 hook（更新后可能还要再批一次）；Grok Build 要 /hooks-trust 或以 --trust 启动；Hermes Agent 里 hook 是插件，需要执行 hermes plugins enable impeccable-design-hook。 解决：按你的工具完成这一步；它是一次性的，但更新后可能重来。

坑 3：以为 hook 也会被「拒绝模型命令」拦住

现象：以为拒绝了 Agent 的命令就等于 hook 不跑。 原因：官方写明在 Claude Code 里，装好的 command hook 在模型自身命令被拒时仍然会执行，所以第一次编辑就可能触发引擎下载。无人值守跑之前要审一遍 hook，或用 --settings '{"disableAllHooks": true}' 临时关掉。 解决：把 hook 当独立的可执行权限来审，而不是当模型的附属行为。

坑 4：手动拷贝之后没有 hook、也没有子代理

现象：命令能用，但「自动检查」和子代理都没了。 原因：官方说明手动拷贝（下载 ZIP 或从仓库拷 skills/impeccable）会跳过 hook 与 subagents；OpenCode 还要额外把 .opencode/commands/impeccable.md 拷到项目里；Hermes 会要求你先 hermes skills trust（全局安装不需要）；Cursor 与 Gemini CLI 可能需要在设置里开启 Agent Skills；Trae 要重启。 解决：手动拷贝只当「装不上时的退路」，能力齐全仍走 npx impeccable install。

坑 5：只扫源码，却说「检测器漏报了低对比度」

现象：npx impeccable detect src/ 一切正常，页面上灰字看不清。 原因：低对比度、过小字号这类规则需要渲染后的页面才能算；源码扫描只跑模式规则。 解决：再扫一次你的 dev server 地址，例如 npx impeccable detect http://localhost:5173。

坑 6：把 live 模式用到已部署站点上

现象：想在生产页面上直接试用变体。 原因：live 模式会改写本地源码并可能执行 package.json 里的 impeccable:manual-edit-validate 脚本（用你的权限），官方明确要求只在本地 checkout 用。 解决：在本地 dev server 上用，别对生产站注入，也别为它放宽 CSP。

常见问题 FAQ

Q1：它是免费的吗？

A：代码是 Apache-2.0，检测器是确定性规则、不调模型，所以检测这条链路不产生费用。你让 Agent 执行 polish / bolder 这类命令时，吃的是你自己 Coding Agent 的额度。

Q2：它和 Anthropic 的 frontend-design 是什么关系？

A：官方在许可段写明「Impeccable started from Anthropic’s frontend-design skill」。也就是说它是在那条起点上继续做，加了命令体系、确定性规则集与多工具安装器；站内另有一条 anthropic-frontend-design（本站 8.5）可以对照。

Q3：62 条规则能替代无障碍审计吗？

A：不能。它是启发式规则集（覆盖 slop 痕迹与部分质量问题如拥挤的间距、跳级的标题层级），audit 会检查无障碍与性能，但不是拿 screen reader 与规范逐条认证。要出合规结论仍要做真机与辅助技术测试。

Q4：支持中文项目吗？

A：工具本身与语言无关，规则关注的是视觉与结构。文档与命令说明目前以英文为主，PRODUCT.md / DESIGN.md 你可以用中文写。

Q5：它在 Hermes Agent 里怎么用？

A：官方把它列为支持入口，hook 以插件形式提供：先 npx impeccable install 勾选 Hermes，再执行 hermes plugins enable impeccable-design-hook；项目内安装还需要 hermes skills trust。

Q6：会不会把我项目上传？

A：官方 telemetry 页说明：开启新设计时它会从 impeccable.style 的目录拉一组视觉方向，关掉 telemetry 不会停止这个请求；它停止的是「展示了哪些方向、你选了哪个」这条匿名记录。项目名、文件、代码与 PRODUCT.md 不会被发送。想彻底静默可以用 npx impeccable telemetry off、DO_NOT_TRACK=1 或配置里 "telemetry": false。

成本、权限与安全边界

• 成本：检测链路零模型成本；生成类命令（polish、bolder、live 等）花你自己 Agent 的额度。
• 权限：hook 是可执行代码，会在你编辑文件时运行；安装器还会写各工具的 hook 配置。无人值守环境里先审再开。
• 写盘：它会在项目里写 .impeccable/、PRODUCT.md、DESIGN.md；live 模式会改源码。
• 出网：开启新设计时会从官方目录拉取视觉方向（与 telemetry 开关无关）；目标是本地站点的扫描不会离开本机。
• 边界：它是「设计质量 + 一部分技术质量」的检查工具，不是安全审计、不是 WCAG 认证、也不保证视觉结果符合你的品牌——后者仍要人看。

进阶学习建议

1. 先读 docs 里「每条命令一页」的结构：impeccable.style/docs 给 24 条命令各一页，先挑三条你每周都会用到的（多数人会是 critique、polish、harden）读透，别一次读完。
2. 再读 context 与 detector 两页：context 讲 PRODUCT.md / DESIGN.md 怎么写才有用；detector 讲三种跑法与退出码。
3. 跟一遍真实案例：Neo Mirai 案例 是一个会议站从 mockup 到上线的全程；live 迭代教程 演示浏览器内挑选变体。
4. 把 npx impeccable detect --list-rules 的输出存成清单，逐条决定「保留 / 加 ignores 并写理由 / 关掉」，这份清单本身就是团队的视觉规范。
5. 接进 CI 再谈推广：先用 --github 出注解跑一周，再决定要不要设成阻断。
6. 遇到怪问题先 doctor：/impeccable doctor 会查过期上下文文件、没用到的设置与坏掉的 hook。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

未安装 Impeccable，未在 Claude Code / Codex / Hermes Agent 等任何 harness 里执行 install、init、critique 或 detect，未验证 62 条规则的实际命中率与误报率，也未实测 live 模式在 Astro / Next 项目上的写回行为。文中命令、规则数、支持工具与限制均转述自官方 README、官方站点与文档站，属官方自述。

参考链接

• 官方仓库 README：定位、24 条命令、检测器三种跑法、安装矩阵、telemetry、许可
• 官方站点：示例对照（same model, same brief）与入口
• 官方文档：每条命令独立页面、context、detector、doctor
• 隐私页：telemetry 发送范围
• Neo Mirai 案例：从 mockup 到上线的完整过程
• Apache-2.0 许可
• GitHub API：stars / forks / 未关闭 issue / 创建与最近推送时间