impeccable：CLI+浏览器扩展+AI代理的前端设计规范自动化实践

1. 项目缘起：为什么我们需要一个叫“impeccable”的前端设计规范工具

第一次看到“impeccable”这个词，是在一个前端团队的内部复盘文档里。当时他们刚经历了一次惨烈的线上事故——设计稿还原度只有七成，组件库版本混乱，三个前端各写各的样式变量，最后上线时间比预期晚了整整两周。复盘会上有人甩出一句：“我们的前端产出离 impeccable 差太远了。”这个词就这么被记住了。

impeccable 直译是“无可挑剔的”，放在前端设计语境里，它指向的是一种近乎苛刻的交付标准：视觉还原零偏差、交互状态全覆盖、代码结构可预测、设计系统与实现完全对齐。但问题在于，靠人肉去追求 impeccable 是不现实的。一个中等规模的项目，光按钮组件就有 default、hover、active、focus、disabled、loading 六种状态，再乘以 primary、secondary、ghost、danger 四种变体，就是二十四种组合。靠设计师标注、前端手写，漏掉三五个状态太正常了。

所以当“impeccable”作为一个项目标题出现时，我本能地意识到：这大概率不是一个设计稿，而是一套工具链或者一个规范体系。结合热搜词里的 AI coding agents、frontend design、CLI、browser extension，方向就更清晰了——它应该是一个用命令行和浏览器插件配合，把前端设计规范自动化落地的东西。说白了，就是让 AI 编码代理和浏览器扩展帮你盯着，别让前端产出跑偏。

这篇文章适合谁看？如果你是前端工程师，正在被设计还原度折磨；如果你是技术负责人，想给团队建立一套可执行的 UI 规范；如果你是对 AI 辅助编码感兴趣、想看看 CLI 工具怎么和浏览器扩展打配合的开发者，那接下来的内容应该对你有用。我会从整体设计思路拆到具体实操，包括 CLI 命令怎么写、浏览器扩展怎么配、AI 代理怎么调，以及我踩过的那些坑。

2. 整体设计思路：CLI 加浏览器扩展加 AI 代理的三层架构

2.1 为什么是 CLI 而不是纯 Web 工具

前端设计规范工具其实不少，Figma 插件、Storybook、Chromatic 都能做视觉回归。但 impeccable 选择 CLI 作为核心入口，这个决策背后有很实际的考量。CLI 意味着它可以嵌入任何 CI/CD 流程，可以在 pre-commit 钩子里跑，可以在代码合并前自动检查。Web 工具再方便，也没法在 git push 的那一刻拦住你。

更重要的是，CLI 天然适合和 AI coding agents 配合。现在的 AI 编码代理，不管是 Codex CLI 还是其他命令行工具，本质上都是在终端里工作的。它们读文件、写代码、跑测试，整个交互闭环都在 shell 里完成。如果设计规范检查也是一个 CLI 命令，那 AI 代理就能直接调用它、读取它的输出、根据报错自动修复。这个自动化闭环是 Web 工具做不到的。

我试过用纯浏览器扩展做设计走查，问题是扩展只能看到渲染后的页面，看不到源码里的样式变量和组件结构。而 CLI 可以直接解析 CSS、SCSS、Tailwind 配置，甚至能读设计 token 的 JSON 文件。两者结合，才能既看“表”又看“里”。

2.2 浏览器扩展的角色：实时视觉校验

浏览器扩展在 impeccable 体系里承担的是“实时视觉校验”的角色。CLI 负责静态检查和批量扫描，扩展负责在开发过程中即时反馈。比如你在本地起了一个 dev server，扩展可以自动注入一个校验层，把当前页面和设计稿的基准图做像素级对比，差异超过阈值就在页面上标红。

这个思路借鉴了视觉回归测试的工具，但做了轻量化。传统视觉回归要跑一整套截图流程，慢且重。impeccable 的扩展更像是“设计稿叠加层”——把设计稿的半透明图层盖在实现页面上，肉眼就能看出偏移。同时它还会检查一些 CLI 不容易覆盖的东西，比如字体渲染差异、阴影的实际视觉效果、动画的缓动曲线是否匹配。

扩展的另一个作用是采集。它可以把当前页面的 computed style 导出成 JSON，喂给 CLI 做进一步分析。这就形成了一个双向通道：CLI 告诉扩展要检查哪些规则，扩展把检查结果和原始数据回传给 CLI。

2.3 AI 代理的介入点：从检查到修复

AI 代理在这个体系里不是必须的，但加上之后体验会完全不同。没有 AI 的时候，CLI 报错说“按钮的 focus 状态缺少 outline 样式”，你得自己去找到对应的组件文件，手动补上。有 AI 代理的时候，你可以让它读 CLI 的输出，自动定位文件、生成修复代码、跑一遍验证。

这里的关键是 CLI 的输出格式要对 AI 友好。我试过让 AI 读普通的 console.log 输出，它经常抓不住重点。后来改成结构化的 JSON 输出，每个问题包含文件路径、行号、规则 ID、期望值、实际值，AI 就能精准定位了。impeccable 的 CLI 在设计时应该也考虑到了这一点，输出里带了足够的上下文信息。

还有一个细节：AI 代理需要知道“什么算修好了”。所以 CLI 要支持--fix模式，AI 改完之后再跑一次，如果通过就说明修复成功。这个反馈循环是自动化的核心。

3. 核心细节解析：设计 token、规则引擎与检查策略

3.1 设计 token 的统一管理

impeccable 能跑起来的前提，是设计 token 有单一可信来源。什么叫单一可信来源？就是颜色、间距、字体、圆角、阴影这些基础样式值，只在一个地方定义，所有地方都从这里取。听起来简单，但实际项目里经常是 Figma 一套、CSS 变量一套、Tailwind 配置又一套，三套之间靠人肉同步。

我的做法是让设计 token 以 JSON 格式存在项目根目录的design-tokens.json里，结构大概是这样：

{ "color": { "primary": { "value": "#2563eb", "type": "color" }, "danger": { "value": "#dc2626", "type": "color" } }, "spacing": { "sm": { "value": "8px", "type": "spacing" }, "md": { "value": "16px", "type": "spacing" } }, "radius": { "button": { "value": "6px", "type": "borderRadius" } } }

然后 CLI 会读这个文件，生成对应的 CSS 变量和 Tailwind 配置。浏览器扩展也从这里读，用来做视觉对比的基准。AI 代理在修复样式时，也被要求只能引用 token 里的值，不能硬编码。这样就保证了从设计到实现的一致性。

注意：token 的命名要有语义，不要用blue-500这种纯视觉描述，而要用primary、danger这种功能描述。否则换主题的时候你会想哭。

3.2 规则引擎的设计：哪些规则值得检查

impeccable 的规则引擎不是越多越好。我见过一些团队搞了几百条 lint 规则，结果开发者天天在绕规则，反而降低了效率。真正值得检查的规则，应该满足两个条件：一是违反了会导致明显的视觉或交互问题，二是修复成本不高。

我整理的规则清单大概分四类：

颜色和交互状态是 error 级别，因为这两个出问题用户直接能感知到。间距和断点先设为 warning，给团队一个适应期，等大家习惯了再升级。

规则引擎的实现方式，我推荐用 AST 解析而不是正则匹配。正则匹配 CSS 很容易误伤，比如color: #fff和background: url(#fff)里的#fff含义完全不同。用 PostCSS 或者 stylelint 的解析器，能准确拿到每个声明的位置和上下文。

3.3 浏览器扩展的注入策略

浏览器扩展怎么知道要检查哪个页面？我的方案是让扩展监听 localhost 的特定端口，当检测到 dev server 启动时，自动注入校验脚本。注入的脚本会做三件事：读取页面上所有元素的 computed style，和设计 token 做对比，把差异用高亮框标出来。

这里有个坑：有些样式是运行时动态计算的，比如 CSS-in-JS 生成的类名，扩展直接读 DOM 可能拿不到原始定义。解决办法是让扩展同时监听样式表的插入事件，把动态生成的样式也纳入检查范围。

另一个坑是性能。如果页面上有几千个元素，逐个对比会卡死。我的做法是只检查“关键元素”——按钮、输入框、卡片、导航这些高频组件，其他的先跳过。关键元素的列表可以在 CLI 的配置文件里定义。

4. 实操过程：从零搭建 impeccable 工作流

4.1 环境准备与 CLI 安装

假设你用的是 macOS 或者 Linux，Node.js 版本 18 以上。先全局安装 impeccable 的 CLI：

npm install -g impeccable-cli

安装完之后跑一下impeccable --version，确认安装成功。然后在你项目的根目录初始化配置：

impeccable init

这个命令会生成一个impeccable.config.js文件，里面包含规则开关、token 路径、忽略目录等配置。默认配置长这样：

module.exports = { tokens: './design-tokens.json', rules: { 'color-consistency': 'error', 'spacing-consistency': 'warning', 'interactive-states': 'error', 'responsive-breakpoints': 'warning' }, ignore: ['node_modules', 'dist', '*.test.*'], browserExtension: { port: 3456, highlightColor: '#ff0000' } };

配置文件里的browserExtension.port要和后面扩展里填的端口一致，否则连不上。

4.2 设计 token 的导入与转换

如果你已经有 Figma 的设计稿，可以用 Figma 的 Tokens Studio 插件导出 JSON，然后放到项目根目录。如果没有，就手动建一个design-tokens.json，按上一节的结构填。

填完之后跑：

impeccable tokens build

这个命令会把 JSON 转换成 CSS 变量文件和 Tailwind 配置。生成的 CSS 变量文件默认叫impeccable-tokens.css，你在主样式文件里@import一下就行。Tailwind 配置会合并到你现有的tailwind.config.js里，不会覆盖你已有的配置。

提示：每次修改 token 后都要重新跑tokens build，建议把它加到package.json的predev脚本里，这样启动 dev server 前会自动更新。

4.3 浏览器扩展的安装与配置

impeccable 的浏览器扩展目前支持 Chrome 和 Edge。安装方式有两种：从商店安装，或者加载本地解压的扩展。开发阶段建议用后者，方便调试。

安装完之后，点击扩展图标，会弹出配置面板。需要填三个东西：CLI 的监听端口（默认 3456）、要检查的页面 URL 模式（比如http://localhost:3000/*）、以及是否开启自动高亮。填完之后点“连接”，如果 CLI 正在运行，状态灯会变绿。

连接成功后，打开你的 dev server 页面，扩展会自动注入校验层。你会在页面右下角看到一个悬浮面板，显示当前页面的检查结果。有问题的元素会被红色虚线框标出来，鼠标悬停能看到具体差异。

4.4 跑一次完整的检查

在项目根目录执行：

impeccable check

CLI 会扫描所有匹配的文件，输出检查结果。默认输出是给人看的表格格式，加--json参数会输出 JSON，方便 AI 代理读取。

impeccable check --json > impeccable-report.json

如果想让 AI 代理自动修复，可以这样：

impeccable check --json | your-ai-agent --fix

这里的your-ai-agent替换成你实际用的 AI 编码代理命令。代理会读 JSON 报告，定位问题文件，生成修复代码，然后你再跑一次impeccable check验证。

4.5 集成到 CI 流程

在.github/workflows/ci.yml里加一步：

- name: Run impeccable check run: | npm install -g impeccable-cli impeccable check --json > report.json if [ $(jq '.errors | length' report.json) -gt 0 ]; then echo "Impeccable check failed" exit 1 fi

这样每次 PR 都会自动跑检查，有 error 级别的规则违反就阻断合并。warning 级别的先不阻断，但在 PR 评论里贴出来，提醒开发者注意。

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

5.1 CLI 报错“Token file not found”

这个最常见，九成是因为impeccable.config.js里的tokens路径写错了。路径是相对于项目根目录的，不是相对于配置文件。如果你把 token 文件放在src/design/tokens.json，配置里就要写'./src/design/tokens.json'。

还有一种情况是文件存在但格式不对。CLI 期望的是 Tokens Studio 的标准格式，如果你手写 JSON 漏了value或type字段，也会报这个错。用impeccable tokens validate可以先验证格式。

5.2 浏览器扩展连不上 CLI

先确认 CLI 是否在运行。impeccable check是一次性命令，跑完就退出了，扩展连不上是正常的。要让扩展连上，得跑impeccable watch，这个命令会启动一个常驻进程，监听文件变化并保持端口开放。

如果watch在跑但还是连不上，检查端口是否被占用。lsof -i :3456看看有没有其他进程占着。有的话改配置里的端口，两边同步改。

5.3 检查结果误报太多

误报通常来自两个地方：一是第三方组件库的样式被扫进来了，二是动态生成的类名没被正确解析。第一个问题在ignore里加上node_modules和组件库的路径就行。第二个问题需要在配置里开启dynamicStyle: true，让 CLI 用更宽松的解析策略。

如果误报还是多，建议先把规则级别调成warning，观察一段时间，把确实没问题的规则关掉，再逐步收紧。

5.4 AI 代理修复后检查仍不通过

这种情况一般是 AI 改错了文件，或者改的地方不对。让 AI 读 JSON 报告时，确保报告里包含了filePath和lineNumber。如果 AI 用的模型上下文窗口小，可能读不完整个报告，建议按文件拆分报告，一次只喂一个文件的问题。

还有一个可能是 AI 修复时引入了新的 token 外颜色值。所以在 AI 的提示词里要明确写：“只能使用 design-tokens.json 里定义的值，不得硬编码颜色和间距。”

5.5 性能问题：检查太慢

大项目跑全量检查确实慢。我的优化策略是分层检查：pre-commit 只检查改动的文件，CI 跑全量但加缓存。CLI 支持--changed参数，只检查 git diff 里的文件。缓存方面，impeccable check --cache会把上次的结果存下来，没变的文件跳过。

如果还是慢，检查一下是不是把dist和build目录也扫了。这些目录应该在ignore里。

6. 一些实操心得与扩展思路

这套东西我断断续续搭了两个月，中间推翻重来过一次。最大的体会是：不要一开始就追求全覆盖。先把颜色和交互状态这两个最影响体验的规则跑通，让团队感受到“确实能发现问题”，再慢慢加规则。一上来就搞几十条规则，大家只会觉得你在添乱。

另一个心得是，浏览器扩展的高亮颜色别用红色。红色太刺眼，开发的时候满屏红框很影响心情。我用的是橙色#f59e0b，既能引起注意又不至于让人焦虑。这个颜色也可以在配置里改。

后续扩展的话，我在考虑把设计稿的截图对比也加进去。现在的方案是读 computed style，但有些视觉效果（比如渐变、阴影的柔和度）光看数值看不出来，得靠像素对比。不过像素对比的性能开销大，可能只对关键页面开启。

还有一个方向是和设计工具的双向同步。现在是从设计工具导出 token 到代码，未来能不能反过来，代码里发现的新颜色值自动同步回设计工具？这个链路打通了，设计和实现的鸿沟才算真正填上。不过这是后话了，眼下先把检查跑稳再说。