分享篇: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)、同一句需求——「利古里亚海岸一栋十四间房的家庭旅馆」。没装它,得到的是奶油底、细衬线加斜体重音、两个药丸按钮加扁平插画的「得体默认」;装了它,整页围绕一张图展开——夜里从海上看悬崖上的房子,配压缩标题和底部月份条。

同一模型同一需求,左为未使用 Impeccable,右为使用后

判断很明确:它的强项是改已经存在的界面,指着一个页面或一个组件反复迭代;从零建新页也能做,但作者自己说那是更难的模式,专门写了文档讲怎么把输出调好。

二、装一次,然后「命令 + 目标」

安装就一行:

1
npx impeccable install

安装器会探测你机器上有哪些编码工具(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
2
3
4
5
/impeccable critique the onboarding flow
/impeccable quieter the landing page
/impeccable polish settings
/impeccable harden checkout
/impeccable redo this hero section

常用的命令可以钉成快捷方式:/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。


分享篇:Impeccable —— 给编码 Agent 一套设计词汇,把「AI 味」拦在提交之前
https://blog.luluvip.cn/2026/11/19/分享篇-Impeccable-给编码Agent的设计词汇表/
作者
Sagit.
发布于
2026年11月19日
许可协议