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 清零，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 浏览器扩展不生效的排查

扩展不生效，按这个顺序查：

1. 确认扩展已启用，且当前页面不是浏览器内置页面（内置页面不允许扩展注入）
2. 打开开发者工具 Console，看有没有扩展报错
3. 检查页面是否有严格的 CSP 策略，阻止了扩展注入脚本
4. 如果是 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过的文件，提交前几秒钟就能出结果，完全不打断心流。用久了你会发现，设计规范的落地，靠的不是一次性的运动式清理，而是这种嵌进日常流程的、几乎无感的持续约束。