1. 从"impeccable"这个词说起：一个前端设计工具链的野心
第一次看到"impeccable"这个词被用作项目名，我的反应是——这名字起得够狂。"无可挑剔"，一个做前端设计辅助的工具敢叫这个名字，要么是团队极度自信，要么是他们对"设计还原度"这件事有近乎偏执的追求。实际用下来一段时间之后，我倾向于后者。
这个项目本质上是一套围绕AI coding agents构建的前端设计质量保障工具链，核心形态是一个CLI工具配合一个browser extension。它要解决的问题非常具体：当你用 AI 编程助手（比如各种 code agent）生成前端代码时，产出的界面往往"能跑但难看"——间距不统一、颜色体系混乱、响应式断点随意、组件复用率低。impeccable 的思路是在 AI 生成代码之后、人工 review 之前，插入一层自动化的设计规范校验与修正环节。
适合谁来用？我梳理了三类人：第一类是重度依赖 AI 生成前端代码的独立开发者，你让 agent 帮你写页面，但不想每次都手动调 CSS；第二类是小团队里没有专职设计师的全栈工程师，需要一套"设计兜底"机制；第三类是对 UI 一致性有强迫症的工程师，想把设计规范变成可执行的检查项而不是文档里的摆设。如果你属于以上任何一类，这套东西值得花时间研究。
需要提前说明的是，impeccable 目前还处于快速迭代阶段，CLI 的命令和配置项在不同版本间可能有变化。我下面写的内容基于我实际使用的版本，你在复现时如果遇到命令不识别的情况，先跑一下impeccable --version确认版本，再去对照官方 changelog。这是踩过坑之后的经验，后面会详细讲。
2. 整体设计思路拆解：为什么是"CLI + 浏览器扩展"这个组合
2.1 核心问题定位：AI 生成代码的"设计债务"
要理解 impeccable 为什么这么设计，得先理解它瞄准的痛点。AI coding agent 生成前端代码时，有一个结构性的缺陷：它优化的是"功能正确性"和"语法合法性"，而不是"视觉一致性"。你让 agent 写一个登录页，它能给你一个能用的表单，但输入框的 padding 可能是 12px，按钮的 padding 可能是 14px，两者视觉上就差那么一点，说不上哪里不对但就是不舒服。这就是所谓的设计债务——功能没 bug，但视觉上处处是"差不多"。
传统解法有两种：一是靠设计师出规范文档，工程师对照实现，问题是文档和代码是两套东西，容易脱节；二是靠 Storybook 之类的组件库约束，问题是 AI 生成的代码往往不走组件库，直接写原生标签加 Tailwind 类名。impeccable 选了第三条路：把设计规范变成可执行的检查规则，直接在代码层面跑。
2.2 为什么 CLI 和浏览器扩展要分开
这是我觉得这个项目设计上最值得说的一点。很多人会问：既然要检查前端设计，为什么不做成一个纯浏览器扩展，直接在页面上标注问题？或者为什么不做成一个纯 CLI，扫描代码文件就行？
我的理解是，这两种形态解决的是不同阶段的问题，缺一不可。
CLI 负责的是静态检查。它在你的代码仓库里跑，扫描 JSX/TSX/Vue 模板/CSS 文件，检查的是"代码里写了什么"。比如它能发现你在三个不同组件里分别写了margin-top: 13px、margin-top: 14px、margin-top: 15px，然后告诉你"这三个值应该统一到设计系统的 spacing scale 上"。这种检查在代码提交前就能跑，可以集成到 CI 里，属于"防患于未然"。
浏览器扩展负责的是运行时检查。它注入到实际渲染的页面里，检查的是"浏览器实际画出了什么"。有些问题静态代码看不出来，比如两个元素的实际间距因为 margin collapse 变成了 8px 而不是你写的 16px，或者某个断点下布局塌了。扩展能拿到 computed style 和实际布局信息，这是 CLI 做不到的。
提示：不要指望只装一个就能覆盖所有场景。我一开始只用了 CLI，结果上线后发现移动端断点下一堆问题，因为静态检查没法模拟真实渲染。后来补上扩展才把这类问题兜住。
2.3 与 AI coding agents 的协作定位
impeccable 把自己定位成 AI coding agents 的"下游质检员"，这个定位很聪明。它不跟 agent 抢活干，不试图去改进 agent 的生成质量，而是承认"agent 生成的东西就是会有设计瑕疵"，然后在后面加一道工序。
实际工作流是这样的：你用 codex cli 或者类似的 agent 工具生成一批前端代码，跑完之后执行impeccable check，它会输出一份问题清单，每条问题附带位置、当前值、建议值。你可以选择手动改，也可以让 agent 根据这份清单再跑一轮修正。我实测下来，让 agent 根据 impeccable 的输出做二次修正，比让它一次性生成"完美代码"的成功率高得多——因为修正任务比生成任务的目标更明确。
这种"生成-检查-修正"的循环，比"一次生成到位"的期望更符合当前 AI 能力的实际水平。这也是我愿意花时间研究这个工具的核心原因。
3. 核心细节解析：设计规范引擎到底在检查什么
3.1 间距与尺寸的归一化检查
impeccable 最基础也最实用的功能是间距检查。它的原理不复杂：维护一套设计 token（间距刻度、字号刻度、圆角刻度等），然后扫描代码里所有硬编码的数值，标记出不在刻度上的值。
举个例子，假设你的设计系统定义间距刻度是 4 的倍数：4、8、12、16、24、32。代码里出现padding: 14px，它就会标记出来，建议改成 12px 或 16px。听起来简单，但实际项目里这种"差 2px"的地方能有几十上百处，人工根本查不过来。
这里有个细节值得说：impeccable 对不同的 CSS 属性用不同的刻度。间距类属性（margin、padding、gap）用 spacing scale，字号用 type scale，圆角用 radius scale。它不会拿间距刻度去卡字号，这点比一些粗糙的 lint 工具做得好。
配置刻度的地方在项目根目录的impeccable.config.js（或.impeccable.json），大致长这样：
module.exports = { scales: { spacing: [0, 4, 8, 12, 16, 24, 32, 48, 64], fontSize: [12, 14, 16, 18, 20, 24, 30, 36], radius: [0, 2, 4, 8, 12, 16, 9999], }, tolerance: 0, // 允许的偏差像素，0 表示严格匹配 };tolerance这个参数很关键。设成 0 最严格，但实际项目里有时候确实需要 1px 的微调（比如边框对齐），设成 1 会宽松一些。我的建议是初期设 1，等团队养成习惯后再收紧到 0。
3.2 颜色体系的一致性校验
颜色检查比间距复杂，因为颜色有多种表示法：hex、rgb、hsl、命名颜色、CSS 变量。impeccable 会把这些统一解析成标准格式再比对。
它的检查逻辑分两层。第一层是调色板外颜色检测：你定义了品牌色板，代码里出现了不在色板上的颜色，标记出来。第二层是近似色合并建议：代码里出现了#3B82F6和#3C83F7这种肉眼几乎分不出的颜色，它会建议合并成一个。
第二层功能我觉得特别有价值，因为 AI 生成代码时经常"随手"写一个接近但不完全一样的颜色。你让 agent 生成三个按钮，它可能给你三个略有差异的蓝色，视觉上就是"脏"。impeccable 能把这些揪出来。
配置色板：
module.exports = { palette: { primary: ['#2563EB', '#3B82F6', '#60A5FA'], neutral: ['#111827', '#374151', '#6B7280', '#D1D5DB', '#F9FAFB'], danger: ['#DC2626', '#EF4444'], }, colorDistanceThreshold: 3, // 色差小于此值视为近似色，建议合并 };colorDistanceThreshold用的是 CIEDE2000 色差公式（这是色彩学里比较符合人眼感知的算法），值越小越严格。设成 3 意味着色差小于 3 的颜色会被认为是"应该合并的"。这个值我调过几次，2 太严（会把有意设计的深浅色也合并），5 太松（漏掉明显该合并的），3 是比较舒服的平衡点。
3.3 响应式断点的规范检查
响应式这块，impeccable 检查的是断点值是否统一。很多项目里会出现@media (max-width: 768px)、@media (max-width: 767px)、@media (max-width: 770px)混用的情况，这就是典型的断点混乱。
它要求你在配置里定义断点集合，然后检查所有 media query 是否用了这些值：
module.exports = { breakpoints: { sm: 640, md: 768, lg: 1024, xl: 1280, }, };检查时它会把max-width: 767px这种"差一像素"的写法也标记出来，因为 767 和 768 在语义上应该是一回事（通常 767 是为了避开边界值，但更好的做法是统一用 768 配合max-width: 767.98px或者直接用min-width）。
注意：断点检查有个坑，如果你用了 Tailwind 的默认断点，它和 impeccable 默认配置可能对不上。Tailwind 的 sm 是 640，md 是 768，但有些版本有细微差异。用之前先确认两边配置一致，否则会报一堆假阳性。
3.4 组件复用与重复代码识别
这一块是 impeccable 比较进阶的功能。它会分析你的组件结构，识别出"结构高度相似但被重复实现"的组件。比如你在五个页面里各写了一个卡片组件，结构都是"图片+标题+描述+按钮"，它会建议抽取成公共组件。
实现原理是基于 AST（抽象语法树）的结构相似度比对。它不看具体的类名和文案，只看 DOM 结构和样式模式。相似度超过阈值（默认 0.85）就会提示。
这个功能我持保留态度。好处是确实能发现一些无意识的重复，坏处是假阳性不少——有些组件看着像但业务逻辑完全不同，强行抽取反而增加耦合。我的用法是把它当"提示"而不是"命令"，看到提示后自己判断要不要抽。
4. 实操过程：从安装到跑通第一条检查
4.1 环境准备与 CLI 安装
impeccable 的 CLI 通过 npm 分发，安装很直接：
npm install -g impeccable-cli # 或者项目内安装 npm install --save-dev impeccable-cli装完之后验证：
impeccable --version impeccable --help如果你看到命令找不到，大概率是全局 bin 路径没配好。用npm config get prefix看一下全局路径，确认它在 PATH 里。这个问题在 Windows 上尤其常见，我帮同事排查过好几次。
初始化配置文件：
impeccable init这个命令会在项目根目录生成impeccable.config.js，里面是默认配置。不要直接用默认配置，默认的刻度是通用值，跟你的项目设计系统大概率对不上。先花十分钟把 spacing、fontSize、palette、breakpoints 改成你项目实际用的值，这一步偷懒后面全是假阳性。
4.2 跑第一次检查与读懂输出
配置好之后跑：
impeccable check ./src输出大概是这样：
src/components/Button.tsx 12:5 warning spacing padding: 14px not in scale [4,8,12,16,24] 18:5 warning color #3C83F7 is close to #3B82F6 (distance: 1.2) src/pages/Login.tsx 34:3 warning breakpoint max-width: 767px should be 768px 56:7 warning spacing margin-top: 13px not in scale第一次跑，问题数量通常会吓你一跳。我第一个项目跑出来 200 多条，当时心想"这代码有这么烂吗"。冷静下来看，大部分是同一类问题重复出现，实际需要改的模式就那么几种。
建议的处理顺序：先按规则类型分组看（spacing 一类、color 一类），找出出现频率最高的模式，批量改。不要一条一条改，效率太低。
4.3 浏览器扩展的安装与使用
浏览器扩展的安装方式取决于你用的浏览器。以 Chromium 系为例，在扩展管理页面开启开发者模式，加载 impeccable 提供的扩展目录（或者从官方渠道安装）。
装好之后，打开你的开发环境页面，点击扩展图标，它会扫描当前页面的渲染结果，在页面上叠加标注：
- 间距问题用橙色框标出
- 颜色问题用紫色框标出
- 断点问题在控制台输出
扩展有个很实用的功能是"实时模式"，你改代码热更新后，标注会自动刷新。这样你可以边改边看，不用反复手动触发扫描。
提示：扩展在扫描大型页面时可能有点卡，尤其是组件数量超过几百个的页面。我的做法是分模块扫描，先扫当前在开发的模块，不要一上来就扫整个应用。
4.4 集成到开发工作流
单次跑检查意义有限，关键是集成到日常流程。我实践下来有三个集成点比较有价值：
提交前钩子：用 husky 在 pre-commit 阶段跑impeccable check --staged，只检查本次改动的文件。这样不会因为历史遗留问题阻塞提交，又能防止新问题进来。
# .husky/pre-commit npx impeccable check --staged --fail-on error--fail-on error表示只有 error 级别的问题才阻塞提交，warning 级别只提示。初期建议这么设，等团队适应了再收紧。
CI 检查：在 CI 流水线里加一步全量检查，输出报告但不阻塞（或者只阻塞 error）。这样能追踪整体设计债务的变化趋势。
与 agent 协作：这是我觉得最有意思的用法。把 impeccable 的输出喂给 AI agent，让它根据清单修正：
impeccable check ./src --format json > issues.json # 然后把 issues.json 的内容作为上下文给 agent，让它逐条修正实测下来，agent 根据结构化的问题清单做修正，比让它自由发挥重新生成，效果好很多。因为修正任务的目标明确，agent 不容易跑偏。
5. 常见问题与排查技巧实录
5.1 假阳性太多怎么办
这是新手最常遇到的问题。跑一次检查几百条警告，仔细一看大部分是误报。原因通常有三个：
第一，配置的刻度跟项目实际用的对不上。比如你项目用的是 8 的倍数间距，但配置里写的是 4 的倍数，那所有 8 的倍数都会被判为"不在刻度上"（因为 8 在 4 的倍数里，这个例子其实不会报，但原理你懂）。解决办法是老老实实把配置改成项目实际值。
第二，第三方组件库的代码被扫描了。node_modules 里的代码不该被检查，但有时候路径配置不对会扫进去。在配置里加ignore: ['**/node_modules/**', '**/dist/**']。
第三，某些属性不该用刻度卡。比如line-height用无单位数值（1.5）是合理的，不该被间距刻度检查。impeccable 支持按属性排除：
module.exports = { ignoreProperties: ['line-height', 'z-index', 'opacity'], };5.2 与现有 lint 工具冲突
如果你项目里已经有 stylelint 或 eslint-plugin-tailwindcss，可能会和 impeccable 的检查重叠。重叠本身不是问题，问题是两边报的问题不一致，让人无所适从。
我的处理原则是：样式规范类的问题交给 impeccable，语法类的问题交给 eslint/stylelint。具体做法是在 eslint/stylelint 配置里关掉那些和 impeccable 重叠的规则（比如 stylelint 的declaration-property-value-allowed-list如果用来卡间距，就关掉），避免双重报告。
5.3 大型项目的性能问题
项目大了之后，全量扫描会变慢。我测过一个中型项目（约 500 个组件文件），全量扫描要 40 多秒。这个时间在 CI 里能接受，但本地开发时反复跑就很烦。
优化手段有几个：用--staged只扫改动文件；用--cache开启缓存，没改的文件跳过；把扫描范围缩小到当前开发的目录。我本地开发时基本只用--staged，全量扫描留给 CI。
5.4 常见问题速查表
| 问题现象 | 可能原因 | 解决办法 |
|---|---|---|
| 命令找不到 | 全局 bin 路径未配置 | 检查npm config get prefix并加入 PATH |
| 假阳性大量出现 | 刻度配置与项目不符 | 按项目实际设计系统修改 config |
| 扫描速度慢 | 全量扫描无缓存 | 用--staged或--cache |
| 扩展不生效 | 页面未刷新或权限不足 | 刷新页面，检查扩展权限设置 |
| 与 agent 协作无效 | 输出格式不匹配 | 用--format json输出结构化数据 |
| 断点检查误报 | 与 Tailwind 默认断点冲突 | 对齐两边配置 |
5.5 几个我踩过的坑
第一个坑：不要一次性把所有 warning 都改成 error。我一开始图省事，配置里把所有规则都设成 error 级别，结果提交被阻塞了几十次，团队怨声载道。正确做法是分级推进，先 warning 观察一段时间，确认规则合理后再逐步升级。
第二个坑：设计 token 要跟设计稿同步更新。有次设计改了品牌色，我更新了代码里的色板但忘了更新 impeccable 配置，结果新颜色全被判为"调色板外颜色"。配置文件和设计系统要建立同步机制，最好是从同一个源头生成。
第三个坑：扩展和 CLI 的配置是分开的。CLI 读项目根目录的配置文件，扩展读的是它自己存储的设置。两边要手动保持一致，否则会出现"CLI 说没问题但扩展报错"的诡异情况。我现在养成的习惯是改配置时两边都改一遍。
6. 与 AI coding agents 的深度协作实践
6.1 把 impeccable 变成 agent 的"设计记忆"
AI agent 有个特点：它在单次会话里能保持上下文，但跨会话就"失忆"了。你这次告诉它"间距用 4 的倍数"，下次新开会话它又忘了。impeccable 的配置某种程度上可以充当 agent 的"设计记忆"——把配置内容作为系统提示的一部分喂给 agent，它就能在生成时遵守这些约束。
具体做法是在 agent 的项目级指令文件（比如AGENTS.md或类似的约定文件）里引用 impeccable 配置：
## 设计规范 本项目使用 impeccable 管理设计规范，配置见 impeccable.config.js。 生成前端代码时请遵守以下约束： - 间距使用 spacing scale 中的值 - 颜色使用 palette 中定义的颜色 - 断点使用 breakpoints 中定义的值这样 agent 在生成代码时就有了明确的约束，从源头减少问题。实测下来，加了这段指令之后，impeccable 检查出的问题数量能减少一半左右。
6.2 生成-检查-修正的闭环
完整的闭环是这样的：
- 用 agent 生成初版代码
- 跑
impeccable check得到问题清单 - 把清单喂回给 agent，让它修正
- 再跑一次检查，确认问题解决
- 重复 3-4 直到问题清零或达到可接受水平
这个循环通常跑两轮就能收敛。第一轮解决大部分明显问题，第二轮处理边角情况。第三轮基本就没什么可改的了。
有个技巧：给 agent 的修正指令要具体。不要说"修复所有设计问题"，而要说"根据以下清单逐条修正，每条给出修改前后的对比"。具体的指令能让 agent 的输出更可控。
6.3 不同 agent 工具的适配差异
我用过几种不同的 agent 工具配合 impeccable，体验有差异。codex cli 这类命令行工具的好处是容易脚本化，可以把 impeccable 的输出直接管道传给它。图形界面的 agent 工具则需要手动复制粘贴问题清单，效率低一些。
不管用哪种工具，核心思路是一样的：让检查结果结构化，让修正任务明确化。impeccable 的--format json输出就是为这个场景设计的，善用它。
7. 我对这套工具链的真实看法
用了一段时间之后，我的整体评价是：impeccable 解决的是一个真实存在但常被忽视的问题。AI 生成前端代码的普及，让"设计债务"的积累速度比以前快了很多，因为生成代码的成本太低了，低到人们懒得去管质量。impeccable 的价值在于它把"设计质量"这件事变得可量化、可自动化、可集成。
但它不是银弹。它检查的是"规范符合度"，不是"设计好坏"。一个完全符合 spacing scale 和色板的界面，依然可能很丑。规范是底线，不是上限。把 impeccable 当成"防止设计债务失控"的工具，而不是"提升设计水平"的工具，这个定位比较准确。
另外，配置成本不能低估。第一次接入一个存量项目，把配置调到一个假阳性可接受的水平，通常要花半天到一天。这个投入是值得的，但要有心理准备。
最后分享一个我自己的用法：我把 impeccable 的检查结果按周统计，画成趋势图。看着设计债务的数字一周周下降，比任何"代码质量提升"的抽象说法都有说服力。数据化的东西，团队里谁都看得懂，推进起来阻力也小。这个习惯我保持了几个月，现在项目里的设计一致性问题基本控制在一个很低的水平，新来的同事甚至感觉不到"规范"的存在——因为它已经变成了默认状态。这大概就是一个设计规范工具能做到的最好结果了。
