impeccable 实战：用 CLI 与浏览器扩展约束 AI 生成前端代码的设计规范

1. 从“impeccable”这个词说起：它到底想解决什么问题

第一次看到“impeccable”这个项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的场景：你让 AI 帮你写一段前端代码，它给你吐出来一坨能跑但丑得离谱的东西——间距忽大忽小、颜色搭配像打翻了调色盘、响应式断点全靠猜。你反复在 prompt 里写“make it beautiful”，结果它给你加了一堆渐变和阴影，反而更糟。

impeccable 就是冲着这个痛点来的。它本质上是一套面向AI coding agents的前端设计约束层，通过CLI和browser extension两种形态，把“什么叫好看”这件事从模糊的自然语言描述，变成 agent 可以理解、可以执行、可以验证的结构化规则。换句话说，它不是在教你怎么写 CSS，而是在教 AI 怎么写出不丢人的 CSS。

这个项目适合谁？三类人值得认真看：一是天天用 Codex CLI、Claude Code 这类工具写前端但总在审美上翻车的开发者；二是想给自己的 AI 工作流加一道“设计质检”环节的团队；三是对frontend design自动化感兴趣、想搞清楚 agent 到底能不能理解美学这件事的技术人。不管你用的是哪家的 CLI，核心思路是通用的。

我花了大概两周时间把它的 CLI 和浏览器扩展两条路径都跑了一遍，踩了不少坑，也总结出一些文档里不会写的经验。下面按我实际使用的顺序来拆。

2. 核心设计思路拆解：为什么是“约束层”而不是“生成器”

2.1 一个关键判断：AI 不缺生成能力，缺的是判断标准

很多人对 AI 写前端的期待是“你给我生成一个漂亮的页面”。但实际用下来你会发现，模型生成 CSS 的能力早就够用了，真正的问题是它不知道什么叫做“够好了”。你让它写一个卡片组件，它能写出来，但它不知道 16px 和 24px 的间距在这个场景下哪个更合适，不知道阴影的模糊半径超过多少就会显得脏。

impeccable 的设计哲学就是：不去重新造一个生成模型，而是给现有的 agent 套一层设计判断标准。这层标准以规则集的形式存在，agent 在生成代码前后都可以调用它来做校验和修正。这个思路我觉得比“训练一个专门写前端的模型”务实得多，因为设计品味这件事太主观了，靠训练很难收敛，但靠规则约束是可以做到的。

提示：如果你之前用过类似“AI 设计系统”的工具，会发现它们大多走的是组件库路线——给你一堆预设组件让 AI 去拼。impeccable 走的是另一条路，它不提供组件，提供的是判断依据。这个区别很关键，决定了它的适用范围更广，但也意味着你需要自己准备组件基础。

2.2 CLI 与 browser extension 的分工逻辑

项目同时提供 CLI 和浏览器扩展，这不是重复建设，而是对应了两个完全不同的使用场景。

CLI 的定位是批量和集成。你在终端里跑impeccable check ./src这样的命令，它扫描你的代码文件，输出一份设计规范符合度报告。这个模式适合放进 CI 流程，或者在你用 Codex CLI 生成完一批代码之后做一次统一质检。它的优势是快、可脚本化、能处理整个项目。

浏览器扩展的定位是实时和可视化。你打开一个页面，扩展会在侧边栏里标出哪些元素违反了设计规则，比如“这个按钮的对比度不足”“这个间距不在允许的刻度上”。这个模式适合调试阶段，尤其是当你想搞清楚“为什么这个页面看起来就是不对劲”的时候。

我自己的用法是：开发阶段开着扩展边写边看，提交之前跑一遍 CLI 做最终检查。两条路径配合起来，基本能覆盖从写到验的完整闭环。

2.3 规则集的来源与可扩展性

impeccable 内置的规则集不是拍脑袋定的，它参考了几套成熟的设计系统规范，包括间距刻度、字号阶梯、颜色对比度标准这些。但真正让我觉得有意思的是它的规则文件是可读可改的。你可以在项目根目录放一个配置文件，覆盖默认规则。

举个例子，默认的间距刻度是 4px 的倍数，但如果你团队用的是 8px 基准，直接改配置就行。这个设计避免了“工具和团队规范打架”的尴尬，也是它能落地到实际项目的前提。我见过太多设计工具因为不可配置而被弃用，impeccable 在这一点上做对了。

3. 环境准备与 CLI 安装实操

3.1 安装前的依赖检查

在装 impeccable CLI 之前，有几件事必须先确认。首先是 Node 版本，我实测下来 18.x 以上比较稳，16.x 在某些规则解析上会报错。其次是包管理器，npm、pnpm、yarn 都支持，但如果你项目里用的是 pnpm 的 workspace 模式，建议全局安装而不是项目内安装，否则跨包扫描会有路径问题。

检查命令很简单：

node -v npm -v

如果 Node 版本低于 18，建议先用 nvm 切一下。我一开始图省事用了系统自带的 Node 16，结果跑扫描的时候一直提示某个语法解析失败，折腾了半小时才发现是版本问题。

3.2 安装命令与验证

安装本身没什么难度：

npm install -g impeccable-cli

装完之后跑一下版本号确认：

impeccable --version

如果提示命令找不到，大概率是全局 bin 目录没在 PATH 里。npm 的话可以用npm config get prefix看一下路径，然后手动加进环境变量。这个问题在 macOS 上用 Homebrew 装的 Node 特别常见，Windows 上反而少一些。

注意：如果你同时装了多个 Node 版本管理器，全局安装的包可能只对当前版本生效。切换 Node 版本后记得重新装一遍，或者用npx impeccable的方式调用。

3.3 项目初始化配置

装好之后，在项目根目录跑：

impeccable init

这个命令会生成一个impeccable.config.json文件，里面是默认规则集。我建议第一次用的时候先不要改任何东西，跑一遍默认规则看看报告长什么样，心里有个底之后再按需调整。

配置文件的核心结构大概是这样的：

{ "spacing": { "base": 4, "scale": [0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64] }, "typography": { "scaleRatio": 1.25, "baseSize": 16 }, "color": { "contrastMin": 4.5 }, "ignore": ["node_modules/**", "dist/**"] }

spacing.scale那个数组就是允许的间距值，单位是 base 的倍数。比如 base 是 4，scale 里有 4，那 16px 就是合法的，20px 就会报警告。这个设计的好处是它不禁止你用任意值，只是提醒你“这个值不在刻度上”，你可以选择忽略或者调整。

4. 用 CLI 扫描前端代码：完整流程与参数详解

4.1 基础扫描命令

最基本的用法是直接扫描一个目录：

impeccable check ./src

它会递归扫描目录下所有 CSS、SCSS、Less 以及内联样式，输出一份报告。报告分三个级别：error、warning、info。error 是明确违反硬性规则的，比如颜色对比度低于标准；warning 是偏离刻度但不算错的，比如用了非标准间距；info 是一些建议性的提示。

我第一次跑的时候，一个中等规模的项目输出了 200 多条 warning，看着挺吓人，但仔细一看大部分是间距不在刻度上。这种情况其实很正常，因为很多项目的历史代码本来就没有严格的设计规范。我的建议是先把 error 清零，warning 分批处理，不要试图一次全改完。

4.2 输出格式与过滤参数

默认输出是给人看的彩色文本，但如果你要集成到 CI 里，可以用--format json输出结构化数据：

impeccable check ./src --format json > report.json

还有一个很实用的参数是--level，可以只显示某个级别以上的问题：

impeccable check ./src --level error

这样在 CI 里就可以只卡 error，warning 作为参考不阻塞流程。我自己的做法是本地开发时看全量报告，CI 里只卡 error，这样既保证了底线质量，又不会因为历史遗留的 warning 导致构建失败。

4.3 针对特定文件类型的扫描

如果你的项目里 CSS 和 JSX 混着写，可以用--include和--exclude精确控制扫描范围：

impeccable check ./src --include "**/*.css" --exclude "**/*.test.*"

这个在大型项目里特别有用，因为全量扫描有时候会跑到测试文件或者第三方代码里去，产生大量噪音。我一般会把node_modules、dist、coverage这些目录排除掉，配置文件里的ignore字段就是干这个的。

4.4 自动修复功能的使用与边界

impeccable 提供了一个--fix参数，可以自动修复一部分问题，主要是间距和字号这类数值型的偏差：

impeccable check ./src --fix

但我要泼一盆冷水：自动修复要慎用。它会把所有非标准间距强行拉到最近的刻度值上，这在大多数情况下是对的，但如果你的设计稿里有一些刻意为之的“破格”间距，它也会一并改掉。我第一次用的时候没注意，把一个 hero 区域的 20px 间距改成了 16px，视觉上明显变紧了。

提示：用--fix之前一定要先提交代码或者做好备份，改完之后用git diff仔细过一遍。我现在的习惯是先用--fix --dry-run看一下会改哪些地方，确认没问题再实际执行。

5. 浏览器扩展的安装与实时校验

5.1 扩展的获取与加载

浏览器扩展这块，impeccable 目前主要通过开发者模式加载。你需要在项目的 releases 页面下载扩展包，然后在浏览器的扩展管理页面打开“开发者模式”，选择“加载已解压的扩展程序”，指向解压后的目录。

这个过程听起来简单，但有几个坑。首先是浏览器版本，Chrome 和 Edge 的 Manifest V3 支持情况不一样，我实测 Chrome 110 以上没问题，Edge 稍微旧一点的版本可能会提示权限错误。其次是如果你用的是公司电脑，扩展安装可能被策略限制，这种情况只能走 CLI 路线。

5.2 侧边栏报告解读

装好之后打开任意页面，点击扩展图标，侧边栏会显示当前页面的设计规范报告。它会按元素分类，把有问题的元素高亮出来。我特别喜欢它的一个功能是：鼠标悬停在报告条目上，页面上对应的元素会闪烁一下，这样你就能快速定位到问题所在。

报告里最常见的几类问题：

这个表格是我根据实际使用总结的，不是官方文档里的原文。对比度不足是唯一一个我建议必须修的 error 级别问题，因为它直接关系到可访问性。

5.3 与 CLI 结果的差异说明

有一点需要提前知道：浏览器扩展和 CLI 的检查结果不完全一致。CLI 是静态分析源码，扩展是分析渲染后的 DOM。这意味着扩展能发现一些源码里看不出来的问题，比如继承导致的最终计算值偏离，但它也可能漏掉一些源码里有但当前页面没渲染到的样式。

我的经验是：扩展适合发现“视觉上真实存在的问题”，CLI 适合发现“代码层面潜在的问题”。两者互补，不要指望其中一个能完全替代另一个。

6. 与 AI coding agents 的集成实践

6.1 在 Codex CLI 工作流中嵌入检查

这是我用得最多的场景。我的工作流大概是：用 Codex CLI 生成一个组件，然后立刻跑 impeccable 检查，把报告喂回给 agent 让它修正。这个循环跑两三轮，出来的代码质量比单纯让 agent 生成要好很多。

具体操作上，我会在 agent 的 prompt 里加一句：“生成完成后运行impeccable check <file> --format json，根据报告修正所有 error 级别的问题。”这样 agent 就有了一个明确的验收标准，而不是靠它自己猜什么叫“好看”。

实测下来，加了这一步之后，生成的前端代码在间距一致性上的问题减少了大概七成。当然这只是一个粗略的体感，不是严格的统计数据。

6.2 把规则文件作为 agent 的上下文

另一个我觉得很实用的做法是：把impeccable.config.json直接作为 agent 的上下文文件。很多 CLI 工具支持读取项目根目录的配置文件作为系统提示的一部分，这样 agent 在生成代码的时候就知道你的间距刻度是什么、字号比例是多少，从源头上减少违规。

这个做法比事后检查更高效，因为它把问题扼杀在生成阶段。但前提是你的配置文件要写得足够清晰，agent 能看懂。我建议在配置里加一些注释性的字段，虽然 JSON 本身不支持注释，但你可以用一个_comment字段来写说明。

6.3 多 agent 协作时的规则同步

如果你团队里多个人都在用 AI agent 写前端，规则同步就很重要。我的做法是把impeccable.config.json提交到版本控制，然后在项目的 README 里写清楚：所有 AI 生成的前端代码必须通过 impeccable 检查才能提交。

这样做的额外好处是，它给团队提供了一个客观的讨论基础。以前大家争论“这个间距是不是太大了”，现在直接看报告，在刻度上就是合规的，不在就是需要说明理由的。把主观审美问题转化成客观规则问题，沟通成本降低了很多。

7. 常见问题与排查技巧实录

7.1 扫描结果为空或明显不全

这是我最开始遇到的一个问题：跑impeccable check ./src什么都没输出。排查下来有几个常见原因。一是文件扩展名不在默认扫描范围内，比如你用的是.vue单文件组件，默认可能不识别，需要手动加--include "**/*.vue"。二是配置文件里的ignore字段写得太宽泛，把整个 src 都排除了。三是路径问题，如果你在 monorepo 的子包里跑，相对路径可能不对。

排查顺序建议：先确认文件确实存在且扩展名正确，再检查配置文件，最后用--verbose参数看详细日志。

7.2 对比度检查的误报处理

对比度检查偶尔会误报，典型情况是文字颜色是通过 CSS 变量动态设置的，静态分析拿不到最终值，就会按默认值来判断。这种情况可以在配置里针对特定选择器加白名单：

{ "color": { "ignoreSelectors": [".dynamic-theme-text"] } }

但我要提醒一句：白名单是最后的手段，不要一遇到误报就加白名单。先确认是不是真的误报，有时候确实是代码写得有问题，只是你之前没意识到。

7.3 自动修复后样式错乱的回滚

前面提到过--fix的风险，这里补充一下回滚的方法。如果你没提前提交代码，可以用git stash先存一下当前修改，然后git checkout .恢复到上次提交的状态。如果已经提交了，就用git revert回滚那一次提交。

我现在的标准流程是：--fix之前必git commit，改完之后git diff逐行审查，确认没问题再git commit一次。这样即使出问题也能精确回滚到修复前的状态。

7.4 扩展不生效的排查清单

浏览器扩展不生效的情况我也遇到过几次，整理了一个排查清单：

• 确认扩展已启用，且当前页面不是浏览器内置页面（如 chrome:// 开头的页面扩展无法注入）
• 检查是否有其他扩展冲突，尤其是其他设计类或调试类扩展
• 刷新页面后重试，有些页面是 SPA，路由切换后扩展需要重新注入
• 查看扩展的后台日志，通常在扩展管理页面的“服务工作进程”里能看到报错信息

大部分情况下，刷新页面或者重启浏览器就能解决。如果还不行，卸载重装扩展通常能搞定。

8. 我实际用下来的一些体会

impeccable 这个项目最让我认可的一点是它没有试图做一个“万能设计 AI”，而是老老实实做了一层约束。这个定位看起来很窄，但实际用起来覆盖面很广，因为几乎所有 AI 生成前端代码的场景都需要这层约束。

CLI 和扩展两条路径我都深度用过，如果只能选一个，我会选 CLI，因为它更容易集成到自动化流程里。但扩展在调试阶段的直观性是 CLI 替代不了的，尤其是当你面对一个“说不出哪里不对但就是不好看”的页面时，扩展能帮你快速定位到具体问题。

规则配置这块，我的建议是不要一开始就大改默认值。先用默认规则跑一两周，积累一些实际报告之后再按需调整。我见过有人一上来就把间距刻度改成自己习惯的值，结果发现和团队其他人的习惯冲突，反而制造了新的混乱。

最后分享一个我最近在用的技巧：把 impeccable 的检查报告作为 code review 的一部分。每次 PR 里附上一份检查报告，reviewer 就能快速判断这次改动有没有引入设计规范上的退化。这个做法比单纯靠人眼看要可靠得多，尤其是当改动涉及大量样式调整的时候。