分享篇:Impeccable —— 给编码 Agent 一套设计词汇,把「AI 味」拦在提交之前
分享篇:Impeccable —— 给编码 Agent 一套设计词汇,把「AI 味」拦在提交之前
项目地址:https://github.com/pbakaus/impeccable | 许可:Apache-2.0 | Star:约 11.3 万(113,000) | 最新版本:skill-v4.10.0(2026-11-18)
一、它治的是「AI 味」,不是「不会设计」
让 agent 做一个页面,不给额外提示,出来的东西往往长一个样:Inter 走天下、紫蓝渐变、卡片套卡片、彩色底上堆灰字、每个标题上面顶一个圆角方形图标。换模型、换项目,还是这套。
Impeccable 的思路不是教 agent「什么是好设计」——那太虚——而是给两样具体的东西:
- 一组动词。
bolder放大胆、quieter降噪、colorize上色、typeset修字体层级、polish收尾、audit做技术体检。你说/impeccable bolder the pricing cards,它加载一份专门针对「放大胆」的操作手册,只作用在你指的那块定价卡上,而不是让模型自由发挥。 - 一个不改也会响的裁判。62 条确定性规则扫描 UI 文件,专抓上面那些套路,外加拥挤留白、跳过标题层级这类质量问题。不用 LLM,不要 API key,本地跑。
README 里那张对比图很能说明问题:同一个模型(Fable 5.1)、同一句需求——「利古里亚海岸一栋十四间房的家庭旅馆」。没装它,得到的是奶油底、细衬线加斜体重音、两个药丸按钮加扁平插画的「得体默认」;装了它,整页围绕一张图展开——夜里从海上看悬崖上的房子,配压缩标题和底部月份条。

判断很明确:它的强项是改已经存在的界面,指着一个页面或一个组件反复迭代;从零建新页也能做,但作者自己说那是更难的模式,专门写了文档讲怎么把输出调好。
二、装一次,然后「命令 + 目标」
安装就一行:
1 | |
安装器会探测你机器上有哪些编码工具(Claude Code、Cursor、Codex CLI、GitHub Copilot、Devin、Replit Agent、Gemini CLI、OpenCode、Trae、DeepSeek Harness 等一大串),问你是装到当前项目还是全局,并在支持的工具里装上设计 hook。装完重载工具,在项目根跑 /impeccable init(Codex 里是 $impeccable init)。
init 读你的代码,只问它推不出来的东西(给谁用、要做什么、有什么约束),然后写一份 PRODUCT.md——后面所有命令都读它。再跑一次 /impeccable document,会把你现有的视觉体系记进 DESIGN.md,保证后续改动不跑偏。这两份文件建议提交进仓库。
之后就是「命令 + 目标」,目标越窄效果越好:
1 | |
常用的命令可以钉成快捷方式:/impeccable pin audit 之后直接 /audit。24 个命令分五组:
| 组别 | 命令 | 干什么 |
|---|---|---|
| 掌舵 | bolder quieter distill colorize typeset layout animate delight overdrive |
调风格:放大胆、降噪、做减法、上色、修排版、调节奏、加动效、加个性、上着色器与弹簧物理 |
| 评审 | critique audit |
打分式 UX 评审 / 技术质量报告(可访问性、性能、主题、响应式) |
| 收尾 | polish harden clarify adapt optimize onboard |
上线前最后一轮:边缘情况、文案、适配、性能、首次体验 |
| 实时迭代 | live generate |
浏览器里选元素循环变体 / 直接生成某个元素的多个版本 |
| 规划与 setup | shape init document extract craft |
先规划 UX、写上下文文件、抽取设计系统(craft 是旧别名) |
第 24 个
craft已经是弃用别名,等价于普通构建请求。
三、检测器:三条路,总有一条能拦住
62 条规则本身跟 agent 无关,单独用也行。三种跑法覆盖不同时机:
| 方式 | 触发时机 | 适合 |
|---|---|---|
| 设计 hook | agent 每次改 UI 文件时,在它宣布完成前把问题回传 | 日常开发,真正拦住 slop 的主战场 |
| CLI / CI | npx impeccable detect src/ 手动跑,或进 GitHub Actions |
需要门禁、要留痕、要机器可读输出 |
| 浏览器扩展 | 在任何线上页面叠加检测结果 | 审查别人或自己的已上线页面 |
CLI 的输出格式挺全:--json 机器可读、--github 生成 Actions 注解、--sarif 出 SARIF 2.1.0 给 GitHub code scanning、--list-rules 列全部规则。退出码是刻意设计的——2 表示「发现问题」,1 表示「某个目标扫不了」,0 才是干净。CI 里要让 2 也能上传 SARIF(|| test $? -eq 2),否则发现问题的那次扫描反而丢了日志,旧告警清不掉。
规则按 slop(AI 套路)和 quality(质量问题)两类打标,但作者明确说这个分类只用于展示和过滤,不影响排序与退出码。要放行某个品牌字体,用 npx impeccable ignores add-value overused-font Inter --reason "Brand font";临时关某条规则,在文件里写 <!-- impeccable-disable overused-font: exported brand doc -->。注意这条注释会「吃掉」之后遇到的下一条同类问题,所以要用 --report-unused-ignores 定期清理失效的豁免。
live 模式值得单独提一句:它打开你正在跑的 dev server,加一层浮层,选中元素后原地热替换变体,接受就写回源码。支持 Vite、Next、SvelteKit、Astro、Nuxt 和普通 HTML。
四、适合谁,不适合谁
适合:
- 已经在用 AI 编码工具、且常嫌产出「一眼 AI」的前端开发者
- 团队里想统一设计基线、把体验评审变成可重复流程的人
- 想要一个不需要 LLM、能塞进 CI 的确定性 UI 检查器的人
不适合 / 要留意:
- 想让它替你做完整设计决策——它是「词汇表」和「评审员」,不是设计师
- 只想画几张静态页面、不打算装任何编码 agent 的人:核心命令价值发挥不出来
- 后端、纯数据项目:整套规则都是围绕 HTML/CSS 和浏览器渲染的
- 对 hook 敏感的环境:hook 在模型审批流程之外运行,第一次编辑就可能下载引擎二进制;无人值守跑之前建议先看一眼装进去了什么,或用
--settings '{"disableAllHooks": true}'关掉
五、几个已知的坑
- Live 模式只改本地 checkout。别把它注进已部署站点,也别为了让它工作去削弱生产环境的 CSP。
- Apply 会绕过审批。live 会话里点 Apply,如果没有 chat agent 在轮询,它会从 PATH 里找
codex(没有就claude)并执行,且关掉审批、权限检查和沙箱。不熟悉的仓库里,先设IMPECCABLE_LIVE_COPY_AGENT=chat或off。 - 遥测关了也还是会请求目录。关遥测只停止记录「展示了哪些方向、你选了哪个」,不阻止启动时拉取视觉方向。项目名、文件、代码不会发送,但网络请求本身还在。
- DeepSeek Harness 有个路径条件:只有
DSH_HOME在你的 home 目录内,install/update才会管理全局副本。 - 手动复制会跳过 hook 和子 agent。想用完整能力还是走
npx impeccable install;另外 Node 只是npx需要,真正的引擎是自包含二进制,首次下载到~/.impeccable/bin/。
项目源自 Anthropic 的 frontend-design skill,Apache-2.0,作者 Paul Bakaus。完整文档在 impeccable.style/docs。