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

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

第一次看到“impeccable”这个项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的场景：你让 AI 帮你写一段前端代码，它给你吐出来一坨能跑但丑得离谱的东西——间距忽大忽小、颜色搭配像打翻了调色盘、响应式断点全靠猜。你反复调 prompt，它每次都能给你“差不多但就是不对”的结果。这个痛点，凡是用过 AI coding agents 写前端的人，应该都深有体会。

“impeccable”这个词本身的意思是“无可挑剔的、完美的”。放在前端设计语境下，它指向的是一个非常明确的目标：让 AI 生成的前端界面达到“无可挑剔”的视觉质量。而它实现这个目标的方式，不是靠更长的 prompt，也不是靠换更强的模型，而是通过一套 CLI 工具加浏览器扩展的组合，把“设计规范”这件事从口头描述变成了可执行、可验证的工程约束。

说白了，它解决的是 AI 写前端时“审美不可控”的问题。你不需要是设计师，也不需要背一堆设计原则，只要在项目里跑一条命令，它就能帮你把 AI 生成的界面拉到一条及格线以上。适合谁来用？我的判断是三类人：一是独立开发者，自己写全栈但前端审美一般；二是前端工程师，想用 AI 提效但不想每次都手动擦屁股；三是产品经理或创业者，需要快速出原型但不想原型丑到没法给人看。

这个项目的核心关键词里出现了 CLI、browser extension、frontend design、AI coding agents，这几个词拼在一起，基本勾勒出了它的技术轮廓：一个命令行工具负责项目初始化和规范注入，一个浏览器扩展负责实时预览和视觉校验，两者配合，让 AI coding agents 在生成前端代码时有据可依。

2. 核心设计思路拆解：为什么是 CLI 加浏览器扩展

2.1 为什么不做成纯 prompt 方案

很多人第一反应是：为什么不直接写一个超级详细的 system prompt，把设计规范全塞进去？我一开始也这么想，但实测下来发现两个致命问题。第一，prompt 的长度是有边际递减效应的，你塞到几千 token 之后，模型对后面内容的注意力会明显下降，前面说的“用 8px 网格”到后面就忘了。第二，prompt 是“软约束”，模型可以选择性遵守，而 CLI 注入的配置文件是“硬约束”，它会被写进项目里，成为代码的一部分，AI 每次读上下文的时候都会看到。

这就好比你和装修师傅口头说“我要北欧风”，和给他一张详细的施工图纸加材料清单，出来的结果完全不是一个量级。impeccable 的思路就是把“口头描述”变成“施工图纸”。

2.2 CLI 和浏览器扩展的分工逻辑

CLI 负责的是“静态规范”的注入。它在项目根目录生成配置文件，定义好设计 token——颜色、间距、字体、圆角、阴影这些基础变量。这些 token 一旦确定，AI 生成组件时就必须引用这些变量，而不是随手写一个#3b82f6或者margin: 13px。这个约束看起来简单，但效果非常明显：整个项目的视觉一致性会瞬间提升一个档次。

浏览器扩展负责的是“动态校验”。它在你本地开发服务器跑起来之后，实时扫描页面上的元素，检查是否有偏离设计 token 的地方。比如某个按钮的 padding 用了 14px 而不是网格定义的 16px，它就会在扩展面板里标出来。这个反馈循环很短，你改完代码保存，扩展立刻告诉你哪里还有问题。

两者配合的逻辑是：CLI 管“事前预防”，扩展管“事后检查”。事前预防让 AI 一开始就走在正确的路上，事后检查兜住那些漏网之鱼。这个设计比单纯依赖 prompt 或者单纯依赖 lint 工具都要更贴合 AI coding 的实际工作流。

2.3 和现有工具链的关系

你可能会问：这不就是 ESLint 加 Stylelint 吗？我的理解是，它和这些工具有交集但不重合。ESLint 和 Stylelint 管的是代码规范和语法问题，比如有没有用未定义的变量、有没有重复的 CSS 属性。impeccable 管的是设计规范，比如间距是否遵循网格、颜色是否在调色板内、字号层级是否合理。前者是“代码对不对”，后者是“设计对不对”。

而且 impeccable 的浏览器扩展是视觉化的，它不要求你读懂 lint 报错信息，直接在页面上高亮有问题的元素，对非设计背景的开发者友好很多。这个差异点很关键，它决定了这个工具的使用门槛比传统 lint 方案低得多。

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

3.1 前置依赖检查

在装 impeccable 的 CLI 之前，有几件事需要先确认。Node.js 版本建议在 18 以上，我用 16 的时候遇到过依赖解析失败的问题。npm 或者 pnpm 都可以，我个人倾向 pnpm，因为它的依赖树更干净，装完之后 node_modules 的体积能小三分之一左右。

检查命令很简单：

node -v npm -v

如果 Node 版本低于 18，建议先用 nvm 或者 fnm 切一个高版本。这里有个坑：有些系统的包管理器自带的 Node 版本很老，你直接npm install -g装 CLI 可能会报engine相关的错误。遇到这种情况不要硬扛，先升级 Node。

3.2 CLI 安装的两种方式

impeccable 的 CLI 安装方式我试过两种，各有适用场景。

第一种是全局安装：

npm install -g impeccable-cli

全局安装的好处是任何目录下都能直接用impeccable命令，适合你同时在多个项目里切换的情况。坏处是版本管理麻烦，不同项目可能需要不同版本的 CLI，全局只能有一个。

第二种是项目内安装：

npm install -D impeccable-cli

然后通过npx impeccable或者写进 package.json 的 scripts 里来调用。这种方式的好处是版本跟着项目走，团队协作时每个人用的版本一致。我现在的习惯是项目内安装，然后在package.json里加一行：

{ "scripts": { "design:init": "impeccable init", "design:check": "impeccable check" } }

这样团队里其他人 clone 下来之后，直接npm run design:init就能初始化设计规范，不需要额外看文档。

注意：如果你所在的环境对全局安装有权限限制，优先用项目内安装加 npx 的方案，避免因为权限问题卡住。

3.3 初始化项目设计规范

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

npx impeccable init

这个命令会做几件事。第一，检测你当前项目的技术栈，是 React、Vue 还是纯 HTML，它会根据技术栈生成对应的配置文件格式。第二，生成一个design-tokens.json或者design-tokens.ts文件，里面定义了基础的设计变量。第三，在项目里注入一段说明，告诉 AI coding agents 在生成代码时要引用这些 token。

我实测下来，React 项目生成的是 TS 文件，Vue 项目生成的是 JS 文件，纯 HTML 项目生成的是 JSON 加一个 CSS 变量文件。这个适配逻辑做得挺细的，不需要你手动改格式。

初始化完成之后，你会看到类似这样的 token 定义：

{ "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px" }, "colors": { "primary": "#2563eb", "secondary": "#64748b", "background": "#ffffff", "surface": "#f8fafc" }, "radius": { "sm": "4px", "md": "8px", "lg": "16px" } }

这套默认值是基于 8px 网格和一套中性偏冷的调色板生成的。如果你有自己的品牌色或者设计系统，可以直接改这个文件，CLI 会读取你改后的值。

4. 浏览器扩展的安装与配置细节

4.1 扩展的获取和加载

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

这里有个细节：扩展需要读取你本地开发服务器的页面内容，所以安装之后要在扩展设置里把localhost和127.0.0.1加进允许列表。有些浏览器默认会拦截扩展对本地地址的访问，不加白名单的话扩展面板会一直显示“未检测到页面”。

4.2 扩展面板的功能解读

扩展装好之后，打开你的本地开发页面，点击扩展图标，会弹出一个面板。面板里主要显示三类信息。

第一类是“Token 偏差”，列出页面上所有使用了非标准间距、颜色、字号的元素。每个条目会显示当前值和期望值，比如“padding: 14px，期望 16px”。第二类是“层级问题”，检测标题层级是否跳跃，比如 h1 直接跳到 h3，或者字号层级不符合定义的比例。第三类是“对比度检查”，自动计算文字和背景的对比度，低于 WCAG AA 标准的会标红。

我特别喜欢对比度检查这个功能，因为这是人工最容易忽略的地方。AI 生成的颜色组合经常出现浅灰字配白底的情况，肉眼看着还行，但对比度只有 2:1 左右，实际可读性很差。扩展会直接告诉你具体数值，你改起来就有依据。

4.3 和 CLI 的联动机制

扩展和 CLI 之间通过一个本地配置文件通信。CLI 初始化时生成的design-tokens.json会被扩展读取，所以你在 CLI 里改了 token，扩展面板里的期望值也会同步更新。这个联动是自动的，不需要手动刷新。

但有一个坑要注意：扩展读取的是文件系统里的 token 文件，如果你改了 token 但没保存，扩展读到的还是旧值。我有一次改完 token 直接切到浏览器看效果，发现扩展还在报旧标准的偏差，折腾了半天才发现是编辑器没保存。所以养成习惯，改完 token 先 Ctrl+S，再看扩展面板。

5. 把 impeccable 接入 AI coding 工作流

5.1 在 prompt 里引用设计规范

CLI 初始化之后，项目里会多出一个DESIGN.md或者类似的文件，里面用自然语言描述了设计规范。你在给 AI coding agents 写 prompt 的时候，可以直接说“参考项目根目录的 DESIGN.md 生成组件”。这样 AI 在生成代码时会主动去读这个文件，按照里面的 token 来写样式。

我实测下来，加了这句话之后，AI 生成的代码里硬编码颜色和间距的比例明显下降。之前可能有一半的样式是写死的，现在大部分都会引用 CSS 变量或者 token 常量。

5.2 配合 codex cli 等工具的使用姿势

如果你用的是 codex cli 这类命令行 AI 工具，可以在命令里加上项目上下文。比如：

codex cli --context ./DESIGN.md "生成一个用户卡片组件"

这样 codex cli 在生成代码时会优先读取 DESIGN.md 的内容。我试过不加 context 和加 context 的对比，加了的版本生成的组件在间距和颜色上明显更规范，基本不需要二次调整。

对于 codex cli 的常用命令，比如/compact、/model、/resume，我的建议是在生成前端组件之前先用/model确认一下当前用的模型，有些轻量模型对设计规范的理解能力弱一些，生成的结果可能需要更多轮调整。/compact适合在长对话之后压缩上下文，避免 token 超限导致规范被截断。

5.3 在 CI 里加一道设计检查

如果你想让设计规范成为团队共识，可以在 CI 流程里加一步：

npx impeccable check --ci

这个命令会扫描项目里的样式文件，检查是否有偏离 token 的地方，有的话返回非零退出码，CI 就会失败。这样能防止有人手动改样式时不小心引入不一致的值。

不过我的经验是，CI 检查的严格程度要调。如果一上来就设成“任何偏差都失败”，团队里肯定有人抱怨。可以先设成“只警告不失败”，跑一段时间让大家适应，再逐步收紧。

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

6.1 初始化时报错“无法识别技术栈”

这个问题的原因通常是项目根目录没有package.json，或者package.json里没有明确的框架依赖。CLI 靠读package.json的 dependencies 来判断技术栈，如果读不到就会报错。

解决办法有两个：一是确保项目根目录有package.json，二是手动指定技术栈：

npx impeccable init --framework react

支持的框架参数有react、vue、svelte、html，选一个最接近的就行。

6.2 扩展面板显示“未检测到设计 token”

这个问题的排查顺序是这样的。先确认项目根目录有没有design-tokens.json文件，没有的话说明 CLI 初始化没成功。有的话，检查扩展设置里的“Token 文件路径”是否指向了正确的文件。默认路径是项目根目录，但如果你的项目结构比较特殊，token 文件在子目录里，就需要手动改路径。

还有一个容易被忽略的点：扩展读取的是本地文件系统，如果你的开发服务器跑在 Docker 容器里，文件路径可能对不上。这种情况建议把 token 文件挂载到宿主机上，或者直接在宿主机上跑开发服务器。

6.3 AI 生成的代码仍然不遵守 token

如果 AI 生成的代码里还是大量硬编码样式，大概率是 prompt 里没有明确引用 DESIGN.md。AI coding agents 不会自动去读项目里的所有文件，你需要在 prompt 里显式告诉它去读。

另一个可能是 DESIGN.md 的内容太长，AI 读到一半就跳过了。这种情况可以把 DESIGN.md 拆成多个文件，比如DESIGN-COLORS.md、DESIGN-SPACING.md，在 prompt 里只引用当前任务相关的那个。

6.4 常见问题速查表

提示：每次升级 CLI 版本之后，建议重新跑一次impeccable init，因为新版本可能会更新 token 的默认值或者配置文件格式。直接覆盖旧文件就行，CLI 会保留你手动改过的值。

7. 我踩过的几个坑和对应的解法

第一个坑是 token 文件的命名冲突。我有个项目里已经有一个叫design-tokens.json的文件，是之前手动建的，跑impeccable init的时候 CLI 检测到同名文件，直接跳过了生成。结果扩展读的是旧文件，一直报偏差。后来我把旧文件改名，重新跑 init 才解决。所以如果你的项目里已经有类似名字的文件，先备份再初始化。

第二个坑是扩展和开发服务器的端口冲突。我的开发服务器跑在 3000 端口，扩展默认也是去 3000 找页面，但有时候 3000 被其他进程占了，开发服务器自动切到 3001，扩展就找不到了。解决办法是在扩展设置里手动指定端口，或者固定开发服务器的端口不要自动切换。

第三个坑是 AI 对 token 的理解偏差。我在 DESIGN.md 里写了“主色调用 primary”，但 AI 有时候会把 primary 理解成“主要使用的颜色”而不是具体的 token 名。后来我把描述改成“主色调使用 token 名为 primary 的颜色值”，AI 就理解对了。这个细节说明，给 AI 写规范文档时，用词要尽量精确，避免歧义。

8. 这套方案适合什么样的项目

我的判断是，impeccable 这套方案最适合的是中小型前端项目，尤其是那种“一个人或两三个人快速迭代”的场景。大团队通常已经有成熟的设计系统，token 定义比 impeccable 默认的更复杂，接入成本反而高。小项目或者个人项目，没有设计系统，impeccable 提供的默认规范刚好能兜住底线。

另一个适合的场景是原型开发。你需要快速出一个能给人看的 demo，但又不想花时间调样式。用 impeccable 初始化之后，AI 生成的界面至少是整洁的，不会出现明显的视觉问题。这个“至少不难看”的底线，在原型阶段价值很大。

不太适合的场景是高度定制化的设计项目，比如品牌官网或者营销落地页，这些项目对视觉有独特要求，impeccable 的通用规范可能反而是一种限制。这种项目更适合手动设计加 AI 辅助，而不是让 AI 主导生成。

最后分享一个小技巧：如果你觉得 impeccable 的默认 token 太保守，可以在初始化之后手动改design-tokens.json，把间距网格从 8px 改成 4px，或者把圆角调大一些。改完之后重新跑一次impeccable check，确认没有引入新的偏差。这套工具的好处就是，规范是你定的，它只负责帮你执行。