1. 从“impeccable”这个词说起：它到底想解决什么问题
第一次看到“impeccable”这个项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的场景：你让 AI 帮你写一段前端代码，它给你吐出来一坨能跑但丑得离谱的东西——间距全靠猜、颜色像打翻的调色盘、响应式断点形同虚设。你反复调 prompt，它反复给你“差不多但就是不对”的结果。这个痛点，凡是重度使用 AI coding agents 的人应该都懂。
impeccable 就是冲着这个来的。它本质上是一个围绕AI coding agents 的前端设计质量层，通过CLI和browser extension两种形态介入你的工作流，让 AI 生成的前端代码在视觉层面达到“无可挑剔”的水准。注意，它不是又一个代码生成器，也不是又一个 UI 组件库，它更像是给 AI 装了一双“审美眼睛”和一套“设计规范约束”。
适合谁来用？三类人最该关注：一是天天用 codex cli、zcode cli 这类命令行 AI 工具写前端的人；二是团队里负责把 AI 产出落地成真实产品的工程师；三是那些被 AI 生成的“能用但难看”的界面折磨过的独立开发者。哪怕你只是偶尔让 AI 帮忙写个 landing page，这套东西也能帮你省下大量来回返工的时间。
我先把结论放这儿：impeccable 的价值不在于它多聪明，而在于它把“设计规范”这件事从人的脑子里搬到了工具链里，让 AI 在生成代码的那一刻就被约束住，而不是等你事后去擦屁股。
2. 核心设计思路拆解：为什么是 CLI 加浏览器扩展的组合
2.1 为什么不做成纯插件，也不做成纯命令行
很多人第一反应是：既然要管前端设计，做个浏览器扩展不就行了？或者干脆做成 VS Code 插件？impeccable 选择 CLI + browser extension 双形态，背后有很实在的考量。
CLI 负责的是生成阶段的约束。当你在终端里用 codex cli 或 zcode cli 让 AI 写代码时，impeccable 的 CLI 可以在代码落盘之前就介入，把设计 token、间距体系、颜色规范这些东西注入到 AI 的上下文里。这就像给 AI 发了一份“设计需求说明书”，而不是等它写完你再拿尺子去量。
浏览器扩展负责的是验证阶段的反馈。代码跑起来之后，扩展会在真实渲染环境里检查：这个按钮的对比度够不够？这个卡片的圆角是不是符合体系？移动端断点下有没有元素溢出？这些问题是静态代码分析看不出来的，必须在浏览器里实际渲染才能发现。
两者结合的逻辑是：生成时约束，渲染时验证，形成闭环。我试过只用 prompt 去约束 AI 的设计输出，效果很不稳定，因为 AI 对“间距要合理”这种模糊描述的理解每次都不一样。但如果你给它一套具体的 token 值，比如--space-4: 16px，它就能稳定复现。
2.2 设计 token 是整套体系的锚点
impeccable 的核心机制是围绕design tokens展开的。你可以把它理解成一套“设计变量的中央仓库”：颜色、字号、行高、间距、圆角、阴影，全部以 token 的形式定义一次，然后在所有 AI 生成的代码里引用这些 token。
为什么这招管用？因为 AI 最擅长的是模式匹配，最不擅长的是“感觉”。你告诉它“用舒服的间距”，它每次给你的值都不一样；你告诉它“用var(--space-3)”，它就会老老实实引用。token 把主观的“好看”翻译成了客观的“引用正确变量”，这是让 AI 输出稳定设计质量的关键。
我自己的做法是先定义一套最小 token 集，大概 20 到 30 个变量，覆盖 90% 的常见场景。太多了 AI 会记混，太少了又不够用。下面是我常用的一套基础结构：
:root { /* 间距体系，基于 4px 网格 */ --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --space-6: 24px; --space-8: 32px; --space-12: 48px; --space-16: 64px; /* 字号体系 */ --text-xs: 12px; --text-sm: 14px; --text-base: 16px; --text-lg: 20px; --text-xl: 24px; --text-2xl: 32px; /* 圆角 */ --radius-sm: 4px; --radius-md: 8px; --radius-lg: 16px; --radius-full: 9999px; /* 颜色语义化 */ --color-bg: #ffffff; --color-surface: #f8f9fa; --color-border: #e5e7eb; --color-text: #1a1a1a; --color-text-muted: #6b7280; --color-primary: #2563eb; }这套 token 的好处是，当 AI 生成代码时，你只需要在 prompt 里附上这段定义，然后要求“所有间距必须使用 --space-* 变量，所有颜色必须使用 --color-* 变量”，输出的代码就会自带一致性。实测下来，这比任何“请让设计看起来专业”的提示词都管用。
2.3 与 AI coding agents 的协作边界
这里要说清楚一个容易混淆的点：impeccable 不替代 codex cli 或 zcode cli，它是叠加在这些工具之上的。你的工作流还是：在终端里调用 AI agent 写代码，但 impeccable 的 CLI 会在中间加一层“设计规范注入”和“输出校验”。
具体来说，它做三件事：第一，在 AI 生成前，把 token 定义和设计约束塞进上下文；第二，在 AI 生成后，扫描输出代码，检查是否有硬编码的颜色值、魔法数字间距、不符合体系的圆角；第三，把违规项报告出来，甚至可以配置成自动修复。
这个边界很重要，因为很多人会误以为 impeccable 是个独立的 AI 工具。不是的，它是寄生在你现有 AI 工作流上的质量层。你原来的工具照用，只是多了一道设计把关。
3. 核心细节解析与实操要点
3.1 CLI 的安装与初始化配置
impeccable 的 CLI 安装方式跟大多数现代前端工具类似，走 npm 生态。我建议全局安装，因为你会频繁在不同项目里调用它：
npm install -g impeccable-cli装完之后，在项目根目录执行初始化：
impeccable init这个命令会做几件事：生成一个impeccable.config.json配置文件，创建tokens.css设计变量文件，并且在你的 AI agent 配置里注册一个 pre-prompt hook。所谓 pre-prompt hook，就是在你每次调用 AI 生成代码之前，自动把设计规范附加到 prompt 里。
配置文件的结构大概长这样：
{ "tokensFile": "./src/styles/tokens.css", "enforceTokens": true, "forbiddenPatterns": [ "#[0-9a-fA-F]{3,8}", "\\d+px" ], "autoFix": false, "agent": "codex" }这里有几个参数值得展开说。enforceTokens设为 true 时，CLI 会强制检查所有颜色和间距是否引用了 token，发现硬编码就报错。forbiddenPatterns是正则数组，用来匹配你不希望出现在输出里的模式，比如十六进制颜色值和裸 px 值。autoFix我建议初期设为 false，先观察 AI 的输出习惯，等稳定了再开启自动修复。
注意：
forbiddenPatterns里的正则要小心写。我一开始把\d+px加进去，结果连1px solid这种边框都被拦了。后来改成只匹配间距相关的属性，或者用更精确的上下文匹配，才避免误伤。
3.2 浏览器扩展的安装与实时校验
浏览器扩展的安装走的是常规的开发者模式加载流程。下载扩展包之后，在浏览器扩展管理页面开启开发者模式，选择“加载已解压的扩展程序”，指向解压后的目录即可。
装好之后，扩展会在你打开本地开发服务器页面时自动激活。它的工作方式是：注入一个轻量的检查脚本，遍历 DOM 节点，读取计算样式，然后跟你的 token 定义做比对。比对结果会以浮层的形式显示在页面角落，用颜色标记问题严重程度。
扩展检查的维度包括：
| 检查项 | 说明 | 严重程度 |
|---|---|---|
| 颜色对比度 | 文字与背景的对比度是否达到 WCAG AA 标准 | 高 |
| 间距一致性 | 元素间距是否落在 token 定义的网格上 | 中 |
| 字号层级 | 是否使用了定义外的字号值 | 中 |
| 圆角规范 | 圆角值是否来自 token 体系 | 低 |
| 响应式溢出 | 在预设断点下是否有元素超出容器 | 高 |
我特别喜欢它的对比度检查，因为这是 AI 最容易翻车的地方。AI 经常生成浅灰文字配白底，看起来“高级”，实际上根本看不清。扩展会直接标红，告诉你对比度只有 2.1:1，远低于 4.5:1 的标准。
3.3 设计 token 的注入策略
token 注入不是简单地把 CSS 文件丢给 AI 就完事，这里面有策略。我的经验是分三层注入：
第一层是变量定义本身，就是上面那段:root代码。这层必须完整给到 AI，让它知道有哪些可用的值。
第二层是使用示例，给 AI 看两三个正确使用 token 的代码片段。比如一个按钮组件、一个卡片组件，展示padding: var(--space-4)和color: var(--color-text)这种写法。AI 是模仿型选手，给它看例子比给它讲道理有效得多。
第三层是禁止清单，明确告诉它不要写#fff、不要写margin: 13px、不要写border-radius: 7px。这层是负向约束，配合 CLI 的forbiddenPatterns使用。
三层注入之后，AI 的输出质量会有肉眼可见的提升。我做过对比测试，同样一个“生成一个 pricing card 组件”的 prompt，没有 token 注入时 AI 输出了 6 种不同的间距值和 4 种不同的圆角值；有 token 注入后，所有值都收敛到了体系内。
3.4 与 codex cli、zcode cli 的集成细节
如果你用的是 codex cli，集成方式是在它的配置文件里加一个 pre-execution hook。具体路径取决于你的安装方式，通常在~/.codex/config.toml或项目级的.codex/config.toml里。加一段：
[hooks] pre_prompt = "impeccable inject --format=markdown"这行的意思是，每次 codex cli 准备发送 prompt 给模型之前，先执行impeccable inject命令，把设计规范以 markdown 格式输出，附加到 prompt 前面。
zcode cli 的集成类似，但它的 hook 机制可能用不同的配置键名。我建议先跑impeccable inject --dry-run看看输出内容，确认格式没问题再接入。
提示：不同版本的 CLI 工具 hook 配置格式可能有差异，接入前先查一下你所用版本的文档。我踩过一次坑，配置写对了但键名大小写错了，结果 hook 一直不触发，排查了半天。
4. 完整实操流程：从零搭一个受约束的前端生成环境
4.1 环境准备与依赖确认
开始之前，确认你的环境满足这些条件：Node.js 18 以上、npm 或 pnpm 可用、一个能跑的本地开发服务器（Vite、Next.js dev server 都行）、以及你常用的 AI coding agent CLI 已经装好并能正常调用。
我个人的组合是 pnpm + Vite + codex cli，这套组合启动快、热更新灵敏，配合 impeccable 的浏览器扩展体验很顺。如果你用 zcode cli 也没问题，原理一样。
第一步，建项目：
pnpm create vite my-project --template react-ts cd my-project pnpm install第二步，装 impeccable：
pnpm add -D impeccable-cli pnpm exec impeccable init初始化完成后，检查一下生成的tokens.css是否被正确引入到入口文件。Vite 项目里通常是在main.tsx或main.ts里 import。
4.2 定义你的第一套设计 token
不要直接用默认生成的 token，那只是个模板。花十分钟根据你的项目调一下。我的建议是：先确定主色和中性色，再定间距网格，最后定字号和圆角。
间距网格我强烈建议用 4px 基准，因为绝大多数设计系统都建立在这个基准上，AI 对这个网格的“理解”也最好。字号用 1.25 或 1.333 的模数递增，视觉上最舒服。
调好之后，把tokens.css的内容复制一份到项目根目录的DESIGN.md里，用自然语言描述每个 token 的用途。这份 markdown 会在注入时一起给到 AI，帮助它理解“什么时候用哪个 token”。
4.3 配置 AI agent 的注入 hook
以 codex cli 为例，在项目根目录创建.codex/config.toml：
[hooks] pre_prompt = "pnpm exec impeccable inject --tokens ./src/styles/tokens.css --format=markdown" [context] extra_files = ["DESIGN.md"]配置好之后，跑一次测试：
codex "生成一个用户登录表单组件"观察输出代码里是否引用了 token 变量。如果还是出现硬编码值，检查 hook 是否真的执行了。可以在 hook 命令后面加&& echo "hook executed"来确认。
4.4 浏览器扩展的实时验证
启动开发服务器：
pnpm dev然后在浏览器里打开本地地址，点击 impeccable 扩展图标，选择“启用当前页面检查”。扩展会开始扫描，几秒后页面右下角出现检查面板。
面板里会列出所有发现的问题，按严重程度排序。点击某一条，页面上对应的元素会高亮。我通常的处理顺序是：先修对比度问题（影响可访问性），再修间距和字号（影响一致性），最后处理圆角这类细节。
4.5 迭代与收敛
第一轮生成和检查之后，你会发现 AI 的输出有一些固定的“坏习惯”。比如它特别喜欢用#333这种颜色，或者喜欢给卡片加box-shadow: 0 2px 4px rgba(0,0,0,0.1)这种不在体系里的阴影。
把这些高频违规项加到forbiddenPatterns里，同时在DESIGN.md里明确写出替代方案。比如：“阴影统一使用--shadow-sm、--shadow-md、--shadow-lg三档，禁止自定义阴影值。”
迭代两三轮之后，AI 的输出就会明显收敛。我实测下来，大概经过 3 到 5 次迭代，AI 生成的前端代码就能达到“基本不需要手动调样式”的水平。
5. 常见问题与排查技巧实录
5.1 注入不生效的排查路径
这是最高频的问题。症状是：配置都写了，但 AI 输出还是老样子。排查顺序如下：
先确认 hook 命令本身能跑通。手动执行pnpm exec impeccable inject --tokens ./src/styles/tokens.css，看有没有正常输出。如果报错，多半是路径问题或 token 文件格式问题。
再确认 hook 被触发了。在 hook 命令里加日志输出，或者看 AI agent 的 verbose 日志里有没有注入内容。codex cli 可以用--verbose参数看详细过程。
最后确认注入内容被 AI 采纳了。有时候注入是成功的，但 AI 忽略了。这时候要检查注入内容的格式和位置。我的经验是，把设计规范放在 prompt 的最前面，并且用明确的分隔符（比如--- DESIGN CONSTRAINTS ---）标出来，AI 的采纳率会高很多。
5.2 token 冲突与覆盖问题
如果你项目里已经有一套 CSS 变量，impeccable 的 token 可能会跟它们冲突。典型症状是样式时好时坏，或者某些组件突然变色。
解决办法是给 impeccable 的 token 加命名空间前缀。在impeccable.config.json里配置：
{ "tokenPrefix": "imp" }这样生成的变量就是--imp-space-4而不是--space-4，避免跟现有体系打架。代价是 AI 生成代码时要多写几个字符，但换来的是确定性。
5.3 浏览器扩展误报处理
扩展的检查规则是通用的，但你的项目可能有特殊情况。比如你确实需要一个 13px 的字号，因为它不在标准体系里但设计稿就是这么定的。
这时候可以在扩展设置里加白名单。支持按选择器、按属性、按具体值三种白名单方式。我一般用选择器白名单，比如把.custom-badge这个类加进去，扩展就不再检查它内部的样式值。
注意：白名单是双刃剑，加多了等于没检查。我的原则是：只有设计稿明确要求且无法用 token 表达的值才加白名单，其他一律改代码适配 token。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 解决方向 |
|---|---|---|
| AI 输出仍有硬编码颜色 | hook 未触发或注入内容被忽略 | 检查 hook 日志，调整注入格式 |
| 扩展面板不显示 | 扩展未在当前页面激活 | 点击扩展图标手动启用 |
| token 变量未定义报错 | tokens.css 未引入或路径错误 | 检查入口文件 import |
| 自动修复改坏了代码 | autoFix 规则过于激进 | 关闭 autoFix，改用手动确认 |
| 不同页面检查结果不一致 | 页面加载时机早于扩展注入 | 刷新页面或调整扩展注入时机 |
5.5 几个我踩过的坑
第一个坑：一开始我把forbiddenPatterns写得太宽泛，结果 AI 生成的 SVG 里的fill="#fff"也被拦了。后来改成只检查 CSS 属性值，不检查 SVG 属性，才解决。
第二个坑：浏览器扩展在 React 严格模式下会重复检查，导致面板里同一个问题出现两次。这是扩展的已知行为，不影响使用，但看着烦。可以在设置里开启“去重显示”。
第三个坑：token 文件里如果用了 CSS 嵌套语法（比如&:hover），某些版本的注入解析器会报错。解决办法是 token 文件保持扁平，不要用嵌套。
6. 进阶玩法：把 impeccable 接入团队协作流程
6.1 在 CI 里加一道设计质量门禁
个人用熟了之后，很自然会想把它推到团队层面。最直接的做法是在 CI 流水线里加一个 impeccable 检查步骤：
- name: Design Quality Check run: pnpm exec impeccable check --tokens ./src/styles/tokens.css --fail-on error这行命令会扫描代码库，发现违规就返回非零退出码，阻断合并。--fail-on error表示只有 error 级别的问题才阻断，warning 级别只报告不阻断。
我建议初期设成--fail-on error，等团队适应了再收紧到--fail-on warning。一上来就卡太严，大家会有抵触情绪。
6.2 多人协作时的 token 版本管理
token 文件是团队共享的设计资产，必须纳入版本管理。但直接改 token 会影响所有人的输出，所以需要一套变更流程。
我的做法是：token 变更走 PR，PR 里必须包含变更理由和影响范围说明。CI 里加一个检查，如果 token 文件有改动，自动在 PR 里评论提醒所有前端成员 review。这样避免有人随手改了个颜色值，导致全团队的 AI 输出都变了。
6.3 与设计工具的联动
如果你的团队用 Figma，可以把 Figma 的 design tokens 导出成 JSON，然后写个脚本转成 impeccable 的 CSS token 格式。这样设计稿和代码之间的 token 就完全同步了，AI 生成的东西天然就跟设计稿一致。
这个联动我做了半年多，最大的收益是：设计师改了一版间距，我跑个脚本同步 token，然后 AI 生成的代码自动就跟上了新规范，不需要手动改任何组件代码。
7. 我对这套工具链的真实体会
用 impeccable 大概三个月之后，我最大的感受是：它改变的不是 AI 的能力，而是我跟 AI 协作的方式。以前我是“生成-检查-返工”的循环，现在变成了“约束-生成-验证”的流水线。返工量至少降了七成。
但它不是银弹。token 体系需要你花时间设计，hook 配置需要调试，浏览器扩展的误报需要处理。前期投入大概两三天，之后就是持续收益。如果你只是偶尔用 AI 写个 demo，可能不值得折腾；但如果你是每天都要跟 AI 协作写前端的人，这套东西值得认真搭一次。
最后分享一个我最近发现的小技巧：把DESIGN.md里的 token 说明写成“给 AI 看的文档”，而不是“给人看的文档”。什么意思呢？就是多用祈使句和明确的条件判断，比如“当需要强调文字时，使用--color-primary，不要使用加粗”。AI 对这种指令式描述的遵循度，比描述性文字高得多。这个细节调整之后，我的注入采纳率又上了一个台阶。
