1. 项目缘起一个叫 impeccable 的前端设计工具到底在解决什么问题第一次看到 impeccable 这个词是在一个前端开发者的讨论串里。有人丢了一句“这玩意儿让我的 AI coding agent 终于不瞎写 CSS 了”底下跟了一串追问。我顺着摸过去发现它并不是一个传统意义上的框架或者组件库而是一个围绕AI coding agents做前端设计约束的工具核心形态是CLI加browser extension的组合。说白了impeccable 想干的事情很具体当你在用 Codex CLI、Claude Code 这类 AI 编程代理去生成或修改前端代码时它负责把“设计规范”这件事从人的脑子里、从散落的 Figma 文件里抽出来变成 agent 能读懂、能执行的约束。你让 agent 写一个按钮它不会给你整出三种不同的圆角、四种蓝色、五种间距。这就是它最朴素的价值。我为什么会对这个东西感兴趣因为过去大半年我几乎每天都在跟各种 CLI 形态的 AI 编程工具打交道。从最早的 codex cli 安装踩坑到后来研究 codex cli 命令哪些 /compact /model /resume 怎么配合用再到折腾 openspec cli、minimax cli 这些周边工具我太清楚一个痛点了AI 写前端代码功能能跑但设计一塌糊涂。你让它改一个卡片它能把整个页面的间距体系给你改乱。你让它加个按钮它用的色值跟设计稿差了两个色阶。impeccable 切的就是这个口子。它不跟你聊“AI 会不会取代设计师”这种虚的它解决的是一个非常工程化的问题如何让 AI agent 在生成前端代码时遵守一套可验证、可复现的设计规则。适合谁来参考我觉得三类人最该看一是天天用 AI 写前端但被设计一致性折磨的开发者二是想给团队引入 AI 编码规范的技术负责人三是做 browser extension 或者 CLI 工具、想理解这类工具设计思路的同行。2. 核心机制拆解impeccable 凭什么让 AI 写出“体面”的前端代码2.1 设计约束的“翻译层”才是真正的核心很多人第一眼会把 impeccable 理解成一个 lint 工具或者一个设计 token 管理器。但我觉得它最聪明的地方在于它做的是一个翻译层。左边是人类设计师能理解的设计规范——间距用 4 的倍数、主色只用那一个、圆角只有两档、字号阶梯不超过五级。右边是 AI agent 能执行的指令——在生成代码前先读取约束文件生成后按规则校验不符合就重写。这个翻译层为什么重要因为 AI coding agents 本质上是在做概率生成。你给它一个 prompt“写一个登录表单”它脑子里没有“这个项目的设计体系长什么样”这个概念。它会从训练数据里捞一个“平均好看”的表单出来。但“平均好看”不等于“符合你这个项目的设计规范”。impeccable 做的事情就是在 agent 生成之前把项目的设计约束注入到它的上下文里在生成之后用 browser extension 在真实渲染环境里做校验。我实测下来的感受是没有约束的 agent 像一个刚毕业、审美还行的实习生有了 impeccable 约束的 agent像一个在这个项目里干了半年的中级工程师。差别不在于它会不会写代码而在于它知不知道这个项目的“规矩”。2.2 CLI 与 browser extension 的分工逻辑为什么是 CLI 加 browser extension 这个组合而不是一个纯 CLI 或者一个纯插件这个选型背后有很实际的考量。CLI 负责的是生成前和生成后的静态环节。你在终端里跑impeccable init初始化项目约束跑impeccable check对 agent 刚生成的代码做静态扫描跑impeccable sync把设计 token 同步到代码里的变量文件。这些操作不需要浏览器在 CI 里也能跑适合集成到自动化流程里。Browser extension 负责的是运行时校验。静态扫描能查出“你用了不在规范里的色值”但查不出“这个按钮在 375px 宽度下换行了”“这个卡片的阴影在深色模式下几乎看不见”。这些必须在真实渲染环境里才能发现。extension 把当前页面的计算样式抓出来跟约束文件做比对把偏差直接标在页面上。注意CLI 和 extension 必须共用同一份约束源文件否则会出现“CLI 说通过、extension 说有问题”的尴尬情况。我建议把约束文件放在项目根目录的.impeccable/下两边都指向这个路径。2.3 跟 codex cli、openspec cli 这些工具的关系这里要澄清一个容易混淆的点。impeccable 不是 codex cli 的替代品也不是 openspec cli 的竞品。它更像是这些 AI 编程 CLI 的外挂约束层。你依然用 codex cli 来跟 agent 对话用/compact压缩上下文用/model切换模型用/resume恢复会话。impeccable 是在这个流程里插了一脚在 agent 动手写前端代码之前先把设计约束喂给它在它写完代码之后用 CLI 和 extension 做双重校验。我试过的工作流是这样的先用 codex cli 起一个会话把 impeccable 生成的约束摘要贴进 prompt 里让 agent 基于约束去改代码。改完之后在终端跑impeccable check --diff只检查这次改动涉及的文件。如果 CLI 过了再打开浏览器用 extension 看一眼真实效果。这套流程跑顺之后返工率明显下降。3. 从零上手impeccable 的安装与约束体系搭建3.1 安装前的环境准备与常见坑impeccable 的安装本身不复杂但前置环境有几个坑我踩过提前说清楚能省你不少时间。首先是 Node 环境。如果你之前装 codex cli 的时候就觉得“node 安装 codex cli 很慢”那大概率是 npm 源的问题。impeccable 同样依赖 Node建议先把 npm 源切到国内镜像或者用 pnpm 代替 npm安装速度会快很多。Node 版本建议 18 以上16 在某些依赖上会有兼容问题。其次是 browser extension 的安装。Chrome 和 Edge 都支持但要注意extension 需要读取当前页面的计算样式所以它需要“读取和更改您在所有网站上的数据”这个权限。如果你在公司的安全策略下装不了那就只能退而求其次只用 CLI 做静态校验运行时校验靠手动在 DevTools 里看。提示安装 extension 之后记得在扩展管理页把它固定到工具栏。我第一次装完找了半天没找到入口以为装失败了其实是藏在扩展菜单里。3.2 初始化约束文件impeccable init 到底生成了什么在项目根目录跑impeccable init它会生成一个.impeccable/目录里面通常包含三个文件tokens.json、rules.yaml、ignore。tokens.json是设计 token 的定义。颜色、间距、字号、圆角、阴影、动效时长都在这里。它默认会给一套比较通用的值但你需要根据自己项目的设计稿去改。我建议直接让设计师把 Figma 里的变量导出来转成这个格式比手动填靠谱。rules.yaml是规则定义。比如“禁止使用不在 tokens 里的色值”“间距必须是 4 的倍数”“同一页面内 h1 只能出现一次”。这些规则分三个等级error、warn、info。error 会直接让impeccable check返回非零退出码适合放进 CI。ignore是忽略清单。有些第三方组件库的样式你管不了或者有些历史遗留页面暂时不想动就写在这里。支持 glob 模式比如src/legacy/**。我个人的习惯是tokens.json严格跟设计稿对齐rules.yaml先只开 error 级别的几条核心规则等团队适应了再逐步加 warn 和 info。一上来全开agent 和你都会崩溃。3.3 把约束喂给 AI agent 的三种方式约束文件建好了怎么让 agent 知道我试过三种方式各有适用场景。第一种是手动贴。在 codex cli 的会话里直接把tokens.json的内容贴进 prompt。适合临时改一两个组件不想搞太复杂。缺点是每次都要贴而且 token 多了会占上下文。第二种是写进项目级 agent 配置。如果你用的 agent 支持读取项目里的配置文件比如某些 CLI 会读AGENTS.md或者类似的约定文件就把约束摘要写进去。这样每次起会话agent 自动就能看到。适合长期项目。第三种是用 impeccable 的 sync 命令生成一个摘要文件。impeccable sync --formatprompt会输出一段压缩过的约束描述专门给 agent 读的。我一般把这个输出存成design-context.md然后在 prompt 里引用这个文件。这样既省 token又保证约束是最新的。实操心得不要把所有 token 都塞给 agent。agent 的上下文很宝贵你塞太多它反而会忽略重点。我一般只同步颜色、间距、字号这三类最容易被写乱的圆角和阴影靠 check 阶段兜底。4. 实操全流程用 impeccable 约束一次真实的前端改动4.1 场景设定与改动前基线假设你有一个已有的 React 项目用的是 Tailwind设计稿有一套自己的 token。现在产品要加一个“通知中心”的下拉面板包含一个列表、每条通知有图标、标题、时间、未读标记底部有一个“全部已读”按钮。在没有 impeccable 之前我让 agent 写这个面板出来的代码大概率是这样的间距用p-3、p-4、p-5混着来未读标记用了一个随手写的红色#ff4444时间文字用了text-gray-400但设计稿里其实是text-gray-500按钮的圆角跟项目里其他按钮不一致。功能能跑但设计 review 会被打回。有了 impeccable 之后流程变成先确认约束文件是最新的然后把约束摘要喂给 agent让它基于约束生成代码生成完跑 CLI check再用 extension 看运行时效果。4.2 生成阶段的约束注入与 prompt 写法这一步的关键是 prompt 的写法。不要只说“写一个通知中心面板”要说“基于 design-context.md 里的约束写一个通知中心面板使用项目现有的 Tailwind 配置不要引入新的色值”。我实测下来明确告诉 agent“不要引入新色值”比“请遵守设计规范”有效得多。前者是一个可执行的禁令后者是一个模糊的期望。agent 对禁令的遵守度明显更高。另外如果你用的是 codex cli可以在会话开头用/model切到一个代码能力更强的模型然后在生成前端代码之前用/compact清理一下无关上下文避免之前的对话干扰。生成完之后如果结果不理想用/resume回到之前的节点重新生成比从头再来省时间。4.3 CLI 校验impeccable check 的输出解读代码生成完在终端跑impeccable check。它会扫描项目里的样式文件和相关组件输出一份报告。报告分三块违规项、警告项、通过项。违规项会告诉你哪个文件、哪一行、用了什么值、期望什么值。比如“NotificationPanel.tsx:42使用了色值#ff4444不在 tokens 的 color 集合中最接近的是red-500”。这种提示非常具体你可以直接让 agent 按提示改或者自己手动改。警告项一般是“间距p-3不在 4 的倍数体系里建议改为p-4或p-2”这种。不致命但改了更统一。我一般会跑impeccable check --fix让它自动修那些能自动修的比如色值替换、间距对齐修不了的再手动处理。实测下来大概 70% 的违规能自动修掉。4.4 Browser extension 的运行时校验与视觉回归CLI 过了不代表就万事大吉。打开浏览器加载页面点开 extension 的图标它会做一次运行时扫描。这时候能发现一些静态扫描发现不了的问题。比如有一次CLI 显示所有色值都合规但 extension 标出来“未读标记的圆点在深色模式下对比度不足”。这个问题在代码里看不出来因为色值是合规的但在实际渲染的深色背景上就是看不清。extension 会给出对比度数值并建议调整。还有一次extension 发现“通知列表在 375px 宽度下时间文字换行导致每条通知高度不一致”。这个问题也是静态扫描查不到的必须真实渲染才能发现。注意extension 的扫描结果不会自动同步回 CLI。如果你在 extension 里发现了问题需要手动记下来改完代码再跑一次 CLI check确保没有引入新的静态违规。4.5 把校验接入 CI让约束变成硬门槛如果只是本地跑跑约束很容易被绕过。我的做法是把impeccable check接进 CI在 PR 阶段就跑。一旦有 error 级别的违规直接 fail不允许合并。具体做法是在 CI 配置里加一步安装 impeccable CLI跑impeccable check --levelerror。这样只有 error 级别的违规会阻断合并warn 和 info 只做提示。等团队适应了再逐步把一些 warn 提升为 error。我还见过有人把 extension 的运行时校验也做成了自动化用 Puppeteer 起一个无头浏览器加载页面跑 extension 的扫描逻辑把结果输出成报告。这个方案更重但覆盖更全。适合对设计一致性要求极高的团队。5. 常见问题与排查技巧实录5.1 安装与初始化阶段的典型问题问题现象可能原因排查与解决impeccable init报错找不到命令全局安装没成功或 PATH 没配用npx impeccable init试试或者检查 npm 全局 bin 目录是否在 PATH 里extension 装了但图标不显示被折叠进扩展菜单了在扩展管理页找到 impeccable点“固定”tokens.json改了但 check 不生效有缓存或者路径不对跑impeccable check --no-cache确认约束文件路径是.impeccable/tokens.jsonagent 生成的代码完全无视约束约束没喂进去或者 prompt 太模糊确认 design-context.md 被引用prompt 里明确写“遵守 design-context.md”5.2 校验结果与实际不符怎么办有时候 CLI 说违规但你一看代码觉得没问题。这种情况一般是三种原因。一是约束文件里的 token 跟实际用的 CSS 变量对不上。比如 tokens 里定义的是primary-500但代码里用的是--color-primaryimpeccable 不认识这个变量名。解决办法是在 tokens 里把变量映射关系写清楚。二是第三方组件库的样式被误扫。比如你用了某个 UI 库的 Button它内部用了自己的色值被 impeccable 当成违规。这时候要在ignore里把node_modules或者具体的组件路径排除掉。三是动态样式没被识别。比如你用 JS 算出来的色值impeccable 静态扫描抓不到。这种情况只能靠 extension 的运行时校验兜底。5.3 跟 codex cli 配合时的上下文管理技巧用 codex cli 的时候上下文管理很关键。我踩过的坑是会话开太久前面聊了一堆无关的东西agent 生成前端代码时被干扰约束遵守度下降。我的做法是前端改动单独起一个会话。会话开头先/compact清理然后贴约束摘要再让 agent 动手。改完一个组件就 check 一次不要攒着一起 check。如果发现 agent 开始跑偏用/resume回到上一个正确的节点重新给指令。另外codex cli 的/model命令可以切模型。我实测下来不同模型对约束的遵守度确实有差异。有些模型更“听话”有些模型更“有主见”。如果你的项目对设计一致性要求极高建议多试几个模型选一个遵守度最高的。5.4 约束体系的维护与演进约束不是定完就不管了。设计稿会更新token 会变规则也要跟着调。我的习惯是每次设计稿有大的更新先更新tokens.json然后跑一次全量 check看看有多少存量代码会违规。如果违规太多就先不改把新规则设为 warn等存量代码逐步迁移。如果违规可控就直接设为 error逼着大家改。还有一个技巧是定期 reviewignore清单。有些当初忽略的历史遗留页面可能已经重构了可以移出 ignore。有些新引入的第三方库可能需要加进去。这个清单如果长期不维护会变成藏污纳垢的地方。6. 我对这类工具的一些个人判断用了一段时间 impeccable 之后我最大的感受是AI 编程工具的能力上限很大程度上取决于你给它多少“项目上下文”。同样的模型你只给一句“写个按钮”和给它一套完整的设计约束出来的东西完全是两个质量层级。impeccable 这类工具的价值不在于它用了多高深的技术而在于它把“设计规范”这件事从隐性知识变成了显性约束。它让 agent 有据可依也让 review 有据可查。以前设计 review 靠肉眼现在靠工具效率不是一个量级。当然它也不是银弹。约束体系本身需要维护token 要跟设计稿同步规则要随项目演进调整。如果团队没人愿意花时间维护这套东西那它很快就会变成摆设。但如果你愿意投入一点精力把约束建起来它带来的回报是持续的——每一次 agent 生成代码都在帮你巩固设计一致性而不是制造新的混乱。最后分享一个小技巧如果你刚开始用不要一上来就搞全量约束。先挑一个最常被写乱的维度比如颜色只约束颜色。跑顺了再加间距。一步一步来团队和 agent 都需要适应过程。一口吃成胖子大概率是半途而废。