Framework Impeccable 用 62 条规则矫正 AI 设计的通病

同一个模型，换个提示词，前端页面却总是那么眼熟：Arial 或 Inter 当万能字体、灰字压在彩色块上、纯黑纯灰从不加 tint、卡片里套卡片、弹性缓动动效显得廉价。这不是你的问题，是几乎所有编码代理都在同一批 SaaS 模板上训练出来的“肌肉记忆”。Anthropic 的 frontend-design 技能是第一个被广泛使用的设计技能，Impeccable 从它出发，把“反 AI 设计腔”做成了一套可量化、可自动检查的系统。

Impeccable 由 Paul Bakaus 维护，提供 1 个技能、24 条命令、浏览器实时迭代，以及 62 条确定性检测器规则（加 LLM 评审）。它的 CLI 与浏览器扩展能在不调用任何大模型、不需要 API key 的情况下，跑完那 62 条规则，直接告诉你页面哪里露怯。

项目基本信息

一、项目介绍

Impeccable 的核心是一套“设计语言 + 检测器”。它先用 /impeccable init 在一个叫 PRODUCT.md 的文件里记下产品的受众、目的、约束、语气与证据，让后续命令不用把表面视觉方向误当成事实。再提供 24 条共享设计词汇的命令：polish、audit、critique、distill、animate、bolder、quieter 等等，把“我想让 AI 改这里”变成一句可追溯的指令。

最硬核的是 62 条确定性检测器规则。它们不依赖大模型，CLI 与浏览器扩展直接本地运行，覆盖两类问题：AI 水军味（侧边 tab 边框、紫色渐变、弹性缓动、暗色辉光）与通用设计质量（行宽、拥挤内边距、过小点击区、跳过的标题层级）。每条规则都有稳定 id，可单独忽略。当前引擎版本为 engine-v0.1.17。

二、核心优势

第一，确定性优于玄学评审。62 条规则跑出来就是命中与否，CI 里能直接 npx impeccable detect --github 把结果标成 GitHub Actions 注解，团队不必再为“我觉得丑”争论。

第二，命令化工作流。24 条命令把设计动作拆细，且支持 /impeccable pin 把常用命令钉成独立快捷键（如 pin audit 得到 /audit）。

第三，编辑器内 hook。在 Claude Code、GitHub Copilot、Codex、Cursor、Grok Build 上，npx impeccable install 会写入原生 hook，你在直接改 UI 文件时它就在后台跑检测器，把发现回流进代理流程。

第四，无运行时绑架。技能自带一个自包含引擎二进制，npx 只是个壳；手动与 Git 方式完全不需要 Node。CLI 也独立于 AI harness，纯静态检查零成本。

三、适用场景

适合“用编码代理做前端、但产出总带着 AI 通病”的所有团队。最典型的是把 Impeccable 接进 Claude Code 的编辑 hook，让每次改动 UI 都被自动 lint，再人工决定改不改。

它也适合做设计系统落地：用 /impeccable document 从现有项目代码生成根 DESIGN.md，/impeccable extract 抽可复用组件与 token。对需要在多 agent（Claude Code、Cursor、Gemini CLI、Codex、Trae 等十几种工具）之间统一设计标准的团队，一份 Impeccable 配置能到处复用。

四、安装教程

推荐用 CLI 安装器，在项目根目录运行：

npx impeccable install

它会探测已装的 harness 文件夹（如 ~/.claude、~/.codex、.cursor），让你选全局还是项目级安装。刷新已有安装：

npx impeccable update

常见报错与处理：

npx: command not found

没装 Node。装 Node 18+ 即可；或走 Git submodule / 手动复制方式，那两条路径完全不需要 Node。

Codex: hook not firing

Codex 需要装完后在 /hooks 里手动批准项目 hook。因为 Codex 按 hook 定义跟踪信任，更新改了 .codex/hooks.json 可能要再批一次。

Grok Build: scripts not running

需要项目文件夹信任：运行 /hooks-trust 或带 --trust 启动。否则 .grok/hooks/ 脚本不会执行。

Git submodule 方式（团队 vendored 更新）：

git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor

五、使用示例

初始化一次，记下产品事实：

npx impeccable install
/impeccable init

随后把设计动作交给命令。例如审计博客相关页面：

/impeccable audit blog
/impeccable critique landing
/impeccable polish settings
/impeccable harden checkout

纯 CLI 也能脱离 AI 直接扫：

npx impeccable detect src/                # 扫描目录
npx impeccable detect index.html          # 扫描单文件
npx impeccable detect https://example.com # 用本机 Chrome 扫渲染后的页面

预期输出（节选）：

[warn] overused-font: "Inter" used in 12 selectors (anti-pattern)
[warn] card-in-card: nested .card inside .card at src/components/hero.tsx:42
[error] touch-target: button "订阅" is 28px < 44px minimum
exit 2 (primary findings present)

六、常见问题

问：62 条规则会误伤我的品牌设计吗？
答：可以精准豁免。用 npx impeccable ignores add-value overused-font Inter --reason "Brand font" 把品牌字体加进忽略；也支持文件级、行级的内联注释豁免。

问：需要 API key 吗？
答：确定性检测器不需要任何 key，零成本本地跑。仅当用到 LLM 评审类检查时才涉及模型。

问：和 Hallmark 什么关系？
答：两者都在治 AI 设计腔，但角度不同：Hallmark 偏“主题材质 + 构建流程”，Impeccable 偏“可量化的 62 条规则 + 命令化工作流 + hook”。可以并存。

问：CI 里怎么用？
答：npx impeccable detect --github src/ 把发现标成 Actions 注解；--json 给机器可读结果，--no-config 做裸扫描。

七、总结

Impeccable 把“AI 前端设计质量”从主观评审变成了可执行、可进 CI 的确定性检查：1 个技能、24 条命令、62 条规则，覆盖从字体到点击区的通病。Apache 2.0 协议，可商用。建议先 npx impeccable install 接上你的主力 harness，再用 /impeccable audit 扫一遍现有项目，你会惊讶于它挑出的那些“自己一直没注意”的细节。