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 是 640md 是 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 的检查结果按周统计画成趋势图。看着设计债务的数字一周周下降比任何代码质量提升的抽象说法都有说服力。数据化的东西团队里谁都看得懂推进起来阻力也小。这个习惯我保持了几个月现在项目里的设计一致性问题基本控制在一个很低的水平新来的同事甚至感觉不到规范的存在——因为它已经变成了默认状态。这大概就是一个设计规范工具能做到的最好结果了。