1. 项目缘起一个叫 impeccable 的前端设计工具到底想解决什么问题第一次看到impeccable这个词是在几个 AI coding agent 的讨论串里。它本身是个英文形容词意思是“无可挑剔的、完美的”放在前端设计语境下指向的其实是一个非常具体的痛点AI 写出来的界面功能能跑但视觉上总差那么一口气。我自己用各类 CLI 编码代理codex cli、claude code 这类做过不少前端页面深有体会。你让它生成一个登录表单它能给你一个能用的表单但间距是随意的、颜色是拍脑袋的、圆角和阴影的搭配经常显得廉价。你反复用自然语言描述“再精致一点”“间距统一一下”它改是改了但改完还是差点意思而且每次都要重新描述一遍效率极低。impeccable这个项目切入的正是这个缝隙。它不是一个从零生成 UI 的工具而更像是一层设计约束层——把“什么叫好看”这件事从模糊的自然语言描述变成一套可执行、可复用、可被 AI 代理直接调用的规则和检查机制。它通常以 CLI 工具或浏览器扩展的形式存在让 AI coding agent 在生成或修改前端代码时能自动套用一套设计规范并且在输出后做一轮“设计体检”。所以这篇文章要聊的不是某个具体版本的 API 文档而是围绕impeccable这个方向把它背后的设计思路、CLI 工具的实操方式、和 AI coding agent 的配合方法、以及我踩过的坑完整拆一遍。适合两类人看一是天天用 AI 写前端、但被“AI 审美”折磨的开发者二是想给自己的 AI 工作流加一层设计质量保障的工程师。哪怕你之前没用过任何 CLI 代理跟着走也能上手。2. 核心思路拆解为什么“设计规范”要交给工具而不是靠嘴说2.1 自然语言描述设计的三个致命缺陷先说清楚为什么“让 AI 自己审美”这条路走不通。我用 codex cli 和类似的代理做过大量前端任务总结下来纯靠自然语言驱动设计有三个绕不过去的坑。第一个是不可复现。你今天说“用柔和的配色”AI 给你一套莫兰迪色明天同样一句话它可能给你一套马卡龙色。因为“柔和”这个词在模型的语义空间里没有唯一解它每次采样都可能落在不同位置。结果就是同一个项目里不同页面风格不统一改到最后你自己都不知道基准是什么。第二个是不可量化。“间距大一点”到底是 16px 还是 24px“圆角柔和”是 8px 还是 12px自然语言天然缺少数值精度而设计的精致感恰恰藏在数值的一致性里。一个页面里出现 13px、15px、17px 三种间距视觉上就是乱的但 AI 不会主动帮你统一因为它没有“间距刻度”这个概念。第三个是不可检查。你没法在 CI 里跑一条命令说“检查这个页面够不够好看”。自然语言描述无法转成断言也就无法自动化。每次改完都得人肉盯着看这在批量生成页面的场景下完全不可行。impeccable这类工具的价值就是把上面三件事变成规则、刻度、断言。它把设计决策从“形容词”翻译成“设计令牌design tokens 约束规则 检查项”让 AI 代理有据可依让结果可复现、可量化、可自动检查。2.2 设计令牌把“好看”拆成可执行的数值设计令牌这个词听起来玄其实很朴素。它就是一套命名好的数值变量比如间距刻度space-1: 4px、space-2: 8px、space-3: 12px、space-4: 16px、space-6: 24px、space-8: 32px字号阶梯text-xs: 12px、text-sm: 14px、text-base: 16px、text-lg: 18px、text-xl: 20px、text-2xl: 24px圆角radius-sm: 4px、radius-md: 8px、radius-lg: 12px、radius-full: 9999px颜色主色、辅助色、中性色各若干档每档有明确用途一旦这些令牌被定义好AI 代理在写样式时就不再是“随便给个值”而是“从刻度里挑一个”。impeccable的核心工作之一就是把这套令牌体系注入到 AI 代理的上下文里并且在它生成代码后检查有没有“越界”——比如用了不在刻度里的 13px 间距就会被标记出来。我实测下来光是“强制使用间距刻度”这一条就能让 AI 生成的页面精致度提升一个档次。因为视觉混乱的根源往往不是配色而是间距和字号的不统一。2.3 为什么选择 CLI 浏览器扩展的组合形态impeccable相关的工具链里CLI 和浏览器扩展是两个高频出现的形态它们分工不同。CLI 负责生成阶段和检查阶段。你在终端里跑一条命令它把设计规范注入到当前项目的配置里AI 代理读这个配置来生成代码生成完之后再跑一条检查命令它扫描产物报告哪些地方违反了规范。这个流程可以塞进 git hook 或者 CI做到每次提交自动体检。浏览器扩展负责预览阶段和实时反馈。页面跑起来之后扩展可以在浏览器里叠加一层“设计标尺”把间距、字号、颜色对比度这些指标可视化出来甚至直接标红不合规的元素。这样你在开发时就能肉眼看到问题而不是等到 code review 才发现。两者配合的逻辑是CLI 管“写的时候别写错”扩展管“写完了看得见”。这个组合不是拍脑袋定的而是因为设计质量的保障天然需要“事前约束 事后检查”两道关缺一不可。3. 环境准备CLI 工具安装与 AI 代理接入的完整流程3.1 安装前的依赖梳理在动手之前先把依赖理清楚。impeccable这类工具通常依赖 Node.js 环境因为前端生态的 CLI 大多基于 npm 分发。我建议用 Node 18 或 20 的 LTS 版本太老的版本会在装某些依赖时卡住。如果你之前装过 codex cli 之类的工具可能已经踩过“node 安装 codex cli 很慢”的坑。这个慢通常不是网络问题而是 npm 默认源在国内访问不稳定加上某些包体积大。解决办法是换一个响应快的镜像源或者用 pnpm 替代 npmpnpm 的并行下载和硬链接机制在装大依赖树时快很多。# 检查 node 版本 node -v # 如果版本太低用 nvm 切换 nvm install 20 nvm use 20 # 换用 pnpm如果还没装 npm install -g pnpm # 验证 pnpm -v提示不要用 sudo 装全局包容易导致权限混乱。如果遇到 EACCES 错误正确做法是配置 npm 的用户级全局目录而不是加 sudo。3.2 安装 impeccable 相关 CLI安装命令本身很简单但有几个细节值得说。# 全局安装假设包名为 impeccable-cli实际以官方为准 pnpm add -g impeccable-cli # 验证安装 impeccable --version如果安装过程中卡在某个包上先别急着反复重试。用pnpm add -g impeccable-cli --reporterappend-only可以看到详细的下载进度定位到底卡在哪个依赖。我遇到过卡在某个二进制包下载的情况换成 pnpm 之后就好了。安装完成后第一件事是初始化项目配置# 在项目根目录执行 impeccable init这个命令会在项目里生成一个配置文件通常是impeccable.config.json或类似名字里面包含设计令牌的定义、检查规则的开关、以及忽略路径。这个文件是整个工具链的核心AI 代理读它、检查命令读它、浏览器扩展也读它。3.3 把设计规范接入 AI coding agent这一步是很多人卡住的地方。CLI 装好了但 AI 代理怎么知道要用这套规范主流做法有两种。一种是通过项目根目录的约定文件比如AGENTS.md或.cursorrules这类把设计规范的存在和用法写进去AI 代理在读取项目上下文时会自动加载。另一种是通过 CLI 提供的inject命令把规范内容写进代理的配置文件。# 把设计规范注入到 AI 代理的上下文配置 impeccable inject --target codex执行完之后代理在生成前端代码时就会优先使用配置里的设计令牌。我建议在AGENTS.md里再补一段明确指令比如“所有间距必须从 impeccable 配置的 space 刻度中选取禁止使用刻度外的值”双保险。注意不同代理读取上下文的机制不一样。codex cli 读的是项目根目录的约定文件有些代理读的是独立配置目录。注入命令跑完后最好手动确认一下配置文件里确实写进去了内容别想当然。4. 实操核心用 impeccable 约束 AI 生成前端页面的完整流程4.1 定义一套最小可用的设计令牌不要一上来就搞几百个令牌那样维护成本高AI 也容易挑花眼。我的经验是先定义一套最小可用集覆盖 80% 的场景。类别令牌名值用途间距space-14px图标与文字间隙间距space-28px紧凑元素间距间距space-416px常规元素间距间距space-624px区块内间距间距space-832px区块间间距字号text-sm14px辅助文字字号text-base16px正文字号text-lg18px小标题字号text-2xl24px大标题圆角radius-md8px卡片、按钮圆角radius-full9999px头像、标签这套刻度不是随便定的。间距用 4 的倍数是因为大多数屏幕像素密度下4 的倍数能保证元素对齐到物理像素不会出现半像素模糊。字号阶梯的比值大约在 1.125 到 1.2 之间这是排版学里比较舒服的缩放比例跳得太大会显得突兀太小又拉不开层次。4.2 让 AI 代理按规范生成页面配置好之后给 AI 代理下指令时重点不是描述“要好看”而是明确“用哪套令牌”。比如生成一个卡片组件我会这样写指令生成一个用户信息卡片组件要求 - 卡片内边距使用 space-6 - 卡片圆角使用 radius-md - 标题字号 text-lg正文字号 text-base - 卡片之间的间距使用 space-8 - 颜色从配置的 color 令牌中选取这样 AI 就不需要“猜”你要多大间距它直接从令牌里取值。生成出来的代码间距和字号天然是统一的。实测下来同样的需求用令牌约束比用自然语言描述生成结果的精致度差异非常明显。前者基本一次成型后者平均要改三到五轮。4.3 生成后的自动检查代码写完之后跑检查命令impeccable check ./src它会扫描指定目录下的样式文件报告违规项。典型的输出长这样src/components/UserCard.css line 12: padding: 13px - 不在 space 刻度内建议改为 space-3 (12px) 或 space-4 (16px) line 18: border-radius: 6px - 不在 radius 刻度内建议改为 radius-sm (4px) 或 radius-md (8px) line 25: color: #3a7bd5 - 不在 color 令牌内建议使用 color-primary这种报告的价值在于它把“感觉不对”变成了“具体哪一行哪个值不对”。修起来目标明确而且修完之后整个项目的视觉一致性会明显提升。4.4 浏览器扩展的实时预览CLI 检查是事后的浏览器扩展是事中的。装上扩展之后打开本地开发页面它会叠加一层可视化标记所有间距用不同颜色的色块标出一眼能看出哪些间距不一致字号用标尺线标出能看出层级是否清晰颜色对比度不足的元素会被高亮提示可访问性问题我习惯在开发时一直开着这个扩展边写边看。很多时候 AI 生成的代码在编辑器里看不出问题一渲染出来就发现某个间距明显偏大这时候立刻改比等到最后统一检查效率高得多。5. 常见问题与排查技巧实录5.1 安装与配置阶段的典型问题问题现象可能原因解决办法安装卡住不动依赖源响应慢换 pnpm 或配置镜像源命令找不到全局 bin 目录不在 PATH检查 npm 全局目录并加入 PATHinject 后代理没反应代理读取的配置文件路径不对手动确认配置文件内容必要时手动写入init 生成的配置为空权限问题或目录不对确认在项目根目录执行检查写权限这里重点说“inject 后代理没反应”这个坑。我遇到过好几次命令跑完提示成功但 AI 代理生成代码时完全没用到设计令牌。排查下来发现注入命令写的是 A 文件但代理实际读的是 B 文件。不同代理的约定不一样有的读AGENTS.md有的读.agent/config有的读独立目录。最稳妥的办法是注入后手动打开配置文件看一眼确认内容真的写进去了而且写在了代理会读的位置。5.2 生成结果不符合规范的排查思路有时候 AI 代理明明读了规范生成出来的代码还是用了刻度外的值。这种情况通常有三个原因。一是指令不够明确。如果你只说“生成一个卡片”代理可能觉得设计规范是“建议”而非“强制”。解决办法是在指令里明确写“必须使用配置中的令牌禁止使用刻度外的值”。二是规范文件太长代理没读完。如果设计令牌定义了几百行代理的上下文窗口可能只加载了前面一部分。解决办法是精简令牌集或者把最常用的令牌放在文件最前面。三是代理版本对上下文注入的支持不完善。这种情况只能靠事后检查命令兜底生成完跑一遍impeccable check把违规项反馈给代理让它修。5.3 几个我踩过的坑第一个坑是令牌定义太细。一开始我定义了 20 档间距结果 AI 每次都要在 20 个选项里挑反而容易挑错而且我自己也记不住哪档对应哪个场景。后来精简到 6 档效果好很多。令牌不是越多越好够用就行。第二个坑是忽略暗色模式。设计令牌如果只定义了一套颜色暗色模式下就会出问题。正确做法是颜色令牌分 light 和 dark 两套或者用语义化命名如color-bg、color-text让具体色值随主题切换。第三个坑是检查命令跑太晚。我一开始习惯写完整个页面再跑检查结果一次报几十个违规改起来很痛苦。后来改成每写完一个组件就跑一次问题即时发现即时修效率高很多。6. 工具选型与工作流整合的几点经验6.1 CLI 工具之间的配合如果你同时用多个 CLI 工具比如 codex cli 做代码生成、其他 CLI 做构建和部署要注意它们之间的配置不要打架。impeccable的配置文件应该作为设计规范的唯一来源其他工具读它就行不要各自维护一套。我见过有人把设计令牌同时写在三个地方结果改了一处忘了另两处最后页面风格分裂。单一数据源这个原则在设计规范上同样适用。6.2 把检查塞进 git hook手动跑检查容易忘最好的办法是塞进 git hook提交前自动跑。# .husky/pre-commit impeccable check ./src --fail-on-error--fail-on-error的作用是发现违规就返回非零退出码阻止提交。这样能保证进仓库的代码都是符合设计规范的。当然如果项目还在快速迭代期可以先不加这个参数只报告不阻断等稳定了再开启。6.3 浏览器扩展的使用时机浏览器扩展不是任何时候都开着好。页面元素特别多的时候叠加层会影响性能拖慢开发时的热更新。我的习惯是写单个组件时开着方便看间距和字号调试复杂交互时关掉避免干扰。另外扩展的可视化标记有时候会和页面本身的样式冲突比如它给元素加的 outline 可能覆盖你自己的 focus 样式。遇到这种情况在扩展设置里关掉对应的标记层就行。7. 关于设计规范落地的一点个人体会用impeccable这套思路做前端最大的感受是AI 不是不会做设计而是缺少约束。你给它一套明确的刻度它就能稳定输出精致的结果你不给它就只能靠概率采样结果自然飘忽不定。我现在的习惯是任何用 AI 代理做前端的项目第一步都是先把设计令牌定下来哪怕只有间距和字号两组。这一步花不了十分钟但能省下后面大量的返工时间。而且这套令牌一旦定好换任何 AI 代理都能用不绑定特定工具迁移成本很低。还有一点设计规范不是定完就一劳永逸的。项目做大了场景变多了令牌需要扩展。扩展的时候注意保持刻度的连续性比如间距从 4 的倍数扩展到 4 和 8 的倍数混用要确保新加的档位和旧的能和谐共存别出现 12px 和 14px 这种相邻太近的档位那样反而增加选择困难。最后分享一个小技巧如果你不确定某个间距该用哪档就在浏览器扩展里打开标尺看看页面上现有元素的间距分布选出现频率最高的那档。这样能保证新加的元素和已有元素视觉上是一体的而不是突兀地插进去。