Impeccable：AI 编程智能体的设计语言 · 最全部署与使用指南（前 Google Chrome 团队 · 8 万星）

一句话定位：GitHub 开源项目 pbakaus/impeccable（86,928 ★，Apache-2.0）是前 Google Chrome 团队 Paul Bakaus 打造的设计智能体工具链——1 个 Skill、24 条设计命令、62 条确定性检测规则、无 API Key 的 Rust 引擎，让 AI 生成的网页告别"千篇一律的 SaaS 模板感"。

slogan：The design language that makes your AI harness better at design.（让你的 AI 工具链更懂设计的设计语言。）

仓库地址：https://github.com/pbakaus/impeccable · 官网：https://impeccable.style/

目录

• 一、官方跳转与下载链接
• 二、为什么要用 Impeccable
• 三、核心组成
• 四、24 条设计命令全解
• 五、官方图片
• 六、五种安装方式（完整部署）
• 七、各 AI 工具复制安装指南
• 八、使用方法
• 九、Detector 检测器 CLI
• 十、Design Hook 自动检查
• 十一、Live Mode 实时浏览器迭代
• 十二、Build Path：comp-first 与 code-first
• 十三、反模式清单（Anti-Patterns）
• 十四、支持的工具全家桶
• 十五、Telemetry 与隐私
• 十六、常见问题 FAQ
• 十七、参考链接汇总

一、官方跳转与下载链接

Git 克隆命令：

git clone https://github.com/pbakaus/impeccable.git
# 或浅克隆
git clone --depth 1 https://github.com/pbakaus/impeccable.git

快速开始： 在项目根目录运行 npx impeccable install，然后在 AI 编码工具里运行 /impeccable init。

二、为什么要用 Impeccable

Anthropic 的 frontend-design 是第一个被广泛使用的 Claude 设计 Skill，Impeccable 正源自它。

问题：每个模型都在同样的 SaaS 模板上训练。跳过设计指导，你会在每个项目看到同样的"AI 味"： - 到处用 Inter 字体 - 紫到蓝的渐变 - 卡片套卡片 - 彩色背景上的灰字 - 每个标题上方都放圆角方块图标

Impeccable 的解决方案：

三、核心组成

3.1 The Skill：impeccable

Skill 安装后就是一个命令：

/impeccable <command> <target>

每个新项目从这一句开始：

/impeccable init

init 检查项目，只询问产品持久真相中实质性的缺口，写出 PRODUCT.md。访客模式和视觉方向留到每个 surface 再选；既有或新构建的视觉系统单独记录在 DESIGN.md。

3.2 24 条命令

所有命令都通过 /impeccable 访问：

创建快捷方式：用 /impeccable pin <command> 创建独立快捷命令（如 pin audit 生成 /audit）。

四、24 条设计命令全解

4.1 使用示例

/impeccable audit blog           # 审计博客 hub + 文章页
/impeccable critique landing     # UX 设计评审
/impeccable polish settings      # 发布前最终打磨
/impeccable harden checkout      # 添加错误处理 + 边界情况

或者直接用描述调用：

/impeccable redo this hero section

4.2 常用命令详解

五、官方图片

5.1 官方图标

▲ 图 1：Chrome 扩展图标

▲ 图 2：插件图标

▲ 图 3：SVG 图标

5.2 推广图

六、五种安装方式（完整部署）

核心机制：Skill 本身不需要运行时。每个 Skill 副本自带一个小启动器（scripts/impeccable，Windows 上是 impeccable.cmd），运行 Impeccable 引擎——一个自包含二进制，要么就在启动器旁边，要么首次运行时下载到 ~/.impeccable/bin/。只有用 npx impeccable 安装器时才涉及 Node；手动和 Git 方式都不需要。

方式 1：CLI 安装器（推荐）

# 在项目根目录
npx impeccable install

安装器会显示检测到的 harness 目录（如 ~/.claude、~/.codex、~/.grok、~/.hermes、~/.veto、或项目级 .cursor），让你保留检测到的组合或自定义 providers，然后问是装进当前项目还是全局。

跳过交互选项（脚本化）：

npx impeccable install --providers=claude,codex,cursor,grok,hermes,veto --scope=project

在 Claude Code、Cursor、Codex、GitHub Copilot 和 Grok Build 上，还会为当前项目安装 provider 原生 hook 清单。

刷新已有安装：

npx impeccable update

Codex 用户注意：安装/更新后打开 /hooks 批准项目 hook。 Grok Build 用户注意：需要项目文件夹信任（/hooks-trust 或用 --trust 启动）。

方式 2：Git Submodule（团队协作）

git submodule add https://github.com/pbakaus/impeccable .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor
git add .gitmodules .impeccable .claude .cursor
git commit -m "Add Impeccable skills"

可用 providers：claude、cursor、gemini、codex、github、grok、hermes、opencode、pi、qoder、trae、trae-cn、rovo-dev、vibe、veto。

后续更新：

git submodule update --remote .impeccable
npx impeccable link --source=.impeccable --providers=claude,cursor

方式 3：插件安装（VS Code / Claude Code / Grok）

GitHub Copilot in VS Code：

code --install-extension renaissance-geek.impeccable

或从 Visual Studio Marketplace 安装。要求 VS Code 1.109.3+、Copilot Chat、可信本地工作区。

Claude Code：

/plugin marketplace add pbakaus/impeccable

然后打开 /plugin 从列表安装。

Grok Build：

grok plugin install pbakaus/impeccable#plugin --trust

方式 4：官网下载

访问 impeccable.style，为你的工具下载 ZIP，解压到项目。

方式 5：从仓库复制

Cursor：

cp -r dist/cursor/.cursor your-project/

Cursor 需要：设置→Beta 切换 Nightly 频道；设置→Rules 开启 Agent Skills。

Claude Code：

# 项目级
cp -r dist/claude-code/.claude your-project/
# 或全局
cp -r dist/claude-code/.claude/* ~/.claude/

OpenCode：

cp -r dist/opencode/.opencode your-project/

DeepSeek Harness：

# 项目级
cp -r dist/dsh/.dsh your-project/
# 或全局
mkdir -p "${DSH_HOME:-$HOME/.dsh}/skills"
cp -r dist/dsh/.dsh/skills/* "${DSH_HOME:-$HOME/.dsh}/skills/"

Gemini CLI：

cp -r dist/gemini/.gemini your-project/

需要：npm i -g @google/gemini-cli@preview；/settings 开启 "Skills"；/skills list 验证。

Codex CLI：

# 项目级
cp -r dist/agents/.agents your-project/
mkdir -p your-project/.codex
cp dist/codex/.codex/hooks.json your-project/.codex/hooks.json
# 或全局
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/

GitHub Copilot：

cp -r dist/github/.github your-project/

Trae：

# Trae 中国版
cp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/
# Trae 国际版
cp -r dist/trae/.trae/skills/* ~/.trae/skills/

Rovo Dev / Qoder / Mistral Vibe / Grok Build / Google Antigravity 均有对应 dist/ 目录复制命令（见 README 原文）。

七、各 AI 工具复制安装指南

八、使用方法

8.1 安装后即用

/impeccable audit        # 找问题
/impeccable polish       # 最终清理
/impeccable distill      # 去复杂化
/impeccable critique     # 全面设计评审

输入 /impeccable 单独一条可查看完整命令列表。

8.2 带目标参数

/impeccable audit the header
/impeccable polish the checkout form

8.3 固定常用命令

/impeccable pin audit    # 以后用 /audit 即可

注：Codex 用 skills 而非 /prompts: 命令——打开 /skills 或输入 $impeccable。

8.4 .gitignore 建议

运行命令时 Impeccable 会在 .impeccable/ 写工作文件（评审/打磨截图、live 模式状态、缓存）。建议加入 .gitignore（官方区块见 README），以下文件保留跟踪：

• .impeccable/config.json（统一共享配置）
• .impeccable/live/config.json（live 模式框架）
• .impeccable/design.json（共享设计规范）
• .impeccable/surfaces/*.md（路由/产物策略合同）
• .impeccable/critique/*.md（评审报告）

九、Detector 检测器 CLI

独立 CLI，无需 AI harness 即可检测反模式。npx impeccable 是小 shim，运行与 Skill 相同的引擎二进制；也可直接下载二进制放 PATH。

9.1 基本用法

npx impeccable detect src/                   # 扫描目录
npx impeccable detect index.html             # 扫描 HTML 文件
npx impeccable detect https://example.com    # 扫描 URL（需 Chrome/Chromium/Edge）
npx impeccable detect --json .               # CI 友好 JSON 输出
npx impeccable detect --github src/          # GitHub Actions 注解
npx impeccable detect --list-rules           # 列出检测规则目录
npx impeccable detect --no-config src/       # 原始扫描，忽略项目配置

9.2 Ignore 管理

npx impeccable ignores list                  # 查看忽略项
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

9.3 检测覆盖

检测器捕获 62 条确定性规则，覆盖两类问题： - AI 味（AI slop）：侧边标签边框、紫色渐变、弹跳缓动、暗色辉光； - 通用设计质量：行长度、拥挤内边距、小触控目标、跳级标题等。

9.4 退出码

十、Design Hook 自动检查

在 Claude Code、GitHub Copilot、Codex、Cursor 和 Grok Build 上，npx impeccable install/update 会安装 provider 原生 hook 清单。Hook 在直接 UI 文件编辑时运行 Impeccable 设计检测器，把发现回灌到智能体流程。

Hook 完全由启动器驱动，无需 Node 或其他运行时。首次编辑或 Stop 事件会下载缓存引擎。

十一、Live Mode 实时浏览器迭代

Live 模式通过开发服务器或本地静态 HTML 编辑本地 checkout。注意：不支持注入线上生产站点（包括 HTTPS 站点），不要为让它工作而禁用浏览器安全或削弱生产 CSP。

• 只在你信任本地运行的项目里用 live 模式；
• 应用复制编辑会自动运行 package.json 的可选 scripts["impeccable:manual-edit-validate"] 命令（用你的用户权限）——在不熟悉的 checkout 用 live 模式前先审查该脚本；
• 线上检查用 npx impeccable detect https://example.com 或浏览器扩展——只检查渲染页面，不做 live 变体编辑、不写回源码。

十二、Build Path：comp-first 与 code-first

新 surface 设计时，Impeccable 要么先出全保真 comp 再照着构建（comp-first），要么直接写代码、把意图写进 surface brief 的开发期方向合同、完成时检查（code-first）。

/impeccable init 会问一次并记录到 .impeccable/config.json：

{ "buildPath": "comp" }

可在 gitignored 的 .impeccable/config.local.json 覆盖（无图像生成能力的 harness 推荐 code）。

十三、反模式清单（Anti-Patterns）

Skill 内置明确的规避指导：

• ❌ 不要用滥用的字体（Arial、Inter、系统默认）
• ❌ 不要在彩色背景上用灰字
• ❌ 不要用纯黑/纯灰（永远加色调）
• ❌ 不要把一切都包进卡片、或卡片套卡片
• ❌ 不要用弹跳/弹性缓动（显得过时）

十四、支持的工具全家桶

十五、Telemetry 与隐私

新设计开始时，Skill 会请求 impeccable.style 的 roll API 从目录发一手"视觉世界"牌。除非选择退出，否则会上传匿名记录：发的是哪手牌、哪张牌胜出——这是目录学习"什么有效"的方式。

发送内容：roll key（随机）、范围、访客模式、重掷轮次、目录版本、胜出卡片类型、客户端版本。

绝不发送：项目名、文件、代码、PRODUCT.md、智能体写的方向名。

关闭方式：

npx impeccable telemetry off        # 存于 ~/.impeccable/config.json
# 或环境变量 DO_NOT_TRACK=1 / IMPECCABLE_NO_TELEMETRY=1
npx impeccable telemetry status     # 查看状态

项目级：.impeccable/config.json 里设 "telemetry": false。

十六、常见问题 FAQ

十七、参考链接汇总

免责声明：本文所有命令、规则、数据均整理自官方 GitHub 仓库 pbakaus/impeccable 的 README 原文，如仓库更新请以最新版本为准。作者 Paul Bakaus（前 Google Chrome 团队）。