Impeccable

项目概述

Impeccable 是面向 AI 编程代理的前端设计规范工具，提供一套设计技能、24 条命令、浏览器实时迭代能力，以及 62 条确定性检测规则，用于识别常见的人工智能生成式界面问题。

工具旨在避免千篇一律的 SaaS 视觉模式，例如滥用 Inter 字体、紫蓝渐变、卡片嵌套、彩色背景上的灰色文字，以及标题上方重复出现圆角方形图标。

核心能力

初始化与设计上下文

每个项目可先执行：

/impeccable init

init 会检查现有项目，收集目标用户、产品目的、使用场景、限制条件、品牌语气和证据等长期有效信息，并写入 PRODUCT.md。具体页面的视觉方向以及现有设计系统则分别记录在 DESIGN.md 或页面策略文件中，避免把产品事实与表面样式混为一谈。

设计命令

所有能力统一通过 /impeccable 调用，主要包括：

/impeccable shape landing       # 编码前规划界面
/impeccable critique landing    # 审查层级、清晰度与体验
/impeccable audit blog          # 检查可访问性、性能和响应式问题
/impeccable polish settings     # 发布前统一设计系统并完成收尾
/impeccable harden checkout     # 补充错误处理、国际化与边界场景
/impeccable distill dashboard   # 删除视觉与结构冗余
/impeccable live                # 在浏览器中迭代视觉方案

其他命令用于增强或收敛视觉风格，包括 bolder、quieter、animate、colorize、typeset、layout、adapt、optimize 和 overdrive 等。常用命令可固定为独立快捷方式：

/impeccable pin audit

此后可直接使用 /audit。

架构与工作方式

Impeccable 采用“设计优先”或“代码优先”两种路径。设计优先先生成高保真视觉稿，再按稿实现，适合落地页和展示型页面；代码优先直接将设计意图写入开发约束，并在完成时检查，适合应用界面和文档。

项目初始化后，可通过以下配置选择路径：

{ "buildPath": "comp" }

允许值为 comp 和 code。机器级覆盖应写入未纳入版本控制的 .impeccable/config.local.json。

工具本身不依赖 Node 运行时。技能包包含启动器，并调用位于同一目录中的引擎二进制文件；若尚未安装，则首次运行时下载到 ~/.impeccable/bin/。Node 仅用于执行 npx 安装命令。

安装与更新

推荐在项目根目录执行：

npx impeccable install
/impeccable init

安装器可检测 Claude Code、Codex、Cursor、Grok、Hermes、Veto 等环境，并支持脚本化配置：

npx impeccable install \
  --providers=claude,codex,cursor \
  --scope=project

更新现有安装：

npx impeccable update

团队也可使用 Git 子模块固定版本：

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

更新后需重新加载 AI 工具。Codex 用户还必须在 /hooks 中批准项目钩子；Grok Build 需要通过 /hooks-trust 或启动参数信任项目目录。

确定性检测 CLI

无需 AI 环境也可扫描本地文件或线上页面：

npx impeccable detect src/
npx impeccable detect index.html
npx impeccable detect https://example.com
npx impeccable detect --json .
npx impeccable detect --github src/
npx impeccable detect --list-rules

检测范围包括过窄的文本行、拥挤间距、过小触控区域、标题层级缺失、禁用式字体、紫色渐变、弹跳缓动和暗色发光等问题。退出码含义为：0 表示没有主要问题，2 表示发现问题，1 表示目标无法完整扫描。

规则可在 .impeccable/config.json 中配置：

{
  "detector": {
    "ignoreRules": [],
    "ignoreFiles": ["src/legacy/**"],
    "ignoreValues": [],
    "designSystem": { "enabled": true }
  }
}

单文件例外可使用内联标记：

<!-- impeccable-disable overused-font: 导出品牌规范 -->

设计钩子与实时模式

Claude Code、GitHub Copilot、Codex、Cursor 和 Grok Build 可在界面文件被编辑后自动运行检测器，并将结果反馈给代理。钩子配置分别保存在各工具对应的项目清单中；部分平台会在任务结束时执行更深层检查。

实时模式只能操作可信的本地开发服务器或本地静态页面，不支持向生产站点注入辅助脚本。生产环境仅可进行只读检测：

npx impeccable detect https://example.com

不得为启用实时编辑而关闭浏览器安全策略或削弱生产环境的 CSP。

遥测与版本控制

启动新设计时会请求视觉方案目录，这是功能正常运行的必要步骤。默认匿名记录随机抽取结果、方案类别、客户端版本和随机选择标识，不发送项目名称、源代码、文件内容或 PRODUCT.md。

可检查或关闭遥测：

npx impeccable telemetry status
npx impeccable telemetry off

也可设置环境变量 DO_NOT_TRACK=1 或 IMPECCABLE_NO_TELEMETRY=1。

.impeccable/ 中的截图、审查缓存、会话状态和个人配置通常不应提交；应保留共享配置、设计规范、页面策略与审查报告。README 提供的 .gitignore 片段可自动区分这些文件。对于此前已提交的临时文件，需使用 git rm --cached <路径> 停止跟踪。