1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI 帮你写一段前端代码它噼里啪啦吐出来一大坨结构看着像那么回事但真丢进项目里跑一遍间距不对、颜色不统一、响应式断点乱成一锅粥最后你还得手动收拾半天。这个项目瞄准的就是这个痛点——让 AI coding agents 产出的前端设计达到“挑不出毛病”的水准。impeccable 本质上是一套围绕AI coding agents的前端设计质量约束方案它通过CLI工具和browser extension两种形态介入你的开发流程把“设计规范”这件事从口头约定变成可执行、可校验的硬性规则。你不需要是资深设计师也不需要背一堆设计系统文档只要在流程里挂上它AI 生成的界面就会自动往“规范”上靠。它适合谁三类人最该关注一是用 AI 辅助写前端但总被设计细节折磨的独立开发者二是团队里负责统一 UI 规范、又不想天天写 review 意见的前端负责人三是刚入门、还没建立起设计直觉、需要工具帮忙兜底的新手。哪怕你只是偶尔用 AI 生成个落地页这套东西也能帮你省下大量返工时间。我下面会把它拆成几个层面来讲整体设计思路为什么这么定、核心机制怎么运作、CLI 和浏览器扩展两条实操路径怎么走、以及我在实际折腾过程中踩过的坑和总结出来的排查套路。内容偏实操能直接抄作业的地方我会写清楚。2. 整体设计思路拆解为什么是 CLI 加浏览器扩展的组合2.1 核心矛盾AI 生成快但设计质量不可控AI coding agents 的强项是“生成速度”弱项是“审美一致性”。你给它一个需求它能在几秒内给你一个能跑的页面但这个页面用的间距可能是 13px、17px、23px 这种随手拍的数字颜色可能是#3a7bd5和#3a7cd5这种肉眼几乎分不出的差异。单看一个组件没问题放到整个项目里就露馅了。传统解法是写一份设计规范文档然后靠人 review。问题是 AI 生成的速度远超人 review 的速度规范文档写得再细执行环节照样断链。impeccable 的思路很直接既然规范靠人执行不可靠那就把它变成工具链的一部分让 AI 在生成阶段就被约束在生成之后还能被自动校验。2.2 双形态设计CLI 管生成前扩展管生成后为什么是 CLI 加 browser extension 这个组合而不是只做一个这背后有个很实际的考量。CLI 的定位是生成前的约束。你在终端里跑命令它把设计 token、间距体系、颜色规范这些东西注入到 AI agent 的上下文里相当于在 AI 动手之前先给它立规矩。这个环节解决的是“从源头减少不合规产出”。Browser extension 的定位是生成后的校验。页面渲染出来之后扩展直接在浏览器里扫描 DOM把不符合规范的地方标出来——间距偏离了多少、颜色不在 token 列表里、字号跳级了等等。这个环节解决的是“漏网之鱼怎么抓”。两者配合的逻辑是CLI 降低问题发生率扩展兜住剩余问题。只做 CLIAI 偶尔不听话你没法及时发现只做扩展你每次都得等页面出来再改效率低。组合起来才是完整闭环。2.3 为什么不做成纯插件或纯 npm 包我一开始也想过为什么不直接做成一个 npm 包在构建时校验后来想明白了前端设计的很多问题只有在真实渲染环境里才暴露得出来。比如响应式断点你在代码里看media (max-width: 768px)觉得没问题但实际渲染出来可能因为容器查询、flex 换行等因素导致布局崩掉。这些必须靠浏览器扩展在真实 DOM 上跑才能抓到。而 CLI 存在的意义是跨 agent 通用。不管你用的是哪家的 AI coding agent只要它能读上下文CLI 就能把规范喂进去。这种“不绑定特定 agent”的设计让 impeccable 的适用范围一下子宽了很多。提示理解这个双形态设计是后面所有实操的基础。CLI 和扩展不是二选一是配合使用。3. 核心机制解析设计 token 是怎么被注入和校验的3.1 设计 token 体系一切的锚点impeccable 整套机制的地基是设计 token。你可以把它理解成一份“设计变量的字典”里面定义了间距阶梯、颜色板、字号层级、圆角半径、阴影层级这些基础元素。所有校验和约束都围绕这份字典展开。一份典型的设计 token 大概长这样这是基于常见实践的合理补全具体字段名以实际工具为准{ spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, color: { primary: #2563eb, primary-hover: #1d4ed8, text: #1f2937, text-muted: #6b7280, border: #e5e7eb }, fontSize: { sm: 14px, base: 16px, lg: 18px, xl: 24px }, radius: { sm: 4px, md: 8px, full: 9999px } }为什么用 token 而不是直接写死数值因为 token 提供了“可校验的基准”。AI 生成padding: 16px时工具能判断 16px 在不在 spacing 阶梯里生成#2563eb时能判断它是不是 primary 色。没有这份基准校验就无从谈起。3.2 注入机制让 AI agent 先读规范再动手CLI 的核心动作是注入。它把设计 token 转换成 AI agent 能理解的上下文格式在 agent 开始生成代码之前塞进去。具体怎么塞取决于你用的 agent 支持什么方式——有的支持 system prompt 注入有的支持读取项目根目录的配置文件有的支持通过 MCP 协议挂载。这里有个关键细节注入的内容不能太长。你把整份设计系统文档几千字塞进去AI 的注意力会被稀释反而记不住重点。impeccable 的做法是只注入“约束性信息”——也就是那些 AI 容易违反的规则比如“间距只能用 4/8/16/24/32 这几档”“颜色只能用 token 列表里的值”。至于设计理念、使用场景这些解释性内容不注入省 token 也省注意力。3.3 校验机制浏览器扩展怎么扫描 DOM浏览器扩展的校验逻辑我拆解下来大概是这么几步采集遍历页面 DOM提取每个元素的 computed style重点关注 margin、padding、color、font-size、border-radius 这几个属性。比对把采集到的值和设计 token 做匹配。匹配不是精确相等而是允许一定容差——比如 15px 可能被判定为接近 16px 这一档但会标记为“轻微偏离”。归类把问题分成几个等级——硬违规完全不在 token 里、软偏离接近但不等、疑似问题需要人工确认。呈现在页面上用高亮框标出问题元素侧边栏列出问题清单点击可以定位到具体元素。这套流程里容差阈值的设定很关键。设太严满屏都是警告你会麻木设太松真正的问题被漏掉。我实测下来间距容差设在 2px 以内比较合理颜色容差用色差公式算ΔE 小于 3 的算通过。3.4 为什么校验要分级而不是一刀切一刀切的校验结果就是“狼来了”。你打开页面200 个警告其中 180 个是无关紧要的你扫两眼就关掉了剩下 20 个真问题也被忽略。分级的意义在于让你能按优先级处理硬违规必须改软偏离看情况疑似问题人工判断。这个设计思路其实借鉴了代码 lint 工具的成熟经验——ESLint 也是分 error、warn、off 三级的。设计校验和代码校验在“分级降噪”这件事上逻辑是相通的。4. CLI 实操从安装到跑通第一条约束4.1 环境准备与安装CLI 工具的安装方式基于常见实践大概率是通过包管理器分发。我按最通用的路径来写你根据实际工具调整# 全局安装假设包名为 impeccable-cli实际以官方为准 npm install -g impeccable-cli # 或者用 npx 直接跑不装全局 npx impeccable-cli init安装完之后第一件事是init它会在你的项目根目录生成一份配置文件通常是impeccable.config.json或类似名字。这份文件里包含设计 token 的默认值和校验规则。注意init 生成的默认 token 是通用型的你几乎一定要根据自己的项目改。直接拿默认值去校验结果会很不准。4.2 配置设计 token从你的项目里提取真实值配置 token 最靠谱的方法不是凭空写而是从你现有项目里提取。如果你项目已经在用 Tailwind、CSS 变量或者设计系统库直接把这些值映射过来。我拿 Tailwind 举例。Tailwind 默认的 spacing scale 是 0、1、2、3、4、5、6、8、10、12、16、20、24……对应到 px 是 0、4、8、12、16、20、24、32、40、48、64、80、96。你把这套值填进 impeccable 的 spacing token 里校验基准就和项目实际用的对齐了。颜色同理。如果你的项目用 CSS 变量定义颜色把变量名和值都映射进去{ color: { primary: var(--color-primary), text: var(--color-text) } }这里有个细节token 里存的是变量名还是实际值我的建议是存实际值因为浏览器扩展在 DOM 上采集到的是 computed style也就是解析后的实际值。你存变量名比对时还得再解析一层容易出错。4.3 注入到 AI agent三种常见方式注入环节是 CLI 最核心的功能但具体怎么注入取决于你用的 agent。我梳理了三种常见方式方式一配置文件注入。如果你的 agent 支持读取项目根目录的特定配置文件比如.cursorrules、AGENTS.md这类CLI 可以把 token 转换成对应格式写进去。这种方式最省事一次配置长期生效。方式二命令包装注入。有些 agent 支持通过命令行参数传入上下文。CLI 可以包装一层在你调用 agent 时自动把 token 拼进去。这种方式灵活但每次调用都得走 CLI。方式三MCP 协议挂载。如果 agent 支持 MCPCLI 可以作为 MCP server 运行agent 在需要时主动查询设计规范。这种方式最优雅但对 agent 的能力有要求。我实测下来方式一最稳方式三最有前景但兼容性还在爬坡。你可以先从方式一开始。4.4 跑通第一条约束验证注入是否生效配置完之后怎么验证注入生效了我的做法是给 AI agent 一个明确的测试任务比如“生成一个带标题和按钮的卡片组件”然后看它产出的代码里间距和颜色是不是落在 token 范围内。如果 AI 生成的padding是 16px、color是 token 里的 primary 值说明注入生效了。如果它还是随手写 13px、17px说明注入没进去或者 agent 没读。这里有个排查技巧把注入的内容单独打印出来看一眼。CLI 通常会有--dry-run或--verbose之类的参数让你看到实际注入了什么。如果注入内容本身就不对那问题在配置如果注入内容对但 agent 不遵守那问题在 agent 的上下文处理能力。4.5 实操心得token 粒度怎么定token 粒度是个需要权衡的事。太粗比如 spacing 只有 sm/md/lg 三档AI 生成时选择太少容易卡壳太细比如 20 档间距AI 记不住校验也容易误判。我的经验是spacing 控制在 6 到 8 档color 控制在 10 到 15 个fontSize 控制在 5 到 6 档。这个粒度既能覆盖绝大多数场景又不会让 AI 和校验器过载。另外token 命名要语义化不要用spacing-1、spacing-2这种数字命名。用spacing-sm、spacing-md这种语义命名AI 更容易理解什么时候该用哪个。5. 浏览器扩展实操安装、扫描与问题定位5.1 安装与初始化浏览器扩展的安装路径基于常见实践应该是从浏览器的扩展商店获取或者以开发者模式加载本地包。我按开发者模式加载来讲因为这样你能看到源码、方便调试下载扩展的源码包解压到本地目录。打开浏览器的扩展管理页面开启“开发者模式”。点击“加载已解压的扩展程序”选择解压后的目录。扩展图标出现在工具栏说明加载成功。加载之后第一件事是配置 token。扩展通常会提供一个配置面板让你粘贴或导入 CLI 用的那份 token 文件。两边用同一份 token校验基准才一致。5.2 扫描流程从打开页面到看到问题清单配置好之后打开你要校验的页面点击扩展图标触发扫描。扫描过程大概几秒取决于页面复杂度。扫描完成后你会看到页面上有问题的元素被高亮框标出不同等级用不同颜色。侧边栏弹出问题清单按等级分组。点击清单里的某一项页面自动滚动到对应元素。我实测下来一个中等复杂度的页面大概 200 个 DOM 节点扫描时间在 2 到 3 秒。如果超过 5 秒还没出结果可能是页面里有大量动态内容或者 iframe需要检查扩展的权限配置。5.3 问题定位三类问题的处理优先级扫描出来的问题分三类处理优先级不一样问题等级判定标准处理建议硬违规值完全不在 token 列表里立即修复这是明确的规范偏离软偏离值接近某个 token 但不等评估后修复可能是容差设置问题疑似问题需要人工判断的边界情况逐个确认确认后调整规则硬违规没什么好说的直接改。软偏离要小心有时候是容差设太严导致的误报比如 15px 被判偏离 16px但 15px 可能是某个组件的合理值。疑似问题最费时间但也是最有价值的——它能帮你发现规则本身的盲区。5.4 实操心得扫描时机怎么选扫描时机很影响效率。我的经验是分三个节点扫开发中扫写完一个组件就扫一次问题当场发现当场改成本最低。提交前扫整个页面写完提交代码前扫一次抓跨组件的全局问题。回归时扫改完问题再扫一次确认没有引入新问题。不要等到项目快上线了才扫那时候问题堆积如山改起来牵一发动全身。注意扩展扫描的是渲染后的 DOM所以动态加载的内容比如异步请求回来的列表需要等加载完成后再扫否则会漏。6. 常见问题与排查技巧实录6.1 注入不生效AI 还是乱写间距这是最高频的问题。排查路径我整理成一张表排查点检查方法常见原因配置文件位置确认文件在 agent 读取的路径下路径不对agent 根本没读到配置格式用 CLI 的 dry-run 看注入内容格式不合法agent 解析失败token 内容检查 token 是否为空或格式错误配置写错注入了个空对象agent 能力换一个明确支持上下文注入的 agent 测试agent 本身不支持或支持不完整我踩过最坑的一次是配置文件路径写错了agent 读的是另一个目录下的旧配置导致我改了半天的 token 根本没生效。后来养成习惯每次改完配置先 dry-run 看一眼。6.2 扩展扫描报错页面加载不出来扩展扫描报错通常和权限有关。浏览器扩展要访问页面 DOM需要对应的权限声明。如果页面是 https 而扩展只声明了 http 权限就会报错。排查方法打开扩展的管理页面看权限列表里有没有覆盖你当前页面的协议和域名。没有的话在扩展的 manifest 里补上。另一个常见原因是页面里有跨域 iframe。扩展默认只能访问同源 iframe跨域的访问不到。这种情况要么放弃校验 iframe 内容要么在扩展配置里显式声明。6.3 误报太多容差怎么调误报多的根源通常是容差设置和 token 粒度不匹配。如果你的 token 间距只有 4/8/16/24/32 五档但项目里实际用了 12px、20px 这些中间值那 12px 和 20px 全会被判违规误报自然多。解法有两个一是把 token 粒度调细补上 12px、20px 这些档位二是把容差调宽让 12px 能被判定为接近 8px 或 16px。我倾向于前者因为补 token 是治本调容差是治标。6.4 性能问题大页面扫描卡顿页面 DOM 节点超过 1000 个时扫描可能明显卡顿。原因是扩展要遍历所有节点、计算 computed style、逐个比对计算量大。优化思路一是限制扫描范围只扫你关心的容器不扫整个 body二是分批扫描先扫首屏滚动后再扫后续内容三是降低扫描频率不要每次 DOM 变动都触发。我实测下来限制扫描范围效果最明显。把扫描根节点从document.body改成你的主内容容器节点数能降一个数量级扫描时间从几秒降到几百毫秒。6.5 独家避坑技巧汇总几个文档里不会写、但实际很管用的技巧token 版本化把 token 文件纳入 git 管理每次改动都有记录。设计规范变了你能追溯是什么时候变的、为什么变。校验规则分级配置不同项目对规范的严格程度不一样。新项目可以严一点老项目迁移可以松一点。把规则做成可配置的别写死。扫描结果导出扩展通常支持导出问题清单为 JSON 或 CSV。导出来之后可以喂给 AI agent让它批量修复比手动改快得多。和 CI 结合CLI 可以在 CI 里跑把校验结果作为构建门禁。硬违规超过阈值就 fail防止不合规代码进主干。7. 把 impeccable 用出效果的关键认知折腾了这么久我最大的体会是impeccable 这类工具的价值不在于“自动帮你改好”而在于“把隐性的设计规范变成显性的、可执行的约束”。它逼着你在项目早期就想清楚 spacing 阶梯怎么定、颜色板怎么划、字号层级怎么分。这些事想清楚了AI 生成的质量自然上去想不清楚工具再强也白搭。另一个认知是不要追求零违规。设计规范是为人服务的不是人为规范服务。偶尔为了视觉效果突破一下 token 范围是合理的。工具的作用是让你“有意识地突破”而不是“无意识地乱写”。看到违规提示时先问自己“这里是不是真的需要这个值”而不是条件反射地改成 token 里的值。最后分享一个我常用的工作流先用 CLI 把 token 注入 agent让 AI 生成初版然后用扩展扫一遍把硬违规批量导出把导出的清单喂回 agent让它按清单修复修复完再扫一遍确认。这个循环跑两三轮产出的前端代码基本就能达到“挑不出毛病”的水准了。整个过程里你花在手动调间距、对颜色上的时间能省下七八成剩下的精力可以放在真正需要人判断的交互逻辑和视觉创意上。
