1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI 帮你写一段前端代码它给你吐出来一坨能跑但丑得离谱的东西——间距忽大忽小、颜色搭配像打翻了调色盘、响应式断点全靠猜。你反复在 prompt 里写“make it beautiful”结果它给你加了一堆渐变和阴影反而更糟。impeccable 就是冲着这个痛点来的。它本质上是一套面向AI coding agents的前端设计约束层通过CLI和browser extension两种形态把“什么叫好看”这件事从模糊的自然语言描述变成 agent 可以理解、可以执行、可以验证的结构化规则。换句话说它不是在教你怎么写 CSS而是在教 AI 怎么写出不丢人的 CSS。这个项目适合谁三类人值得认真看一是天天用 Codex CLI、Claude Code 这类工具写前端但总在审美上翻车的开发者二是想给自己的 AI 工作流加一道“设计质检”环节的团队三是对frontend design自动化感兴趣、想搞清楚 agent 到底能不能理解美学这件事的技术人。不管你用的是哪家的 CLI核心思路是通用的。我花了大概两周时间把它的 CLI 和浏览器扩展两条路径都跑了一遍踩了不少坑也总结出一些文档里不会写的经验。下面按我实际使用的顺序来拆。2. 核心设计思路拆解为什么是“约束层”而不是“生成器”2.1 一个关键判断AI 不缺生成能力缺的是判断标准很多人对 AI 写前端的期待是“你给我生成一个漂亮的页面”。但实际用下来你会发现模型生成 CSS 的能力早就够用了真正的问题是它不知道什么叫做“够好了”。你让它写一个卡片组件它能写出来但它不知道 16px 和 24px 的间距在这个场景下哪个更合适不知道阴影的模糊半径超过多少就会显得脏。impeccable 的设计哲学就是不去重新造一个生成模型而是给现有的 agent 套一层设计判断标准。这层标准以规则集的形式存在agent 在生成代码前后都可以调用它来做校验和修正。这个思路我觉得比“训练一个专门写前端的模型”务实得多因为设计品味这件事太主观了靠训练很难收敛但靠规则约束是可以做到的。提示如果你之前用过类似“AI 设计系统”的工具会发现它们大多走的是组件库路线——给你一堆预设组件让 AI 去拼。impeccable 走的是另一条路它不提供组件提供的是判断依据。这个区别很关键决定了它的适用范围更广但也意味着你需要自己准备组件基础。2.2 CLI 与 browser extension 的分工逻辑项目同时提供 CLI 和浏览器扩展这不是重复建设而是对应了两个完全不同的使用场景。CLI 的定位是批量和集成。你在终端里跑impeccable check ./src这样的命令它扫描你的代码文件输出一份设计规范符合度报告。这个模式适合放进 CI 流程或者在你用 Codex CLI 生成完一批代码之后做一次统一质检。它的优势是快、可脚本化、能处理整个项目。浏览器扩展的定位是实时和可视化。你打开一个页面扩展会在侧边栏里标出哪些元素违反了设计规则比如“这个按钮的对比度不足”“这个间距不在允许的刻度上”。这个模式适合调试阶段尤其是当你想搞清楚“为什么这个页面看起来就是不对劲”的时候。我自己的用法是开发阶段开着扩展边写边看提交之前跑一遍 CLI 做最终检查。两条路径配合起来基本能覆盖从写到验的完整闭环。2.3 规则集的来源与可扩展性impeccable 内置的规则集不是拍脑袋定的它参考了几套成熟的设计系统规范包括间距刻度、字号阶梯、颜色对比度标准这些。但真正让我觉得有意思的是它的规则文件是可读可改的。你可以在项目根目录放一个配置文件覆盖默认规则。举个例子默认的间距刻度是 4px 的倍数但如果你团队用的是 8px 基准直接改配置就行。这个设计避免了“工具和团队规范打架”的尴尬也是它能落地到实际项目的前提。我见过太多设计工具因为不可配置而被弃用impeccable 在这一点上做对了。3. 环境准备与 CLI 安装实操3.1 安装前的依赖检查在装 impeccable CLI 之前有几件事必须先确认。首先是 Node 版本我实测下来 18.x 以上比较稳16.x 在某些规则解析上会报错。其次是包管理器npm、pnpm、yarn 都支持但如果你项目里用的是 pnpm 的 workspace 模式建议全局安装而不是项目内安装否则跨包扫描会有路径问题。检查命令很简单node -v npm -v如果 Node 版本低于 18建议先用 nvm 切一下。我一开始图省事用了系统自带的 Node 16结果跑扫描的时候一直提示某个语法解析失败折腾了半小时才发现是版本问题。3.2 安装命令与验证安装本身没什么难度npm install -g impeccable-cli装完之后跑一下版本号确认impeccable --version如果提示命令找不到大概率是全局 bin 目录没在 PATH 里。npm 的话可以用npm config get prefix看一下路径然后手动加进环境变量。这个问题在 macOS 上用 Homebrew 装的 Node 特别常见Windows 上反而少一些。注意如果你同时装了多个 Node 版本管理器全局安装的包可能只对当前版本生效。切换 Node 版本后记得重新装一遍或者用npx impeccable的方式调用。3.3 项目初始化配置装好之后在项目根目录跑impeccable init这个命令会生成一个impeccable.config.json文件里面是默认规则集。我建议第一次用的时候先不要改任何东西跑一遍默认规则看看报告长什么样心里有个底之后再按需调整。配置文件的核心结构大概是这样的{ spacing: { base: 4, scale: [0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64] }, typography: { scaleRatio: 1.25, baseSize: 16 }, color: { contrastMin: 4.5 }, ignore: [node_modules/**, dist/**] }spacing.scale那个数组就是允许的间距值单位是 base 的倍数。比如 base 是 4scale 里有 4那 16px 就是合法的20px 就会报警告。这个设计的好处是它不禁止你用任意值只是提醒你“这个值不在刻度上”你可以选择忽略或者调整。4. 用 CLI 扫描前端代码完整流程与参数详解4.1 基础扫描命令最基本的用法是直接扫描一个目录impeccable check ./src它会递归扫描目录下所有 CSS、SCSS、Less 以及内联样式输出一份报告。报告分三个级别error、warning、info。error 是明确违反硬性规则的比如颜色对比度低于标准warning 是偏离刻度但不算错的比如用了非标准间距info 是一些建议性的提示。我第一次跑的时候一个中等规模的项目输出了 200 多条 warning看着挺吓人但仔细一看大部分是间距不在刻度上。这种情况其实很正常因为很多项目的历史代码本来就没有严格的设计规范。我的建议是先把 error 清零warning 分批处理不要试图一次全改完。4.2 输出格式与过滤参数默认输出是给人看的彩色文本但如果你要集成到 CI 里可以用--format json输出结构化数据impeccable check ./src --format json report.json还有一个很实用的参数是--level可以只显示某个级别以上的问题impeccable check ./src --level error这样在 CI 里就可以只卡 errorwarning 作为参考不阻塞流程。我自己的做法是本地开发时看全量报告CI 里只卡 error这样既保证了底线质量又不会因为历史遗留的 warning 导致构建失败。4.3 针对特定文件类型的扫描如果你的项目里 CSS 和 JSX 混着写可以用--include和--exclude精确控制扫描范围impeccable check ./src --include **/*.css --exclude **/*.test.*这个在大型项目里特别有用因为全量扫描有时候会跑到测试文件或者第三方代码里去产生大量噪音。我一般会把node_modules、dist、coverage这些目录排除掉配置文件里的ignore字段就是干这个的。4.4 自动修复功能的使用与边界impeccable 提供了一个--fix参数可以自动修复一部分问题主要是间距和字号这类数值型的偏差impeccable check ./src --fix但我要泼一盆冷水自动修复要慎用。它会把所有非标准间距强行拉到最近的刻度值上这在大多数情况下是对的但如果你的设计稿里有一些刻意为之的“破格”间距它也会一并改掉。我第一次用的时候没注意把一个 hero 区域的 20px 间距改成了 16px视觉上明显变紧了。提示用--fix之前一定要先提交代码或者做好备份改完之后用git diff仔细过一遍。我现在的习惯是先用--fix --dry-run看一下会改哪些地方确认没问题再实际执行。5. 浏览器扩展的安装与实时校验5.1 扩展的获取与加载浏览器扩展这块impeccable 目前主要通过开发者模式加载。你需要在项目的 releases 页面下载扩展包然后在浏览器的扩展管理页面打开“开发者模式”选择“加载已解压的扩展程序”指向解压后的目录。这个过程听起来简单但有几个坑。首先是浏览器版本Chrome 和 Edge 的 Manifest V3 支持情况不一样我实测 Chrome 110 以上没问题Edge 稍微旧一点的版本可能会提示权限错误。其次是如果你用的是公司电脑扩展安装可能被策略限制这种情况只能走 CLI 路线。5.2 侧边栏报告解读装好之后打开任意页面点击扩展图标侧边栏会显示当前页面的设计规范报告。它会按元素分类把有问题的元素高亮出来。我特别喜欢它的一个功能是鼠标悬停在报告条目上页面上对应的元素会闪烁一下这样你就能快速定位到问题所在。报告里最常见的几类问题问题类型典型表现严重程度间距偏离margin/padding 不在刻度上warning对比度不足文字与背景色对比度低于 4.5:1error字号跳跃相邻层级字号比超过设定比例warning颜色数量超标页面用色超过设定上限info这个表格是我根据实际使用总结的不是官方文档里的原文。对比度不足是唯一一个我建议必须修的 error 级别问题因为它直接关系到可访问性。5.3 与 CLI 结果的差异说明有一点需要提前知道浏览器扩展和 CLI 的检查结果不完全一致。CLI 是静态分析源码扩展是分析渲染后的 DOM。这意味着扩展能发现一些源码里看不出来的问题比如继承导致的最终计算值偏离但它也可能漏掉一些源码里有但当前页面没渲染到的样式。我的经验是扩展适合发现“视觉上真实存在的问题”CLI 适合发现“代码层面潜在的问题”。两者互补不要指望其中一个能完全替代另一个。6. 与 AI coding agents 的集成实践6.1 在 Codex CLI 工作流中嵌入检查这是我用得最多的场景。我的工作流大概是用 Codex CLI 生成一个组件然后立刻跑 impeccable 检查把报告喂回给 agent 让它修正。这个循环跑两三轮出来的代码质量比单纯让 agent 生成要好很多。具体操作上我会在 agent 的 prompt 里加一句“生成完成后运行impeccable check file --format json根据报告修正所有 error 级别的问题。”这样 agent 就有了一个明确的验收标准而不是靠它自己猜什么叫“好看”。实测下来加了这一步之后生成的前端代码在间距一致性上的问题减少了大概七成。当然这只是一个粗略的体感不是严格的统计数据。6.2 把规则文件作为 agent 的上下文另一个我觉得很实用的做法是把impeccable.config.json直接作为 agent 的上下文文件。很多 CLI 工具支持读取项目根目录的配置文件作为系统提示的一部分这样 agent 在生成代码的时候就知道你的间距刻度是什么、字号比例是多少从源头上减少违规。这个做法比事后检查更高效因为它把问题扼杀在生成阶段。但前提是你的配置文件要写得足够清晰agent 能看懂。我建议在配置里加一些注释性的字段虽然 JSON 本身不支持注释但你可以用一个_comment字段来写说明。6.3 多 agent 协作时的规则同步如果你团队里多个人都在用 AI agent 写前端规则同步就很重要。我的做法是把impeccable.config.json提交到版本控制然后在项目的 README 里写清楚所有 AI 生成的前端代码必须通过 impeccable 检查才能提交。这样做的额外好处是它给团队提供了一个客观的讨论基础。以前大家争论“这个间距是不是太大了”现在直接看报告在刻度上就是合规的不在就是需要说明理由的。把主观审美问题转化成客观规则问题沟通成本降低了很多。7. 常见问题与排查技巧实录7.1 扫描结果为空或明显不全这是我最开始遇到的一个问题跑impeccable check ./src什么都没输出。排查下来有几个常见原因。一是文件扩展名不在默认扫描范围内比如你用的是.vue单文件组件默认可能不识别需要手动加--include **/*.vue。二是配置文件里的ignore字段写得太宽泛把整个 src 都排除了。三是路径问题如果你在 monorepo 的子包里跑相对路径可能不对。排查顺序建议先确认文件确实存在且扩展名正确再检查配置文件最后用--verbose参数看详细日志。7.2 对比度检查的误报处理对比度检查偶尔会误报典型情况是文字颜色是通过 CSS 变量动态设置的静态分析拿不到最终值就会按默认值来判断。这种情况可以在配置里针对特定选择器加白名单{ color: { ignoreSelectors: [.dynamic-theme-text] } }但我要提醒一句白名单是最后的手段不要一遇到误报就加白名单。先确认是不是真的误报有时候确实是代码写得有问题只是你之前没意识到。7.3 自动修复后样式错乱的回滚前面提到过--fix的风险这里补充一下回滚的方法。如果你没提前提交代码可以用git stash先存一下当前修改然后git checkout .恢复到上次提交的状态。如果已经提交了就用git revert回滚那一次提交。我现在的标准流程是--fix之前必git commit改完之后git diff逐行审查确认没问题再git commit一次。这样即使出问题也能精确回滚到修复前的状态。7.4 扩展不生效的排查清单浏览器扩展不生效的情况我也遇到过几次整理了一个排查清单确认扩展已启用且当前页面不是浏览器内置页面如 chrome:// 开头的页面扩展无法注入检查是否有其他扩展冲突尤其是其他设计类或调试类扩展刷新页面后重试有些页面是 SPA路由切换后扩展需要重新注入查看扩展的后台日志通常在扩展管理页面的“服务工作进程”里能看到报错信息大部分情况下刷新页面或者重启浏览器就能解决。如果还不行卸载重装扩展通常能搞定。8. 我实际用下来的一些体会impeccable 这个项目最让我认可的一点是它没有试图做一个“万能设计 AI”而是老老实实做了一层约束。这个定位看起来很窄但实际用起来覆盖面很广因为几乎所有 AI 生成前端代码的场景都需要这层约束。CLI 和扩展两条路径我都深度用过如果只能选一个我会选 CLI因为它更容易集成到自动化流程里。但扩展在调试阶段的直观性是 CLI 替代不了的尤其是当你面对一个“说不出哪里不对但就是不好看”的页面时扩展能帮你快速定位到具体问题。规则配置这块我的建议是不要一开始就大改默认值。先用默认规则跑一两周积累一些实际报告之后再按需调整。我见过有人一上来就把间距刻度改成自己习惯的值结果发现和团队其他人的习惯冲突反而制造了新的混乱。最后分享一个我最近在用的技巧把 impeccable 的检查报告作为 code review 的一部分。每次 PR 里附上一份检查报告reviewer 就能快速判断这次改动有没有引入设计规范上的退化。这个做法比单纯靠人眼看要可靠得多尤其是当改动涉及大量样式调整的时候。