1. 项目缘起与核心定位
1.1 一个被名字耽误的实用工具
第一次看到 "impeccable" 这个词，很多人会愣一下——这词儿啥意思？翻译过来大概是“无可挑剔的”“完美的”。拿它当项目名，多少有点自卖自夸的嫌疑。但真正用过之后你会发现，这名字起得其实挺克制，因为它做的事情确实挑不出什么毛病。
impeccable 本质上是一个面向 AI coding agents 的前端设计增强工具。说人话就是：你平时用 Claude Code、Codex CLI、Cursor 这类 AI 编程助手写前端代码，它们生成的界面往往能用但不好看——间距随意、配色辣眼、层次混乱。impeccable 就是来解决这个问题的。它通过一套精心设计的规则和提示词工程，让 AI 在生成前端代码时自动遵循专业设计师的审美标准。
这个项目适合谁？三类人最需要它：一是独立开发者，一个人要兼顾前后端，设计功底不够扎实；二是小团队里的全栈工程师，没有专职设计师配合；三是任何经常用 AI 写前端、但每次都要手动调样式调到崩溃的人。如果你属于以上任何一种，impeccable 值得花时间了解一下。
1.2 它到底解决了什么痛点
AI 写前端代码有个通病：功能逻辑没问题，但视觉呈现一言难尽。我拿几个实际场景举例你就明白了。
让 AI 写一个登录表单，它给你生成的东西大概率长这样：输入框紧贴在一起，没有呼吸感；按钮颜色是默认的蓝色，跟品牌色毫无关系；错误提示直接堆在表单下面，没有任何视觉引导。功能上能用，但用户一看就觉得“这是个半成品”。
再比如让 AI 写一个数据展示卡片，它会把所有信息平铺直叙地堆上去，标题、数值、说明文字之间没有层级对比，用户扫一眼根本抓不住重点。你让它改，它改完还是差不多——因为 AI 本身没有“设计感”这个概念，它只是在做模式匹配。
impeccable 的思路很直接：既然 AI 缺的是设计规则，那就把规则喂给它。项目内置了一套完整的前端设计规范，涵盖间距系统、色彩体系、字体层级、组件布局等维度，通过 CLI 工具注入到 AI coding agent 的工作流中。AI 在生成代码时，会参照这些规则来组织样式，出来的效果直接上一个台阶。
2. 核心机制与设计哲学
2.1 为什么是 CLI 而不是插件
impeccable 选择以 CLI 形式分发，这个决策背后有讲究。市面上做类似事情的工具，有的做成浏览器扩展，有的做成 IDE 插件，impeccable 偏偏选了命令行。我一开始觉得这不够“现代”，但用下来发现这个选择很聪明。
CLI 的好处是通用性。不管你用的是 Codex CLI、Claude Code 还是其他终端里的 AI 编程工具，impeccable 都能无缝接入。它不绑定任何特定的编辑器或平台，你只要在项目目录下跑一条命令，它就把设计规则注入到当前工作环境中。相比之下，IDE 插件往往只支持某一款编辑器，浏览器扩展则受限于网页环境，覆盖面窄得多。
另一个原因是 CLI 更符合 AI coding agent 的工作方式。现在主流的 AI 编程工具，比如 Codex CLI、Claude Code，本身就是命令行工具。impeccable 作为 CLI 跟它们是同一层级的，可以直接在终端里配合使用，不需要来回切换窗口。你可以在一个终端会话里先跑 impeccable 注入规则，再用 Codex CLI 生成代码，整个流程一气呵成。
2.2 设计规则的底层逻辑
impeccable 内置的设计规则不是拍脑袋想出来的，它参考了成熟的设计系统方法论。核心逻辑可以概括为三个层面。
第一个层面是空间系统。impeccable 定义了一套间距刻度，比如 4px、8px、12px、16px、24px、32px、48px、64px 这样的序列。AI 在生成 margin、padding、gap 这些属性时，会被引导从这套刻度里取值，而不是随便写个 13px 或者 27px。这个约束看起来简单，但效果立竿见影——所有元素之间的间距都落在同一个节奏上，页面自然就整齐了。
第二个层面是色彩体系。impeccable 不会让 AI 随便用十六进制颜色值，而是引导它使用语义化的色彩变量。比如 primary、secondary、background、surface、border、text-primary、text-secondary 这些角色。AI 生成代码时会引用这些变量，而不是硬编码颜色值。这样做的好处是，后续要换主题色，改一个变量就行，不用满项目搜索替换。
第三个层面是排版层级。impeccable 规定了标题、正文、辅助文字之间的字号和字重关系。比如 h1 到 h6 的字号递减比例，正文和辅助文字的字重差异，行高的合理范围。AI 按照这套规则生成文本样式，出来的页面就有了清晰的视觉层次，用户扫一眼就知道哪里是重点。
2.3 与 AI coding agents 的协作模式
impeccable 跟 AI coding agents 的配合方式，可以理解为“规则注入 + 实时校验”的双层机制。
规则注入发生在你运行 impeccable 命令的时候。它会在项目目录下生成或更新配置文件，这些文件会被 AI coding agent 读取。比如你用的是 Codex CLI，impeccable 会在项目根目录写入一个规则文件，Codex CLI 在生成代码时会自动参考这个文件的内容。这个过程是透明的，你不需要手动告诉 AI “请遵循这些规则”，它自己就会去读。
实时校验则是在 AI 生成代码之后。impeccable 提供了一套检查命令，可以扫描生成的代码，找出不符合设计规则的地方。比如某个间距值不在刻度序列里，某个颜色是硬编码的而不是变量引用，某个字号跳过了层级。这些检查结果会以清晰的报告形式呈现，你可以据此让 AI 重新生成或手动修正。
这种双层机制的好处是，规则注入保证了 AI 一开始就朝着正确的方向走，实时校验则兜住了漏网之鱼。两者配合，前端代码的设计质量就有了基本保障。
3. 实操流程与关键步骤
3.1 环境准备与安装
impeccable 的安装过程不复杂，但有几个细节需要注意。首先确保你的 Node.js 版本在 18 以上，这是大多数现代 CLI 工具的基本要求。如果你还没装 Node，去官网下载 LTS 版本即可，安装过程一路下一步就行。
安装 impeccable 本身，用 npm 全局安装是最省事的方式：
npm install -g impeccable如果你习惯用 yarn 或 pnpm，对应的命令分别是：
yarn global add impeccable pnpm add -g impeccable安装完成后，在终端输入impeccable --version验证一下。如果能看到版本号输出，说明安装成功。如果提示命令找不到，大概率是 npm 全局 bin 目录没有加到 PATH 环境变量里。这个问题在 macOS 和 Linux 上比较常见，解决办法是在 shell 配置文件里加上export PATH="$PATH:$(npm config get prefix)/bin"，然后重新加载配置文件。
注意：如果你之前装过旧版本的 impeccable，建议先卸载再装新版。卸载命令是
npm uninstall -g impeccable。残留的旧版本可能会导致命令冲突。
3.2 在项目中初始化配置
安装完成后，进入你的前端项目根目录，运行初始化命令：
impeccable init这个命令会做几件事：在当前目录下创建.impeccable配置文件夹，生成默认的设计规则文件，检测你使用的 AI coding agent 类型并做相应适配。初始化过程中，终端会提示你选择项目类型——是 React、Vue、Svelte 还是纯 HTML/CSS。这个选择会影响后续生成的规则文件内容，比如 React 项目会额外包含 JSX 相关的样式约定。
初始化完成后，你会看到项目根目录多了一个.impeccable文件夹，里面通常包含这几个文件：
rules.json：核心设计规则，定义了间距刻度、色彩变量、字号层级等agent-config.json：AI coding agent 的适配配置ignore：指定哪些文件或目录不参与规则校验
这些文件建议纳入版本控制，这样团队里每个人用的都是同一套规则。如果某些规则你不想用，可以直接编辑rules.json，删掉对应的条目即可。
3.3 配合 Codex CLI 生成前端代码
这是 impeccable 最核心的使用场景。假设你已经装好了 Codex CLI，并且完成了 impeccable 的初始化，接下来就可以在项目里用 AI 生成前端代码了。
打开终端，进入项目目录，启动 Codex CLI：
codex进入交互界面后，你可以直接描述需求，比如“帮我写一个用户登录表单，包含邮箱和密码输入框，以及一个登录按钮”。Codex CLI 在生成代码时，会自动读取.impeccable/rules.json里的设计规则，并按照规则来组织样式。
生成完成后，你可以运行 impeccable 的校验命令来检查结果：
impeccable check这个命令会扫描最近修改的文件，输出一份报告。报告里会列出所有不符合规则的地方，比如“第 23 行使用了 13px 的间距，不在刻度序列中”“第 45 行硬编码了颜色值 #3b82f6，建议使用 primary 变量”。根据报告，你可以手动修正，也可以让 Codex CLI 重新生成。
3.4 浏览器扩展的辅助作用
impeccable 除了 CLI 之外，还提供了一个浏览器扩展。这个扩展的作用是实时预览和调试。安装扩展后，你在浏览器里打开本地开发服务器上的页面，扩展会自动检测页面中不符合设计规则的元素，并在页面上用高亮标注出来。
比如某个按钮的 padding 值不在刻度序列里，扩展会在按钮周围画一个红色虚线框，鼠标悬停时显示具体的违规信息。这个功能在调试阶段特别有用，因为你可以直观地看到哪些地方需要调整，而不需要去翻代码。
扩展的安装方式取决于你用的浏览器。Chrome 和 Edge 用户可以去扩展商店搜索 impeccable 安装，Firefox 用户则需要手动加载扩展文件。安装完成后，在扩展设置里填入你的项目路径，扩展就能自动关联到对应的规则文件。
提示：浏览器扩展和 CLI 共享同一套规则文件，所以你在 CLI 里修改了规则，扩展这边会自动同步，不需要重新配置。
4. 常见问题与排查技巧
4.1 安装与配置阶段的坑
问题一：npm 全局安装速度慢或超时。这是国内用户经常遇到的情况。解决办法是切换 npm 镜像源，命令是npm config set registry https://registry.npmmirror.com。切换后再安装，速度会有明显提升。如果还是慢，可以试试用npx impeccable直接运行，跳过全局安装这一步。
问题二：初始化时提示“未检测到 AI coding agent”。这种情况通常是因为你的 AI 编程工具没有安装在默认路径下，或者版本太旧。解决办法是手动指定 agent 类型，命令是impeccable init --agent codex或impeccable init --agent claude。如果还是不行，检查一下你的 AI 工具是否在 PATH 环境变量里。
问题三：规则文件生成了但 AI 不读取。这往往是因为 AI coding agent 的工作目录跟 impeccable 初始化的目录不一致。比如你在项目根目录跑了impeccable init，但 Codex CLI 是在子目录里启动的，它可能找不到规则文件。解决办法是在项目根目录启动 AI 工具，或者在子目录里也跑一次impeccable init。
4.2 使用过程中的典型故障
问题四：生成的代码仍然不符合规则。先运行impeccable check看看具体哪些地方违规。如果违规项很多，可能是规则文件没有正确加载。检查.impeccable/rules.json是否存在且内容完整。如果文件没问题，试试重启 AI coding agent，有时候它需要重新读取配置文件。
问题五：浏览器扩展不生效。首先确认扩展已经启用，并且当前页面是本地开发服务器的地址（比如 localhost:3000）。如果页面是直接打开的 HTML 文件，扩展可能无法正常工作。另外检查扩展设置里的项目路径是否正确，路径错误会导致扩展找不到规则文件。
问题六：校验报告里出现大量误报。这可能是因为你的项目里有一些第三方组件库的样式，这些样式不受 impeccable 规则约束。解决办法是在.impeccable/ignore文件里加上这些组件库的路径，让校验时跳过它们。
4.3 常见问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 安装时提示权限错误 | npm 全局目录权限不足 | 使用sudo或修改 npm 全局目录权限 |
| 初始化后没有生成规则文件 | 目录不可写或磁盘空间不足 | 检查目录权限和磁盘剩余空间 |
| AI 生成的代码样式混乱 | 规则文件未加载或内容有误 | 检查.impeccable/rules.json并重启 AI 工具 |
| 校验命令报错 | 项目中没有可校验的文件 | 确认项目目录下有 HTML/CSS/JS 文件 |
| 浏览器扩展图标灰色 | 扩展未启用或页面不兼容 | 启用扩展并确保页面是本地开发地址 |
| 规则修改后不生效 | 缓存未刷新 | 重启 AI 工具和浏览器扩展 |
4.4 几个提升效率的小技巧
第一个技巧是自定义规则。impeccable 的默认规则适合大多数项目，但如果你有特定的设计系统，可以编辑rules.json来匹配。比如你的品牌色是特定的蓝色，就把 primary 变量的值改成你的品牌色。这样 AI 生成的代码就直接用你的品牌色，省去后续替换的麻烦。
第二个技巧是结合/compact命令使用。在 Codex CLI 里，/compact可以压缩对话历史，释放上下文空间。当你跟 AI 进行了多轮对话、上下文快满的时候，先跑一下/compact，再继续让 AI 生成代码，效果会更好。impeccable 的规则文件不占用对话上下文，所以压缩后规则依然生效。
第三个技巧是定期更新 impeccable。项目在持续迭代，新版本可能会增加新的设计规则或修复已知问题。更新命令是npm update -g impeccable。更新后建议重新跑一次impeccable init，让规则文件同步到最新版本。
5. 设计规则深度拆解与自定义方法
5.1 间距系统的参数逻辑
impeccable 默认的间距刻度是 4、8、12、16、24、32、48、64、96、128，单位是像素。这个序列不是随便定的，它遵循了 4px 基准网格的原则。为什么是 4px 而不是 5px 或 10px？因为 4 能被大多数屏幕像素密度整除，在高分屏上不会出现半像素模糊的问题。
这个序列的另一个特点是，相邻数值之间的比例大致遵循 1.5 到 2 倍的递增。比如 4 到 8 是 2 倍，8 到 12 是 1.5 倍，12 到 16 是 1.33 倍，16 到 24 是 1.5 倍。这种非线性递增让设计师在选值时有了明确的层级感——小间距用于紧凑元素，中间距用于常规布局，大间距用于区块分隔。
如果你想自定义间距刻度，编辑rules.json里的spacing数组即可。但建议保持 4px 基准，只调整具体数值。比如你觉得 96 和 128 太大用不上，可以删掉，换成 80 和 112。关键是保持序列的节奏感，不要出现 4、8、15、23 这种跳跃不规律的数值。
5.2 色彩变量的命名与使用
impeccable 默认定义了一套语义化色彩变量，包括：
primary：品牌主色，用于主要按钮、链接、强调元素secondary：辅助色，用于次要操作和装饰background：页面背景色surface：卡片、面板等容器的背景色border：边框颜色text-primary：主要文字颜色text-secondary：次要文字颜色text-disabled：禁用状态文字颜色success、warning、error：状态色
AI 在生成代码时，会被引导使用这些变量而不是硬编码颜色值。比如生成一个按钮，它会写background-color: var(--primary)而不是background-color: #3b82f6。这样做的好处是主题切换变得极其简单——你只需要在 CSS 变量定义处改一次，整个项目的颜色就全变了。
自定义色彩体系时，建议保持变量命名的语义化。不要用blue、red这种具体颜色名，而是用primary、error这种角色名。因为哪天你的品牌色从蓝色换成紫色，blue这个变量名就变得很尴尬，而primary永远是对的。
5.3 排版层级的比例关系
impeccable 默认的排版层级是这样的：
| 层级 | 字号 | 字重 | 行高 | 用途 |
|---|---|---|---|---|
| h1 | 32px | 700 | 1.2 | 页面主标题 |
| h2 | 24px | 600 | 1.3 | 区块标题 |
| h3 | 20px | 600 | 1.4 | 子区块标题 |
| h4 | 16px | 600 | 1.5 | 卡片标题 |
| body | 14px | 400 | 1.6 | 正文内容 |
| small | 12px | 400 | 1.5 | 辅助说明 |
| caption | 11px | 400 | 1.4 | 标签、注释 |
这个层级的核心逻辑是：字号递减的同时，行高递增。因为字号越小，行高相对越大，才能保证可读性。字重方面，标题用 600 或 700，正文用 400，形成明显的视觉对比。
自定义排版时，建议保持字号序列的数学关系。常见的做法是使用模数比例，比如 1.25 倍（Major Third）或 1.333 倍（Perfect Fourth）。impeccable 默认用的是接近 1.25 倍的比例，从 14px 正文出发，往上推是 17.5、21.9、27.4、34.2，取整后就是 18、22、28、34。你可以根据自己的喜好调整这个比例，但不要跳得太随意。
6. 与不同 AI 工具的配合实践
6.1 配合 Codex CLI 的完整工作流
Codex CLI 是目前跟 impeccable 配合最顺畅的工具之一。完整的工作流是这样的：
第一步，在项目根目录跑impeccable init，生成规则文件。第二步，启动 Codex CLI，用自然语言描述你的前端需求。第三步，Codex CLI 生成代码，自动遵循 impeccable 的规则。第四步，跑impeccable check校验结果。第五步，根据校验报告决定是手动修正还是让 Codex CLI 重新生成。
这个流程里有个细节值得注意：Codex CLI 在生成代码时，会把 impeccable 的规则文件内容作为上下文的一部分。这意味着规则文件不宜过大，否则会占用宝贵的上下文空间。impeccable 默认生成的规则文件大概几百行，这个体量是合理的。如果你自定义了很多规则，建议精简一下，只保留真正需要的部分。
另外，Codex CLI 的/model命令可以切换底层模型。不同模型对设计规则的理解能力有差异。实测下来，能力较强的模型在遵循规则方面表现更好，生成的代码更少违规。如果你发现某个模型生成的代码总是偏离规则，试试换一个模型。
6.2 配合 Claude Code 的注意事项
Claude Code 跟 impeccable 的配合方式略有不同。Claude Code 更倾向于在对话中理解上下文，而不是读取外部配置文件。所以你需要显式地告诉它去读.impeccable/rules.json。
一个实用的做法是，在 Claude Code 的对话开头加上这样一句：“请先读取项目根目录下的.impeccable/rules.json，后续生成前端代码时严格遵循其中的设计规则。”这样 Claude Code 就会把规则文件纳入上下文，生成代码时参照执行。
Claude Code 的优势在于它对长上下文的理解能力较强，可以一次性处理比较复杂的页面需求。你可以把整个页面的结构描述给它，让它一次性生成完整的 HTML、CSS 和 JS。impeccable 的规则会在这个过程中持续生效，保证生成的代码在视觉上的一致性。
6.3 其他 CLI 工具的兼容性
除了 Codex CLI 和 Claude Code，impeccable 理论上可以配合任何读取项目配置文件的 AI 编程工具。关键在于工具是否支持从项目目录读取外部规则。如果工具不支持自动读取，你可以手动把规则文件的内容粘贴到对话里，效果是一样的。
有些工具比如 openspec cli、minimax cli，它们的配置机制各不相同。使用之前建议先看看它们的文档，确认是否支持外部规则注入。如果不支持，impeccable 的浏览器扩展可以作为一个补充手段——你可以在浏览器里实时看到哪些地方不符合规则，然后手动调整。
提示：不管用什么 AI 工具，impeccable 的规则文件都是纯文本格式，你可以随时打开查看和编辑。这意味着你完全掌控着设计规则，不会被工具锁定。
7. 实际项目中的效果与局限
7.1 效果实测：从“能用”到“好看”
我在一个实际项目里对比了使用 impeccable 前后的效果。项目是一个后台管理系统的仪表盘页面，包含数据卡片、表格、图表和筛选控件。
使用之前，让 AI 直接生成代码，出来的页面问题很明显：卡片之间的间距不一致，有的 16px 有的 20px；表格的表头和内容行高一样，没有区分；筛选控件的按钮颜色是默认蓝，跟整体色调不搭。整体感觉就是“拼凑出来的”。
使用 impeccable 之后，同样让 AI 生成代码，变化很直观：所有间距都落在 4px 刻度上，卡片之间统一 24px 间距；表头行高 48px、内容行高 40px，层次分明；按钮使用了 primary 变量，颜色跟品牌色一致。页面整体看起来协调多了，不需要太多手动调整就能达到可交付的状态。
从时间成本上看，使用 impeccable 之前，我大概要花 30 到 40 分钟手动调整样式；使用之后，调整时间缩短到 10 分钟左右。对于频繁生成前端代码的场景，这个效率提升是实实在在的。
7.2 当前版本的局限性
impeccable 不是万能的，它有几个明显的局限。
第一，它主要关注视觉层面的设计规则，对交互逻辑和可访问性关注较少。比如键盘导航、屏幕阅读器支持、焦点状态管理这些，impeccable 的规则覆盖不到。如果你的项目对可访问性有要求，还需要额外的手段来保障。
第二，它对复杂布局的支持有限。简单的卡片、表单、列表，impeccable 处理得很好。但遇到复杂的网格布局、响应式断点、动画过渡这些，规则的作用就弱化了。AI 在这些场景下仍然需要人工指导。
第三，规则文件的自定义有一定学习成本。虽然 JSON 格式不算复杂，但要设计出一套合理的设计规则，还是需要一定的设计功底。如果你对设计系统不太熟悉，建议先用默认规则，等熟悉了再逐步调整。
7.3 后续可以扩展的方向
从项目的发展趋势看，impeccable 后续可能会在几个方向上有动作。一是增加对更多 AI 工具的支持，目前主要适配 Codex CLI 和 Claude Code，未来可能会覆盖更多。二是增强规则引擎的智能程度，比如根据项目已有的样式自动推导规则，而不是完全依赖手动配置。三是提供更多的预设规则集，针对不同项目类型（后台管理、电商、博客等）给出开箱即用的方案。
作为用户，我比较期待的是规则的可视化编辑。现在改规则要手动编辑 JSON 文件，对不熟悉代码的设计师不太友好。如果有一个图形界面可以拖拽调整间距刻度、色彩变量，那就方便多了。
8. 个人实操心得与建议
8.1 什么时候该用 impeccable
根据我的经验，impeccable 最适合的场景是：你频繁使用 AI 生成前端代码，并且对视觉质量有一定要求，但又没有专职设计师配合。比如独立开发者做 side project，或者小团队快速做 MVP，impeccable 能帮你省下大量调样式的时间。
反过来，如果你本身设计功底很强，对每个像素都有精确控制的需求，impeccable 的规则可能会让你觉得束手束脚。这种情况下，你可以把 impeccable 当作一个参考，而不是强制约束。只启用你认可的规则，其他的关掉。
还有一种情况是项目已经有成熟的设计系统。这时候 impeccable 的默认规则可能跟你的设计系统冲突。解决办法是把 impeccable 的规则文件改成你设计系统的映射，让 AI 生成的代码直接使用你已有的设计变量。这样既享受了 AI 生成的效率，又保持了设计系统的一致性。
8.2 几个踩过的坑
第一个坑是规则文件放错位置。我一开始在子目录里跑impeccable init，结果 AI 工具在根目录启动时找不到规则文件。后来统一在项目根目录初始化，问题就解决了。建议不管项目结构多复杂，impeccable 的初始化都在根目录做。
第二个坑是规则文件太大。我一开始把能想到的规则都写进去了，结果 AI 生成代码时上下文被占满，反而影响了生成质量。后来精简到只保留核心规则，效果明显好转。规则不在多，在于精。
第三个坑是忘了更新。impeccable 更新后，规则文件的格式可能会有变化。如果一直用旧版本的规则文件，可能会错过新功能。建议每隔一段时间跑一次impeccable init，让规则文件同步到最新版本。
8.3 给新手的上手建议
如果你刚开始用 impeccable，我的建议是：先用默认规则跑一遍完整流程，感受一下效果。不要一上来就自定义规则，那样容易陷入细节。等熟悉了基本用法，再根据自己的需求逐步调整。
另外，建议把 impeccable 跟版本控制结合起来。.impeccable文件夹纳入 git 管理，这样团队里每个人用的都是同一套规则。如果有人改了规则，其他人拉取代码后自动生效，不需要额外沟通。
最后，不要指望 impeccable 能解决所有设计问题。它是一个辅助工具，帮你把 AI 生成的代码从“能用”提升到“好看”，但真正的设计决策还是需要人来把关。把它当作一个靠谱的助手，而不是替代品。
