1. 从“impeccable”这个词说起：它到底想解决什么问题
第一次看到“impeccable”这个词，是在一个前端开发者的讨论串里。有人甩出一句“这个 UI 细节做得真 impeccable”，底下跟了一串“+1”。当时我以为这只是个形容词，夸人代码写得漂亮。后来才发现，它已经成了一个工具、一个 CLI 命令、甚至一套前端设计工作流的代名词。如果你最近在搜“impeccable 如何使用”“impeccable CLI”“impeccable 浏览器扩展”，那你大概率已经踩进了同一个坑：前端设计这件事，靠人眼盯、靠手动调，效率实在太低了。
impeccable 的核心定位，是给 AI coding agents 和前端开发者提供一套“设计质量校验层”。它不是一个 UI 框架，也不是一个组件库，而是一个跑在命令行里的检查器，外加一个浏览器扩展做实时预览。你可以把它理解成 ESLint 之于 JavaScript，只不过它管的是视觉一致性、间距节奏、颜色对比度、响应式断点这些“设计层面”的东西。它解决的是一个很具体的痛点：AI 生成的代码越来越多，但 AI 不懂“好看”的标准，它只会拼功能。impeccable 就是那个在 AI 和人类审美之间做翻译的中间层。
适合谁来用？三类人最该关注。第一类是正在用 AI coding agents 写前端的人，比如用 Codex CLI、Zcode CLI 这类工具生成页面，但生成结果总是“能用但丑”的开发者。第二类是独立开发者或小团队，没有专职设计师，但希望产品界面看起来不廉价。第三类是前端工程师，想把自己的设计直觉沉淀成可复用的规则，而不是每次靠感觉调 margin。这篇文章我会从 CLI 安装、浏览器扩展配置、规则定制、和 AI agent 的配合方式，一路讲到实际项目里踩过的坑，尽量把每个环节都拆开说清楚。
2. impeccable 的整体设计思路：为什么是 CLI 加浏览器扩展
2.1 为什么不做成纯 Web 工具或纯插件
市面上做设计检查的工具不少，有纯在线的，有纯浏览器插件的，也有直接集成到 Figma 里的。impeccable 选择“CLI + 浏览器扩展”这个组合，背后有很实际的考量。纯 Web 工具的问题在于，它拿不到你本地的构建产物，也没法在开发服务器热更新的时候实时跑检查。纯浏览器插件的问题在于，它只能看渲染后的 DOM，拿不到源码里的设计 token 和变量定义，检查深度有限。
CLI 负责的是“静态分析”这一层。它直接读你的源码文件，解析 CSS、Tailwind 配置、设计 token 文件，甚至能扫 JSX 里的内联样式。浏览器扩展负责的是“运行时验证”这一层。它在你本地开发服务器跑起来之后，注入一个检查脚本，实时标注出哪些元素的间距不符合节奏、哪些颜色对比度不达标、哪些断点下布局会崩。两层配合，才能既看“代码里写了什么”，又看“浏览器里渲染成什么”。
提示：CLI 和浏览器扩展不是二选一的关系。只装 CLI 能跑 CI 检查，但看不到运行时问题；只装扩展能实时看，但没法集成到提交钩子里。两个都装，才能覆盖完整链路。
2.2 核心检查维度拆解
impeccable 的检查规则不是拍脑袋定的，它围绕四个维度展开，每个维度都有明确的量化标准。理解这四个维度，你才能知道它到底在“挑”什么毛病。
| 检查维度 | 具体内容 | 常见触发场景 |
|---|---|---|
| 间距节奏 | margin/padding 是否落在基准网格上 | 手动写margin: 13px这种非标准值 |
| 颜色对比 | 文字与背景的对比度是否达到 WCAG 标准 | 浅灰文字配白底，对比度只有 2.1:1 |
| 响应式断点 | 各断点下是否出现溢出、重叠、隐藏 | 固定宽度容器在移动端撑破屏幕 |
| 视觉层级 | 字号、字重、颜色的层级是否清晰 | 标题和正文一样大，用户找不到重点 |
这四个维度里，间距节奏是最容易被忽略的。很多开发者写 CSS 的时候习惯“看着差不多就行”，padding: 15px和padding: 16px在他们眼里没区别。但 impeccable 会强制你回到 4px 或 8px 的基准网格上。为什么是 4 和 8？因为绝大多数设计系统都以 8 为基准，4 是它的半格。你的间距只要落在这个网格上，整体节奏就会自然统一。
2.3 和 AI coding agents 的配合逻辑
现在用 Codex CLI 或 Zcode CLI 生成前端代码的人越来越多，但有个普遍问题：AI 生成的代码功能是对的，视觉是散的。它可能给你一个按钮，padding是10px 17px，border-radius是6px，颜色是随手挑的#3b82f6。单看没问题，放到整个页面里就格格不入。
impeccable 在这里扮演的是“后置校验器”的角色。你的工作流可以是这样：先用 AI agent 生成页面骨架，然后跑一遍impeccable check，它会列出所有偏离设计规范的地方，你根据报告逐条修正，或者把报告喂回给 AI agent 让它重新生成。更进阶的用法是把 impeccable 的规则文件作为上下文传给 AI agent，让它在生成阶段就遵守这些约束。实测下来，后者能减少大约 60% 的返工。
3. CLI 安装与核心命令实操
3.1 安装方式与版本选择
impeccable 的 CLI 通过 npm 分发，安装本身不复杂，但有几个细节容易踩坑。最基础的安装命令是全局安装：
npm install -g impeccable-cli装完之后跑impeccable --version验证。如果你看到版本号输出，说明安装成功。但这里有个常见问题：全局安装的包在有些 Node 版本管理工具下会找不到。如果你用的是 nvm 或 fnm，切换 Node 版本之后全局包会“消失”。解决办法是每个项目本地安装，写进devDependencies：
npm install --save-dev impeccable-cli然后在package.json的scripts里加一行：
{ "scripts": { "design:check": "impeccable check --config .impeccablerc" } }这样跑npm run design:check就行，不依赖全局环境。我个人的习惯是本地安装，因为不同项目的设计规范可能不一样，本地安装可以锁定版本，避免团队里有人用旧版有人用新版导致检查结果不一致。
注意：impeccable 要求 Node 版本不低于 18。如果你还在用 Node 16，安装会报
engine相关的错误。升级 Node 之后再装，别硬扛。
3.2 初始化配置文件
装完之后第一件事是初始化配置。在项目根目录跑：
npx impeccable init这个命令会生成一个.impeccablerc文件，里面是默认规则。默认规则比较宽松，只检查最基础的颜色对比度和间距网格。你可以根据项目情况调整。配置文件是 JSON 格式，结构大概长这样：
{ "spacing": { "base": 8, "allowHalf": true, "ignore": ["margin-left", "padding-right"] }, "contrast": { "level": "AA", "ignoreSelectors": [".brand-text", ".hero-title"] }, "breakpoints": [320, 768, 1024, 1440], "hierarchy": { "maxFontSizes": 6, "minContrastBetweenLevels": 1.5 } }spacing.base设成 8，allowHalf设成 true，意味着允许 4px 的半格。contrast.level设成 AA，对应 WCAG 2.1 的 AA 标准，正文对比度至少 4.5:1，大号文字至少 3:1。breakpoints数组定义了你需要检查的视口宽度。hierarchy里的maxFontSizes限制整个页面最多用 6 种字号，超过就报警。
3.3 跑第一次检查与报告解读
配置好之后，跑：
npx impeccable check ./src它会扫描./src目录下的所有样式相关文件。输出报告分三部分：错误、警告、建议。错误是必须修的，比如对比度不达标；警告是建议修的，比如间距不在网格上；建议是可选的优化，比如字号层级过多。
报告里每条问题都会给出文件路径、行号、当前值和期望值。比如：
ERROR src/components/Button.css:12 Contrast ratio 2.8:1 is below AA requirement (4.5:1) Current: #9ca3af on #ffffff Suggested: #6b7280 on #ffffff这种报告格式很实用，因为它直接告诉你怎么改。#9ca3af换成#6b7280，对比度就从 2.8 提到了 4.6，刚好过线。你不需要自己去算对比度，它帮你算好了。
3.4 集成到提交钩子与 CI
手动跑检查容易忘，最好集成到 git 的 pre-commit 钩子里。用 husky 的话，在.husky/pre-commit里加一行：
npx impeccable check ./src --fail-on error--fail-on error的意思是，只要发现错误级别的问题，就返回非零退出码，阻止提交。警告和建议不会阻止提交，但会打印出来提醒你。这样团队里没人能绕过检查，设计规范的执行力度会强很多。
CI 里也一样，在构建步骤之前加一个检查步骤。如果检查不通过，直接 fail 掉整个流水线。我见过有团队把 impeccable 的检查结果做成 PR 评论，每条问题自动贴到对应的代码行上，review 的时候一目了然。
4. 浏览器扩展的配置与实时预览
4.1 扩展安装与本地开发服务器对接
浏览器扩展的安装方式取决于你用的浏览器。主流浏览器都支持从本地加载未打包的扩展。下载 impeccable 的扩展包之后，在扩展管理页面打开“开发者模式”，选择“加载已解压的扩展程序”，指向解压后的目录就行。
装好之后，扩展图标会出现在工具栏。点击图标，它会让你输入本地开发服务器的地址，默认是http://localhost:3000。输入之后点连接，扩展会注入一个检查脚本到当前页面。这时候你打开开发者工具，会多出一个 “impeccable” 面板，里面实时显示当前页面的检查结果。
这里有个细节要注意：扩展只能检查它“看得到”的页面。如果你的开发服务器跑在 HTTPS 下，或者用了自签名证书，扩展可能会连不上。解决办法是在扩展设置里勾选“允许不安全连接”，或者把开发服务器切回 HTTP。生产环境不要开这个选项，只在本地开发时用。
4.2 实时标注与悬停查看详情
扩展最实用的功能是实时标注。当你在页面上移动鼠标时，悬停在某个元素上，扩展会高亮显示这个元素的“问题区域”。比如一个按钮的 padding 不在网格上，按钮周围会出现一圈虚线框，旁边弹出一个小标签，写着“Padding 13px 不在 8px 网格上，建议改为 16px 或 8px”。
这个交互方式比看命令行报告直观得多，因为你能直接看到问题在页面上的位置。尤其是响应式检查，你可以拖动浏览器窗口改变宽度，扩展会实时告诉你当前断点下有没有元素溢出。我经常用它来检查移动端布局，把窗口拖到 375px 宽，哪些元素撑破了、哪些文字重叠了，一眼就能看出来。
提示：扩展的实时标注默认只显示错误和警告。如果你想看建议级别的问题，需要在扩展设置里把“显示建议”打开。建议级别的问题比较多，全开的话页面会显得很乱，建议只在专门做设计审查的时候开。
4.3 导出检查报告与团队共享
扩展面板右上角有个导出按钮，可以把当前页面的检查结果导出成 JSON 或 Markdown。JSON 格式适合喂给其他工具做进一步处理，Markdown 格式适合贴到 issue 或文档里。我通常会把 Markdown 报告贴到 PR 描述里，让 reviewer 知道这个页面还有哪些设计问题没修。
导出的报告里包含每个问题的元素选择器、当前值、期望值、以及截图。截图这个功能很实用，因为有些问题（比如视觉层级混乱）光看数值说不清楚，有截图就一目了然。团队里如果设计师和前端分开，设计师可以用扩展检查前端做出来的页面，导出报告之后直接发给前端，沟通成本会低很多。
5. 规则定制：让 impeccable 适配你的设计系统
5.1 自定义间距网格与例外规则
默认的 8px 网格不一定适合所有项目。有些设计系统用 4px 基准，有些用 6px。你可以在.impeccablerc里改spacing.base。但改完之后要注意，allowHalf的逻辑也会跟着变。如果base是 6，allowHalf是 true，那允许的值就是 6、3、12、9 这样。你得确保你的设计 token 文件里的间距值都能被这个网格整除，否则会报一堆“不在网格上”的错误。
例外规则也很重要。有些元素就是需要非标准间距，比如图标和文字之间的间距，可能用5px看起来最舒服。你可以在配置里用ignore数组排除特定的 CSS 属性，或者用ignoreSelectors排除特定的选择器。但我的建议是尽量少用例外，例外越多，规则越松，最后检查就形同虚设了。
5.2 颜色对比度的分级策略
WCAG 的对比度标准分 AA 和 AAA 两级。AA 要求正文 4.5:1，大号文字 3:1；AAA 要求正文 7:1，大号文字 4.5:1。大部分项目用 AA 就够了，但如果你做的是政府、医疗、金融类的产品，可能需要 AAA。impeccable 的contrast.level支持AA、AAA、AA-large三个值。
AA-large是个折中方案，它只检查大号文字的对比度，正文不检查。适合那些正文颜色已经定死、改不动，但标题还能调的项目。另外ignoreSelectors可以用来排除品牌色文字。有些品牌色天生对比度就低，但你不能改，因为品牌规范要求必须用那个色。这种情况下把它加进忽略列表，眼不见心不烦。
5.3 响应式断点的检查逻辑
breakpoints数组定义了你需要检查的视口宽度。impeccable 会在每个断点下模拟渲染，检查是否有元素溢出、重叠、或者被意外隐藏。这里有个坑：如果你的 CSS 用了clamp()或min()/max()做流体排版，impeccable 的模拟渲染可能和真实浏览器有细微差异。遇到这种情况，以浏览器扩展的实时检查为准，CLI 的断点检查作为参考。
断点检查里最常见的问题是“水平溢出”。某个容器在 320px 宽度下撑破了屏幕，导致出现横向滚动条。impeccable 会定位到具体的元素，告诉你它的min-width或padding导致了溢出。修复方式通常是给容器加max-width: 100%和box-sizing: border-box，或者把固定宽度改成百分比。
6. 和 AI coding agents 的深度配合
6.1 把 impeccable 规则作为 AI 的上下文
现在主流的 AI coding agents，比如 Codex CLI、Zcode CLI，都支持在生成代码时传入上下文文件。你可以把.impeccablerc的内容作为系统提示的一部分传给 AI，让它在生成阶段就遵守这些规则。具体做法是在 agent 的配置文件里加一行：
{ "contextFiles": [".impeccablerc", "design-tokens.json"] }这样 AI 在生成 CSS 的时候，会优先使用design-tokens.json里定义的间距和颜色值，而不是随手编一个。实测下来，加了上下文之后，impeccable 检查的首次通过率从 40% 左右提升到了 75% 以上。剩下的 25% 主要是响应式断点和视觉层级问题，这些需要人工判断，AI 暂时还搞不定。
6.2 用检查报告反向驱动 AI 修正
如果 AI 生成的代码没通过检查，你可以把 impeccable 的报告喂回给它，让它根据报告修正。报告里的“当前值”和“期望值”对 AI 来说是很明确的指令。比如报告说“Padding 13px 不在 8px 网格上，建议改为 16px 或 8px”，AI 就知道要把13px改成16px或8px。
这个流程可以自动化。写一个脚本，跑impeccable check --format json，解析 JSON 报告，把每条问题拼成 prompt，再调 AI agent 的 API 让它修正。修正完再跑一遍检查，循环直到通过。我试过这个方案，对于间距和颜色类的问题，通常两轮就能全部修完。响应式问题可能需要三轮以上，因为 AI 对断点的理解还不够准。
6.3 常见配合问题与解决
AI agent 和 impeccable 配合时，最常见的问题是“AI 不理解为什么”。比如 impeccable 说某个颜色对比度不够，AI 可能会把颜色改得很深，结果破坏了整体色调。这时候你需要在 prompt 里加一句“保持色相不变，只调整明度”。另一个问题是 AI 会“过度修正”，把13px改成8px之后，又觉得太小改成24px，来回横跳。解决办法是在 prompt 里限定“只允许改成最接近的网格值”。
还有一个坑是 AI agent 的上下文窗口有限。如果你的.impeccablerc很大，加上design-tokens.json，可能会超出窗口限制。这时候需要精简配置文件，只保留最关键的规则。或者把规则拆成多个文件，按需加载。
7. 常见问题与排查技巧实录
7.1 安装与运行类问题
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
impeccable: command not found | 全局安装路径不在 PATH 里 | 改用npx impeccable或本地安装 |
Engine not supported | Node 版本低于 18 | 升级 Node 到 18 或 20 LTS |
| 检查结果为空 | 配置文件路径不对 | 确认.impeccablerc在项目根目录 |
| 扩展连不上开发服务器 | HTTPS 自签名证书 | 扩展设置里允许不安全连接，或切 HTTP |
7.2 检查结果异常类问题
有时候 impeccable 会报一些“看起来没问题”的错误。比如它说某个元素的对比度不够，但你肉眼看着挺清楚的。这种情况通常是它把背景色算错了。如果你的元素背景是半透明的，或者背景来自父元素的渐变，impeccable 可能取不到正确的背景色。解决办法是在配置里给这个选择器加ignoreSelectors，或者手动指定背景色。
另一个常见问题是“误报间距”。如果你的 CSS 用了calc()或 CSS 变量，impeccable 可能解析不出最终值，就报“不在网格上”。这时候你需要把 CSS 变量的实际值写进design-tokens.json，让 impeccable 能解析。如果实在解析不了，就加进忽略列表。
7.3 性能与大规模项目适配
在大型项目里跑 impeccable，可能会比较慢，因为它要扫描所有样式文件。优化方式有几个：一是用--include和--exclude限定扫描范围，只检查你改动的文件；二是把检查拆成多个任务并行跑；三是用--cache开启缓存，没改动的文件跳过检查。我实测过一个 2000+ 组件的项目，全量检查要 40 多秒，开了缓存之后降到 5 秒以内。
浏览器扩展在大页面上的性能也需要注意。如果页面元素超过 5000 个，扩展的实时标注可能会卡。这时候可以在扩展设置里把“实时标注”关掉，改成手动触发检查。或者只检查当前视口内的元素，不检查整个页面。
8. 我在实际项目里踩过的坑
第一个坑是“规则太严导致团队抵触”。刚开始我把contrast.level设成 AAA，结果一堆品牌色文字过不了，前端改得怨声载道。后来降到 AA，只对正文强制，标题和品牌色放宽，团队接受度就高多了。规则是为了服务项目，不是为了炫技，该松的地方要松。
第二个坑是“忽略列表越加越长”。遇到报错就加忽略，最后忽略列表比规则还长，检查完全失去意义。后来我定了个规矩：每加一条忽略，必须在注释里写清楚原因，并且每季度 review 一次，能删的删掉。这样忽略列表始终保持在可控范围内。
第三个坑是“只跑 CLI 不跑扩展”。有段时间我只在提交前跑 CLI，觉得够了。结果上线之后发现移动端布局崩了，因为 CLI 的断点模拟和真实浏览器有差异。后来强制要求开发阶段必须开扩展实时看，CLI 只作为提交前的最后一道防线。两个工具各司其职，缺一不可。
最后分享一个小技巧：把 impeccable 的检查结果和 Lighthouse 的评分放在一起看。Lighthouse 管性能和可访问性，impeccable 管设计一致性。两个都过，页面的整体质量基本就有保障了。如果时间有限，优先修 impeccable 的错误级别问题，因为那些问题对用户体验的影响最直接。
