1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个词是在一个前端开发者的讨论串里。有人甩出一句这个布局写得不够 impeccable底下立刻有人接话你装个 impeccable 试试。我当时的第一反应是这又是什么新出的代码检查工具后来花了一个周末把它摸了一遍才发现它跟传统的 lint 工具完全不是一回事。impeccable 这个词本身是无可挑剔的、完美的意思。放在前端设计和 AI coding agents 的语境里它其实指向一个很具体的痛点AI 写出来的前端代码功能上能跑但视觉上往往差一口气。间距不对、对齐歪了、颜色对比度不够、响应式断点乱设、组件层级混乱——这些问题 lint 工具查不出来单元测试也测不到但人眼一看就觉得不对劲。impeccable 就是冲着这个不对劲来的。它的核心定位可以概括成一句话一个面向 AI coding agents 的前端设计质量层。它通过 CLI 和浏览器扩展两种形态介入开发流程在 AI 生成代码之后、人工 review 之前自动做一轮设计品味层面的检查和修正。适合谁用我梳理了三类人一是重度依赖 AI coding agents比如各种 CLI 形态的编码助手写前端的开发者二是带团队、需要统一前端视觉规范的技术负责人三是自己写组件库、想让产出更耐看的独立开发者。这里要特别说明一点impeccable 不是替代你的审美而是把那些有明确对错的设计规则自动化掉。比如按钮内边距不能小于 8px正文行高不能低于 1.4相邻元素间距必须落在 4px 的倍数网格上——这些是有客观标准的交给工具而这个渐变好不好看这种主观判断还是得人来。理解这个边界后面用起来才不会拧巴。2. 核心设计思路拆解为什么是 CLI 浏览器扩展这套组合2.1 为什么不做成纯插件也不做成纯命令行我一开始也疑惑既然要检查前端设计为什么不干脆做成一个 VS Code 插件或者一个纯 CLI 工具用下来才明白CLI 和浏览器扩展解决的是两个不同阶段的问题缺一不可。CLI 的战场在代码生成阶段。当 AI coding agent 吐出一堆 JSX 或 Vue 模板之后你可以在提交前跑一遍impeccable check它扫描的是源码层面的设计 token 使用情况——有没有硬编码颜色值、间距是不是走了设计系统的变量、组件的 props 命名是否符合规范。这一步是静态的快能进 CI。浏览器扩展的战场在运行时渲染阶段。有些设计问题只有页面真正渲染出来才暴露元素实际计算出来的间距、字体加载后的行高、不同视口下的布局塌陷。扩展直接读取 DOM 的 computed style能抓到 CLI 抓不到的东西。而且它能在你浏览页面时实时给出标注像给页面叠了一层设计网格。提示这两个形态不是二选一而是流水线的上下游。CLI 管写的时候扩展管看的时候。只装一个覆盖度大概只有六成。2.2 它和 ESLint、Stylelint 的本质区别很多人第一反应是这不就是 Stylelint 吗。我实测对比过差别很大。Stylelint 检查的是语法和写法规范比如不要用!important颜色要用十六进制小写。impeccable 检查的是设计意图和视觉结果比如这个卡片的阴影层级和它所在的容器不匹配这个标题的字号和它的语义层级对不上。打个比方Stylelint 像语文老师改错别字impeccable 像美术老师看你的构图。前者管对错后者管协调。两者不冲突可以同时跑。2.3 面向 AI coding agents 的设计考量这是我觉得最值得说的一点。impeccable 的输出格式是为 AI 消费而优化的。它报错不是给你看一段人类友好的长文本而是给出一段结构化的、可以直接喂回给 AI agent 的修正指令。比如它不会只说间距有问题而是输出类似将.card的padding从13px调整为16px以对齐 4px 网格这样的可执行 diff 建议。这个设计背后的逻辑是AI coding agents 的迭代速度极快如果每次都要人肉把设计问题翻译成修改指令那效率瓶颈就卡在人这里了。让工具直接产出 AI 能懂的指令形成AI 写 → impeccable 查 → AI 改的闭环才是它真正的价值所在。这也是为什么它会在 AI coding agents 这个圈子里先火起来。3. 核心细节解析几个必须搞懂的关键概念3.1 设计网格Design Grid与 4px 基准impeccable 默认以4px 为基准网格。为什么是 4 而不是 8 或 5这是有讲究的。4px 在主流屏幕密度下1x、2x、3x都能整除不会产生半像素模糊同时 4 的倍数足够细能表达出 8px 网格表达不了的微调比如 12px 这种介于 8 和 16 之间的间距。8px 网格虽然更整齐但遇到紧凑型 UI 就捉襟见肘了。它的检查逻辑是所有margin、padding、gap、width、height的最终计算值都应该落在 4 的倍数上。注意是最终计算值不是源码里写的值。比如你写padding: 0.8rem在 16px 根字号下等于 12.8px这就违规了因为 12.8 不是 4 的倍数。这个细节很多人会踩坑。3.2 对比度阈值与可访问性impeccable 内置了 WCAG 对比度检查但它的阈值设置比标准更严格一点。正文文本要求对比度至少4.5:1这是 WCAG AA 标准大号文本要求3:1。但它额外加了一条交互元素按钮、链接在 hover 和 focus 状态下的对比度也要达标。这一条很多设计系统都忽略了导致键盘用户 focus 到按钮时根本看不清焦点在哪。3.3 组件层级与 z-index 管理z-index 混乱是前端的老大难。impeccable 的做法是强制你使用语义化的层级 token而不是裸数字。它会在配置里定义一套层级比如// impeccable.config.js export default { zIndex: { base: 0, dropdown: 1000, sticky: 1020, modal: 1050, toast: 1080, } }然后检查代码里有没有出现z-index: 9999这种裸值。有的话直接报错并建议你替换成对应的 token。这个约束一开始会让人觉得烦但用久了会发现它逼着你想清楚这个元素到底该在哪一层而不是遇到遮挡就无脑加数字。3.4 响应式断点的收敛AI 生成的前端代码有个通病断点乱设。一会儿768px一会儿800px一会儿820px。impeccable 要求断点必须来自预设集合默认是640 / 768 / 1024 / 1280 / 1536对应主流框架的 sm/md/lg/xl/2xl。超出这个集合的断点会被标记出来让你确认是不是真的需要。4. 实操过程从安装到跑通第一条检查4.1 环境准备与 CLI 安装impeccable 的 CLI 是基于 Node 的所以先确认你的 Node 版本。我实测下来Node 18 以上比较稳16 也能跑但偶尔有依赖警告。# 全局安装 CLI npm install -g impeccable-cli # 或者作为项目依赖推荐方便锁版本 npm install -D impeccable-cli # 验证安装 impeccable --version装完之后在项目根目录初始化配置impeccable init这个命令会生成一个impeccable.config.js里面包含网格基准、断点集合、z-index 层级、颜色 token 等默认配置。我的建议是先把默认配置跑一遍看看报多少错再决定改哪些规则不要一上来就大改配置否则你根本不知道工具默认的品味是什么样。4.2 配置文件的关键参数初始化出来的配置大概长这样我挑几个关键项说明export default { grid: { base: 4, // 基准网格单位 px tolerance: 0, // 容差0 表示严格对齐 }, breakpoints: [640, 768, 1024, 1280, 1536], contrast: { normalText: 4.5, largeText: 3, interactive: 4.5, // 交互元素额外要求 }, zIndex: { // 语义化层级定义 }, ignore: [ **/node_modules/**, **/*.test.*, ], }tolerance这个参数值得单独说。默认是 0意味着 12.8px 这种值会直接报错。如果你接手的是一个历史项目一上来就 0 容差会报出几千个错根本没法推进。这时候可以先把tolerance设成1允许 1px 的偏差等存量问题清理得差不多了再收紧到 0。这是渐进式接入的关键技巧。4.3 跑第一遍检查# 检查整个项目 impeccable check # 只检查指定目录 impeccable check src/components # 输出为 JSON方便喂给 AI agent impeccable check --format json # 自动修复能修的问题 impeccable check --fix第一次跑impeccable check的时候我建议先不加--fix纯看报告。报告会按文件分组每个问题标注行号、当前值、建议值、以及违反的规则名。看一遍报告你就能大致摸清自己项目在设计规范上的欠债集中在哪几类。4.4 浏览器扩展的安装与使用浏览器扩展的安装方式取决于你用的浏览器一般是在扩展商店搜索 impeccable或者加载开发者模式下的解压包。装好之后打开任意页面点扩展图标它会做几件事在页面上叠加一层网格参考线让你直观看到元素有没有对齐高亮所有间距违规的元素用不同颜色区分差 1-2px和差 4px 以上侧边栏列出当前页面的对比度问题和层级问题提供一个复制修正指令按钮一键把问题转成 AI 能读的格式注意扩展读取的是运行时 DOM所以对于动态渲染的内容比如懒加载的列表需要等页面完全加载后再点检查否则会漏报。4.5 把检查接进 AI coding agent 的工作流这是重头戏。假设你用某个 CLI 形态的编码助手写前端理想的工作流是这样的# 1. AI agent 生成代码后先跑检查 impeccable check --format json .impeccable-report.json # 2. 把报告喂回给 agent让它按建议修正 # 具体命令取决于你用的 agent核心是把 json 报告作为上下文传入 # 3. 修正后再跑一遍确认清零 impeccable check我实测下来这个闭环能把AI 写完 → 人工发现设计问题 → 人工描述问题 → AI 改这个四步流程压缩成AI 写 → 工具查 → AI 改三步中间省掉的人工描述环节恰恰是最费时、最容易描述不清的环节。5. 常见问题与排查技巧实录5.1 报错太多怎么办分级处理策略新手最容易卡在第一步一跑检查几千个错误直接劝退。我的处理策略是分三级级别问题类型处理方式P0对比度不达标、z-index 裸值立即修影响可访问性和可维护性P1间距不在网格上批量--fix人工抽查P2断点不收敛、命名不规范排期修不阻塞当前迭代先把 P0 清零P1 用自动修复过一遍P2 记进技术债清单。这样一轮下来项目能立刻体面不少又不会因为追求完美而卡住进度。5.2 自动修复改坏了布局怎么办--fix不是万能的。它把padding: 13px改成16px的时候可能会让某个本来就紧凑的卡片撑破容器。我的经验是跑--fix之前先提交一次代码跑完之后用git diff逐个文件看改动重点看那些改完之后尺寸变化超过 4px的地方。发现改坏的单独 revert 那个文件手动调。5.3 和现有设计系统冲突如果你团队已经有一套成熟的设计系统impeccable 的默认规则可能和它打架。比如你们的设计系统基准是 5px 网格而 impeccable 默认 4px。这时候不要硬改代码去迁就工具而是改配置去迁就设计系统grid: { base: 5, tolerance: 0, }工具是服务于规范的不是反过来。这一点想清楚接入过程会顺很多。5.4 浏览器扩展不生效的排查扩展不生效按这个顺序查确认扩展已启用且当前页面不是浏览器内置页面内置页面不允许扩展注入打开开发者工具 Console看有没有扩展报错检查页面是否有严格的 CSP 策略阻止了扩展注入脚本如果是 iframe 内的内容需要确认扩展是否有跨 frame 权限我遇到最多的是第 3 种尤其是企业内部系统CSP 卡得很死。这种情况只能退而求其次用 CLI 做静态检查。5.5 性能开销CLI 检查大项目几千个文件大概需要几十秒可以接受。浏览器扩展在复杂页面上叠加网格会有轻微卡顿建议只在需要检查时开启平时关掉不要一直挂着。6. 一些实操心得与踩坑记录先说一个我踩过的坑不要试图一次性把所有规则都开到最严。我一开始把tolerance设成 0断点集合只留 5 个z-index 全部 token 化结果一个中型项目报出 4000 多个问题团队直接对这个工具产生了抵触情绪。后来改成渐进式两周清一批反而推得动。第二个心得是关于 AI agent 的配合。impeccable 输出的 JSON 报告字段设计得挺合理但不同 AI agent 对上下文的消化能力不一样。有的 agent 能一次吃下整个报告并批量修正有的只能一次处理一个文件。我的做法是先用impeccable check --format json拿到全量报告然后按文件切分逐个喂给 agent。虽然多几步但修正质量明显更稳。第三个是团队协作层面。impeccable 的配置文件应该进版本库作为团队共识的一部分。谁改了网格基准或者断点集合都要走 code review。否则今天你改成 4px明天他改成 8px工具就失去意义了。最后分享一个提效小技巧把impeccable check挂到 git 的 pre-commit hook 里但只对暂存区的文件跑不要全量跑。全量跑会让每次提交都等半天体验极差。只查改动文件既快又能防止新代码引入新的设计债。# .husky/pre-commit 示例 npx impeccable check --staged这个--staged参数是我用得最顺的一个它只检查git add过的文件提交前几秒钟就能出结果完全不打断心流。用久了你会发现设计规范的落地靠的不是一次性的运动式清理而是这种嵌进日常流程的、几乎无感的持续约束。
