impeccable

Impeccable

面向 AI 编码代理 (AI coding agents) 的设计指引。1 项 skill，23 条命令，浏览器实时迭代，以及 46 条用于 AI 生成前端设计的确定性检测器规则 (deterministic detector rules)。

快速开始： 在项目根目录运行 npx impeccable install，然后在 AI 编码工具内运行 /impeccable init。完整文档：impeccable.style。

为什么选择 Impeccable？

Anthropic 的 frontend-design 是首个为 Claude 广泛使用的设计 skill（设计技能）。Impeccable 正是以此为基础发展而来。

每个模型都在相同 SaaS 模板上训练过。跳过指引，你会在每个项目上得到同样的老套路：到处用 Inter 字体、紫蓝色渐变、卡片嵌套卡片、彩色背景上的灰色文字、标题上方圆角方形图标方块。

Impeccable 增加了：

• 一套设置流程。/impeccable init 写入 PRODUCT.md 并提供 DESIGN.md，后续命令能了解受众、品牌/产品赛道、语调、反参考案例 (anti-references)、色彩、字体和组件。
• 23 条命令。 与 AI 共享的设计词汇：polish、audit、critique、distill、animate、bolder、quieter 等等。
• 46 条确定性检测器规则 (deterministic detector rules)，加上纯 LLM 的评审检查 (critique checks)。CLI 和浏览器扩展无需 LLM 和 API Key 即可运行确定性规则。

包含内容

Skill：impeccable

该 skill 安装为一条命令：

/impeccable <command> <target>

用以下命令开始每个新项目：

/impeccable init

init 会询问界面是品牌类（营销、落地页、作品集）还是产品类（应用 UI、仪表盘、工具），然后写入每条后续命令都会读取的设计上下文。

23 条命令

所有命令通过 /impeccable 访问：

命令	作用
/impeccable craft	完整“先构思再构建”流程，附带视觉迭代
/impeccable init	一次性设置：收集设计上下文，写入 PRODUCT.md 和 DESIGN.md，配置实时模式，推荐下一步操作
/impeccable document	从现有项目代码生成根目录 DESIGN.md
/impeccable extract	将可复用组件和令牌 (tokens) 提取到设计系统中
/impeccable shape	在写代码之前规划 UX/UI
/impeccable critique	UX 设计评审：层次、清晰度、情感共鸣
/impeccable audit	运行技术质量检查（可访问性、性能、响应式）
/impeccable polish	最终打磨、设计系统对齐，为发布做好准备
/impeccable bolder	增强乏味的设计
/impeccable quieter	调低过于大胆的设计
/impeccable distill	提炼至精髓
/impeccable harden	错误处理、国际化、文本溢出、边界情况
/impeccable onboard	首次运行流程、空状态、激活路径
/impeccable animate	添加有意义的动效
/impeccable colorize	引入策略性色彩
/impeccable typeset	修正字体选择、层次结构、字号
/impeccable layout	修正布局、间距、视觉节奏
/impeccable delight	添加愉悦瞬间
/impeccable overdrive	添加技术上极其惊艳的效果
/impeccable clarify	改进不清晰的 UX 文案
/impeccable adapt	适配不同设备
/impeccable optimize	性能改进
/impeccable live	视觉变体模式：在浏览器中迭代元素

使用 /impeccable pin <command> 创建独立快捷方式（例如 pin audit 创建 /audit）。

使用示例

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

或者直接使用 /impeccable 加上描述：

/impeccable redo this hero section

反模式 (Anti-Patterns)

该 skill 包含明确应避免的指导原则：

• 不要使用过度使用的字体（Arial、Inter、系统默认字体）
• 不要在彩色背景上使用灰色文字
• 不要使用纯黑/纯灰（始终加色调）
• 不要把所有内容都套进卡片，或嵌套卡片
• 不要使用弹跳/弹性缓动（感觉过时）

实际效果

访问 Neo Mirai 案例研究，查看一个真实项目使用 Impeccable 命令改造前后的对比案例。

安装

选项 1：CLI 安装器（推荐）

在项目根目录运行：

npx impeccable install

它会显示检测到的 harness 文件夹（例如 ~/.claude、~/.codex 或项目本地 .cursor），让你保留检测到的集合或自定义提供者，然后询问是安装到当前项目还是全局安装。使用 --providers=claude,codex,cursor 和 --scope=project|global 可在脚本中跳过这些选择。在 Claude Code、Cursor 和 Codex 上，它还会为当前项目安装原生 hook 清单。适用于 Cursor、Claude Code、Gemini CLI、Codex CLI、Grok Build 及其他所有支持的工具。之后需要重新加载 harness。

要刷新已有安装，运行：

npx impeccable update

Codex 用户在安装或更新后应打开 /hooks，并在提示时批准项目 hook。Codex 按 hook 定义跟踪信任，因此更新如果改变了 .codex/hooks.json，可能需要再次批准。

选项 2：Git 子模块

对于希望将 Impeccable 加入 vendor 并通过 Git 更新的团队，可将此仓库添加为子模块，并将编译后的提供者构建链接到你的 harness 文件夹中：

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"

使用你项目所需的提供者，例如 claude、cursor、gemini、codex、github、opencode、pi、qoder、trae、trae-cn 或 rovo-dev。该命令会从 .impeccable/dist/universal/ 链接各个 skill 文件夹，除非传递 --force，否则不会触碰已有的真实 skill 目录。

以后更新：

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

选项 3：插件安装

Claude Code：

/plugin marketplace add pbakaus/impeccable

仅限 Claude Code。添加市场后，打开 /plugin 并从列表中安装 Impeccable。

Grok Build：

grok plugin install pbakaus/impeccable --trust

仅限 Grok Build。然后在 Grok 会话中运行 /impeccable init。

选项 4：从网站下载

访问 impeccable.style，下载适用于你工具的 ZIP 文件，并解压到项目中。

选项 5：从仓库复制

Cursor：

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

注意： Cursor skills 需要设置：

1. 在 Cursor Settings → Beta 中切换到 Nightly 频道
2. 在 Cursor Settings → Rules 中启用 Agent Skills

了解更多关于 Cursor 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/

Pi：

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

Gemini CLI：

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

注意： Gemini CLI skills 需要设置：

1. 安装预览版：npm i -g @google/gemini-cli@preview
2. 运行 /settings 并启用 "Skills"
3. 运行 /skills list 验证安装

了解更多关于 Gemini CLI skills

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

# 或为用户级安装 skill。在每个希望设计 hook 运行的项目中复制 .codex/hooks.json。
mkdir -p ~/.agents/skills
cp -r dist/agents/.agents/skills/* ~/.agents/skills/

资源生产者子代理 (asset-producer subagent) 内嵌在 skill 自身的 agents/ 文件夹中，Codex 会自动发现，无需单独复制 .codex/agents/。Hook 是项目本地的，因为 Codex 从受信任项目配置旁边的 .codex/hooks.json 中发现 hook。

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/

注意： Trae 有两个版本，配置目录不同：

• Trae 中国版：~/.trae-cn/skills/
• Trae 国际版：~/.trae/skills/

复制后，重启 Trae IDE 以激活 skills。

Rovo Dev：

# 项目级
cp -r dist/rovo-dev/.rovodev your-project/

# 或全局（适用于所有项目）
cp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/

Qoder：

# 项目级
cp -r dist/qoder/.qoder your-project/

# 或全局（适用于所有项目）
cp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/

用法

安装后，所有命令都通过单条 /impeccable skill 运行：

/impeccable audit        # 查找问题
/impeccable polish       # 最终清理
/impeccable distill      # 去除复杂性
/impeccable critique     # 完整设计评审

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

大多数命令接受可选参数来聚焦特定区域：

/impeccable audit the header
/impeccable polish the checkout form

如果某个命令经常使用，可以通过 /impeccable pin audit 将其固定，获得 /audit 作为独立快捷方式。

注意： Codex 在此使用 skills，而非 /prompts: 命令。打开 /skills 或输入 $impeccable。仓库本地安装位于 .agents/skills/；用户级安装位于 ~/.agents/skills/。GitHub Copilot 使用 .github/skills/。如果新安装的 skill 未出现，请重启工具。

将 .impeccable 排除在 Git 之外

运行命令时，Impeccable 会在 .impeccable/ 下写入工作文件：评审和打磨截图、实时模式会话和预览状态、运行时缓存以及每个开发者的配置。其中大部分是临时文件，不应提交，少数文件是共享的项目产物，应留在仓库中。在项目的 .gitignore 中添加以下块：

# impeccable-ignore-start
# 临时输出、运行时状态和每个开发者的覆盖。
# 未锚定：.impeccable 可能位于仓库根目录或嵌套工作区下
# （apps/web/.impeccable/...）；锚定模式会漏掉它。
# 共享产物保持跟踪：config.json、live/config.json、
# design.json、critique/*.md。
.impeccable/config.local.json
.impeccable/hook.cache.json
.impeccable/hook.pending.json
.impeccable/*.png
.impeccable/live/server.json
.impeccable/live/sessions/
.impeccable/live/previews/
.impeccable/live/annotations/
.impeccable/live/cache/
.impeccable/live/manual-edit-apply-transaction.json
.impeccable/live/manual-edit-events.jsonl
.impeccable/live/manual-edit-evidence/
.impeccable/live/pending-manual-edits.json
.impeccable/live/deferred-svelte-component-accepts.json
.impeccable/live/*.png
# impeccable-ignore-end

该块以 # impeccable-ignore-start / # impeccable-ignore-end 标记包裹，方便你识别和后续刷新。这些模式是有意未锚定的：在 monorepo 中，活跃项目（及其 .impeccable/ 目录）通常位于嵌套工作区路径下，例如 apps/web/，根锚定模式会漏掉它。

保留这些文件不被忽略（它们是共享的项目产物，不要添加到 .gitignore）：

• .impeccable/config.json（统一的共享配置）
• .impeccable/live/config.json（实时模式框架连接）
• .impeccable/design.json（共享设计规范）
• .impeccable/critique/*.md（评审报告）

如果在添加该块之前已经提交了临时文件（如截图、config.local.json），.gitignore 不会自动取消跟踪。运行 git rm --cached <path> 可在不删除本地副本的情况下停止跟踪。

设计 Hook

在 Claude Code、GitHub Copilot、Codex 和 Cursor 上，npx impeccable install 和 npx impeccable update 会在安装 skill 负载的同时安装一个提供者原生 hook 清单。该 hook 在直接 UI 文件编辑时运行 Impeccable 设计检测器，并将发现结果反馈到代理流程中。Claude Code、GitHub Copilot 和 Codex 在编辑后显示发现结果。Cursor 会在不良写入生效之前阻止它们。

已安装的 hook 表面：

• Claude Code：.claude/settings.local.json（已 gitignore，机器本地）运行 ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs。移动到共享 settings.json 中的 hook 也会被生效。
• GitHub Copilot：.github/hooks/impeccable.json（已提交，Copilot CLI 和云代理共享）运行 .github/skills/impeccable/scripts/hook.mjs。一旦文件位于仓库默认分支且文件夹被信任，Copilot CLI 会激活它。
• Cursor：.cursor/hooks.json 运行 .cursor/skills/impeccable/scripts/hook-before-edit.mjs。
• Codex：.codex/hooks.json 运行 .agents/skills/impeccable/scripts/hook.mjs。

安装器会保留不相关的 hook 条目和设置。如果 hook 清单格式错误，安装/更新默认会中止；使用 --force 重新运行可将畸形文件备份为 .bak 并替换。

在交互式 install/update 中，Impeccable 会解释 hook 并提供安装选项（默认是）。你的选择会按开发者记录在已 gitignore 的 .impeccable/config.local.json 中，因此不会重复询问；--no-hooks 可在本次运行中跳过而不记录任何内容。Hook 生命周期设置位于 .impeccable/config.json 的 hook 键下；检测器忽略项位于 detector 下，由 /impeccable hooks 和 npx impeccable detect 共享。

调试时，在 .impeccable/config.json 中设置 hook.auditLog 为一个路径（或使用旧的 IMPECCABLE_HOOK_LOG 环境变量），每次 hook 调用会写入一行 NDJSON。正常情况下省略即可。

Codex 需要一个 Impeccable 不能安全跳过的平台步骤：安装或更新后打开 /hooks 并批准项目 hook。没有针对此 hook 的 Codex marketplace/plugin 安装流程。

完整 hook 文档：impeccable.style/docs/hooks。

手动复制命令是回退/调试指令。正常路径是：

npx impeccable install
npx impeccable update

CLI

Impeccable 包含一个独立的 CLI，用于在无需 AI harness 的情况下检测反模式 (anti-patterns)：

npx impeccable detect src/                   # 扫描目录
npx impeccable detect index.html             # 扫描 HTML 文件
npx impeccable detect https://example.com    # 扫描 URL（需要 Puppeteer）
npx impeccable detect --json .               # CI 友好的 JSON 输出
npx impeccable detect --no-config src/       # 原始扫描，忽略项目配置/上下文
npx impeccable ignores list                  # 显示检测器忽略项
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "品牌字体"

检测器能捕捉 46 个确定性问题，涵盖 AI 惯用套路（边栏标签边框、紫色渐变、弹跳缓动、暗色发光）以及通用设计质量（行长度、拥挤的内边距、小的触摸目标、跳过的标题等）。

默认情况下，detect 尊重与设计 hook 相同的 .impeccable/config.json 和 .impeccable/config.local.json 检测器配置：detector.ignoreRules、detector.ignoreFiles、detector.ignoreValues 以及 detector.designSystem.enabled。Hook 生命周期设置如 hook.enabled 仅影响自动 hook 执行。

对于希望随单个文件而非仓库配置移动的豁免，可在文件中添加内联注释：<!-- impeccable-disable overused-font: 导出的品牌文档 -->。该标记支持任何注释语法，作用范围是整个文件（或者使用 impeccable-disable-line / impeccable-disable-next-line 限制为一行），并且可以通过 --no-inline-ignores 或 --no-config 绕过。

完整检测器文档：impeccable.style/docs/detector。

支持的工具

• Cursor
• Claude Code
• GitHub Copilot
• Gemini CLI
• Codex CLI
• Grok Build
• OpenCode
• Pi
• Kiro
• Trae
• Rovo Dev
• Qoder

社区与生态

加入社区和生态讨论：

• GitHub Discussions：报告 bug、请求功能、帮助新手。
• npm 上的 Impeccable：获取 CLI、关注发布、点赞包。
• 在 Twitter 上关注 @pbakaus，获取发布说明、示例 lint 报告以及新规则的视频亮点。

贡献

参见 DEVELOP.md 了解贡献指南和构建说明。

许可证

Apache 2.0。参见 LICENSE。

---

由 Paul Bakaus 创建。