1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI coding agent 帮你改一个前端页面它改完之后你打开浏览器一看——间距不对、颜色偏了、响应式在某个断点崩了、按钮的 hover 状态没了。你回头去看 diff代码逻辑没错但视觉上就是差那么一口气。impeccable 这个词本身的意思是无可挑剔的、完美的放在前端设计语境里它指向的其实是一个非常具体的痛点让 AI coding agents 产出的前端界面从能跑变成能看从能看变成挑不出毛病。这不是一个泛泛的 AI 工具而是一个专门针对前端设计质量做约束和校验的 CLI 工具同时配套了 browser extension 来做实时的视觉反馈。我先把话说在前面这个项目不是那种一键生成整个网站的魔法棒。它的定位更像是给 AI coding agent 戴上一副设计审查眼镜——agent 写完代码impeccable 负责用一套可量化的设计规则去检查、去纠正、去迭代直到界面达到一个可接受的视觉标准。这个思路我觉得比单纯堆 prompt 要靠谱得多因为设计这件事靠嘴说好看一点是没用的得有具体的规则和度量。适合谁来用三类人最直接受益一是用 AI agent 写前端但自己设计功底一般的开发者二是想给团队建立前端设计质量基线的前端负责人三是做 AI coding 工具链、想把设计校验环节自动化的工作流搭建者。如果你只是偶尔手写几个页面那这个工具对你来说可能有点重但如果你已经在日常工作中大量依赖 AI agent 产出前端代码那 impeccable 解决的正是你最头疼的那个最后一公里问题。2. 核心设计思路拆解为什么是 CLI Browser Extension 的组合2.1 为什么不做成纯 Web 服务我一开始也疑惑为什么 impeccable 选择 CLI 作为主要入口而不是做一个网页版。后来想明白了AI coding agents 的工作流本身就是命令行驱动的。你用 codex cli、zcode cli 这类工具的时候整个交互都在终端里完成agent 读写文件、执行命令、跑测试全在本地文件系统上。如果 impeccable 是个 Web 服务那 agent 每次要校验设计就得把代码或截图上传到远端这个链路既慢又别扭还涉及代码外传的问题。CLI 的另一个好处是可组合性。它可以被 agent 直接调用也可以被写进 package.json 的 scripts 里还可以挂在 CI 流程里做设计回归检查。这种一个命令解决一件事的设计才是真正能嵌进现有工作流的方式。我实测下来把 impeccable 挂到 pre-commit hook 里做基础检查比事后人工 review 效率高太多。2.2 Browser Extension 补的是哪块短板CLI 能检查代码层面的东西——比如颜色变量是否用了设计 token、间距是否落在 4px 网格上、有没有硬编码的魔法数字。但 CLI 看不到渲染后的真实效果元素实际占多大、在某个视口下有没有溢出、对比度在真实背景上够不够、动画有没有卡顿。这就是 browser extension 存在的理由。它把代码静态分析和渲染后视觉分析这两条线接上了。extension 在浏览器里跑能拿到真实的 computed style、能截图、能测量元素的实际几何信息然后把这些数据回传给 CLI 或者 agent。这个组合的逻辑是CLI 管规则和流程extension 管真实渲染数据的采集。提示这个分工很重要。很多人误以为 extension 是给人类用户看的可视化面板其实它的核心价值是给 agent 提供眼睛让 agent 能感知到自己写的代码在浏览器里长什么样。2.3 和 AI coding agents 的协作模式impeccable 和 agent 的协作我理解成一种生成-校验-修正的闭环。agent 负责生成和修改代码impeccable 负责给出结构化的反馈agent 再根据反馈修正。关键在于反馈必须是结构化的、可操作的而不是这里不好看这种模糊评价。举个具体的例子agent 写了一个卡片组件padding 用了 13px。impeccable 的检查会输出类似padding: 13px 不在 4px 网格上建议改为 12px 或 16px这样的结构化信息。agent 拿到这条信息就能精确地改。如果反馈是间距看起来不协调agent 大概率会瞎改一通。这个区别决定了整个闭环能不能真正跑起来。3. 核心细节解析impeccable 到底检查哪些维度3.1 间距与网格系统间距是前端设计里最容易被 AI 搞砸的地方。人类设计师脑子里有网格概念AI 没有它经常写出 7px、13px、23px 这种数字。impeccable 的第一类检查就是间距是否落在统一的网格系统上。常见的网格基准是 4px 或 8px。为什么是这两个数因为绝大多数屏幕像素密度下4px 的倍数能保证元素在不同设备上对齐清晰不会出现半像素模糊。8px 网格更粗适合大块布局4px 网格更细适合组件内部微调。impeccable 一般会允许你配置基准值然后检查所有 margin、padding、gap 是否符合。我踩过的一个坑是有些设计系统里图标尺寸和文字行高不一定要严格落在网格上比如 20px 的图标配 24px 行高。如果检查规则太死板会误报一堆。所以配置的时候要留白名单机制把图标、字体行高这类特殊项排除掉。3.2 颜色与对比度颜色检查分两层。第一层是是否使用了设计 token也就是有没有硬编码#3b82f6这种色值而不是引用var(--color-primary)。硬编码色值是设计系统腐化的开始impeccable 会重点标记。第二层是对比度是否达标。这个有明确的标准正文文字和背景的对比度至少要 4.5:1大号文字可以放宽到 3:1。impeccable 会计算实际渲染后的对比度而不是只看代码里的色值——因为背景可能是渐变、可能是图片、可能是半透明叠加只有渲染后才能算准。# 典型的对比度检查输出示例 [WARN] Contrast ratio 3.2:1 below threshold 4.5:1 Element: .card-title Foreground: #6b7280 Background: #f9fafb Suggestion: darken foreground to #4b5563 (ratio 4.6:1)这种输出对 agent 特别友好因为它直接给了可执行的修改建议。3.3 响应式断点完整性AI agent 写响应式最容易犯的错是只写了一个断点。比如只处理了移动端和桌面端中间平板尺寸直接崩。impeccable 会检查在预设的几个视口宽度下布局是否都正常——有没有横向溢出、有没有元素重叠、有没有文字被截断。我一般会配置四个检查视口375px手机、768px平板竖屏、1024px平板横屏/小笔记本、1440px桌面。这四个点覆盖了绝大多数真实使用场景。检查的时候extension 会在每个视口下截图并测量CLI 汇总结果。3.4 交互状态覆盖按钮、链接、输入框这些交互元素至少有五种状态默认、hover、focus、active、disabled。AI agent 经常只写默认态hover 和 focus 全靠浏览器默认样式这在设计上是不合格的。impeccable 会检查每个交互元素是否显式定义了这些状态。focus 状态尤其重要它关系到键盘可访问性。很多 AI 生成的代码会把 outline 去掉却不给替代方案这是明确的可访问性缺陷。impeccable 会把这类问题标为高优先级。检查维度检查方式常见问题优先级间距网格静态分析 渲染测量魔法数字、不对齐中颜色 token静态分析硬编码色值中对比度渲染后计算文字看不清高响应式多视口渲染溢出、重叠高交互状态静态 渲染缺 hover/focus高4. 实操过程从安装到跑通第一个检查4.1 环境准备与 CLI 安装impeccable 的 CLI 安装方式我按常见 Node 生态工具的习惯来推演。它大概率是通过 npm 或类似的包管理器分发。安装前确认你的 Node 版本一般这类工具要求 Node 18 以上因为要用到较新的 ESM 和 fetch API。# 全局安装便于在任意项目目录调用 npm install -g impeccable-cli # 或者作为项目开发依赖 npm install --save-dev impeccable-cli # 验证安装 impeccable --version如果你用的是 codex cli 或 zcode cli 这类 agent 工具建议把 impeccable 装成项目本地依赖这样 agent 在项目里执行命令时能直接调用不用依赖全局环境。全局安装适合你个人频繁跨项目使用但团队协作时本地依赖更可控。注意安装过程中如果遇到权限报错不要用 sudo 硬装优先检查 npm 的全局目录权限配置。用 sudo 装全局包是很多奇怪问题的根源。4.2 初始化配置文件装完之后第一步是初始化配置。impeccable 需要一个配置文件来知道你的设计系统基准——网格大小、颜色 token 来源、检查视口、忽略规则等。impeccable init这个命令会在项目根目录生成一个配置文件类似impeccable.config.json。我建议你打开它逐项确认尤其是这几个字段{ grid: { base: 4, whitelist: [icon-size, line-height] }, colors: { tokenSource: ./src/styles/tokens.css, contrastThreshold: 4.5 }, viewports: [375, 768, 1024, 1440], ignore: [**/node_modules/**, **/*.test.*] }tokenSource指向你的设计 token 文件impeccable 会解析这个文件来建立合法色值清单。whitelist是前面提到的例外机制把不该被网格规则约束的属性放进去。4.3 跑第一次检查配置好之后直接对目标文件或目录跑检查# 检查单个组件 impeccable check ./src/components/Card.tsx # 检查整个目录 impeccable check ./src/components # 输出 JSON 格式便于 agent 解析 impeccable check ./src/components --format json第一次跑大概率会报一堆问题这很正常。我的建议是先别急着全改先看问题的分布。如果 80% 的问题都集中在间距和颜色 token 上说明你的项目缺一套统一的设计约束这时候应该先补设计系统而不是逐个改样式。4.4 Browser Extension 的接入Extension 的接入分两步。第一步是在浏览器里安装扩展第二步是让它和 CLI 建立连接。连接方式通常是 extension 启动一个本地服务CLI 通过这个服务请求渲染数据。# 启动本地渲染服务 impeccable serve --port 3456 # 然后在浏览器里打开你的开发页面 # extension 会自动连接到这个服务这里有个实操细节extension 需要访问你本地开发的页面所以你的 dev server 得先跑起来。我一般开三个终端窗口——一个跑 dev server一个跑 impeccable serve一个跑 agent。三个窗口各司其职互不干扰。提示如果你在浏览器里看到 extension 提示enter the code from your two-factor authentication app or browser extension这类验证信息那通常是扩展的权限确认流程按提示在扩展面板里完成配对即可。这一步是为了确保只有你授权的 CLI 实例能读取浏览器数据。4.5 和 Agent 的联动配置让 agent 自动调用 impeccable需要在 agent 的配置里加一条规则。以常见的 agent 配置为例你可以在项目根目录放一个说明文件告诉 agent 在修改前端代码后必须跑 impeccable 检查。# AGENT.md 片段 ## 前端修改规则 1. 修改任何 .tsx/.vue/.svelte 文件后必须执行 impeccable check 修改的文件 --format json 2. 如果输出包含 severity: high 的问题必须修复后重新检查 3. 连续三次检查仍有 high 问题停止并报告这个连续三次的限制很重要防止 agent 陷入无限修正循环。我见过 agent 因为一个对比度问题反复改颜色改到第 N 次还是差 0.1最后把整个配色方案搞乱了。设个上限超了就人工介入。5. 常见问题与排查技巧实录5.1 检查结果全是误报怎么办这是新手最容易遇到的问题。跑一次检查几百条警告仔细一看大部分是误报。原因通常是配置没贴合项目实际。排查思路先看误报集中在哪个维度。如果是间距误报检查grid.whitelist是不是漏了图标、行高这类特殊项。如果是对比度误报检查tokenSource是不是没正确解析你的 token 文件导致 impeccable 把合法色值当成了硬编码。我的一般做法是第一次跑完把误报的规则逐条加进 ignore 或 whitelist跑个三五轮误报率就能降到可接受范围。这个过程别嫌烦一次配置好后面长期受益。5.2 Extension 连不上本地服务常见原因有三个端口被占用、dev server 没跑、跨域限制。按顺序排查# 检查端口占用 lsof -i :3456 # 换个端口重试 impeccable serve --port 3457如果是跨域问题impeccable serve 一般会有 CORS 配置项把你的 dev server 地址加进允许列表。我遇到过 dev server 跑在localhost:3000但 extension 只允许127.0.0.1的情况把地址统一一下就好了。5.3 Agent 不按规则调用检查Agent 不执行检查通常是两个原因一是规则文件没被 agent 读到二是规则描述太模糊。确认你的规则文件放在 agent 会扫描的位置一般是项目根目录并且用明确的祈使句写规则别用建议可以考虑这种软性措辞。还有一个隐蔽的坑有些 agent 在修改文件后会忘记跑检查因为它把注意力都放在代码生成上了。解决办法是在规则里把检查步骤写成强制前置条件——未通过检查的修改视为未完成。这个措辞对 agent 的约束力明显更强。5.4 检查通过但视觉上还是不对这种情况说明你的检查规则覆盖不全。impeccable 能查的是可量化的东西但设计里有些东西是量化的规则查不出来的比如视觉层级、留白节奏、信息密度。这时候需要人工补位。我的经验是把 impeccable 当成底线守卫它保证你的界面不会出现硬伤。但好看这件事还是得靠人来判断。工具能帮你省掉 70% 的机械检查工作剩下 30% 的审美判断暂时还没有工具能替代。问题现象可能原因排查动作大量误报配置未贴合项目检查 whitelist 和 tokenSourceExtension 连不上端口/跨域/dev server换端口、查 CORS、确认 dev serverAgent 不执行检查规则未读到或措辞软确认规则位置、改强制措辞检查通过但不好看规则覆盖不全人工补位审美判断5.5 性能问题大项目检查太慢项目大了之后全量检查会变慢。解决办法是增量检查——只检查改动的文件。impeccable 一般支持传入文件列表你可以结合 git diff 来生成这个列表。# 只检查本次改动的文件 git diff --name-only HEAD | grep -E \.(tsx|vue|svelte)$ | xargs impeccable check这个命令我挂在 pre-commit hook 里每次提交只检查改动的文件速度快很多。全量检查放在 CI 里每天跑一次就够了。6. 我个人的使用体会与几个实用建议用了一段时间 impeccable我最大的感受是它把设计质量这件事从主观讨论变成了客观检查。以前团队里讨论这个间距是不是太大了能争论半小时现在直接跑检查规则说 4px 网格超了就是超了没什么好争的。这种把主观问题客观化的能力对团队协作的价值远大于对个人开发者的价值。第二个体会是配置比使用更重要。impeccable 开箱即用的规则只能覆盖通用场景真正发挥价值的是你把它配置成贴合自己项目设计系统的样子。我花了大概两个下午调配置把误报率从 60% 降到 5% 以下后面用起来就非常顺了。这个前期投入绝对值得。第三个建议是别追求 100% 通过。设计检查的目的是减少硬伤不是追求完美分数。我给自己定的目标是 high 优先级问题必须清零medium 和 low 允许存在一定数量。如果为了清零所有 low 问题去改代码往往会引入新的问题得不偿失。最后分享一个小技巧把 impeccable 的检查结果和 agent 的修改记录关联起来做成一个简单的日志。这样你能看到 agent 在哪些维度上反复犯错然后针对性地在 prompt 或规则里加强约束。我用这个方法发现 agent 特别容易在 focus 状态上偷懒后来在规则里专门加了一条 focus 检查的强调问题就少多了。这个日志不用搞得很复杂一个 append 的文本文件就够用。