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}, \\dpx ], autoFix: false, agent: codex }这里有几个参数值得展开说。enforceTokens设为 true 时CLI 会强制检查所有颜色和间距是否引用了 token发现硬编码就报错。forbiddenPatterns是正则数组用来匹配你不希望出现在输出里的模式比如十六进制颜色值和裸 px 值。autoFix我建议初期设为 false先观察 AI 的输出习惯等稳定了再开启自动修复。注意forbiddenPatterns里的正则要小心写。我一开始把\dpx加进去结果连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 --formatmarkdown这行的意思是每次 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第二步装 impeccablepnpm 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 --formatmarkdown [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 变更走 PRPR 里必须包含变更理由和影响范围说明。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 对这种指令式描述的遵循度比描述性文字高得多。这个细节调整之后我的注入采纳率又上了一个台阶。
