★ FEATURED ARTICLE 1. 从impeccable这个热词说起它到底在解决什么问题第一次看到impeccable这个词被频繁提起是在一批前端开发者的讨论里。它不是一个框架也不是某个大厂开源的库而是一个定位非常明确的东西——给 AI coding agents 做前端设计约束的工具。关键词里同时出现了 CLI、browser extension、frontend design、AI coding agents这几个词拼在一起基本就勾勒出了它的轮廓一个既能跑在命令行里、又能以浏览器扩展形式存在的工具专门用来让 AI 写出来的前端代码挑不出毛病。为什么这个东西会火因为过去一年里用 AI 写前端的人越来越多但几乎所有人都遇到过同一个尴尬AI 生成的页面能跑但一眼就是AI 味。间距忽大忽小、颜色对比度不够、按钮圆角不统一、响应式断点乱设、无障碍属性缺失。你让它改它改一处坏一处。问题的根源不在于模型不够强而在于缺少一套可执行的、机器能读懂的设计规范让 AI 在生成代码时有据可依、生成之后有据可查。impeccable 要干的就是这件事。它把前端设计里那些老师傅凭手感的东西——视觉层级、间距节奏、色彩系统、可访问性——变成一套可以被 CLI 调用、被浏览器扩展实时检查的规则集。你可以把它理解成前端设计的 ESLint只不过它的目标用户一半是人一半是 AI agent。这篇文章适合三类人看一是正在用 AI 辅助写前端、但被AI 味折磨的开发者二是想给自己的项目建立设计规范、又不想手写一大堆文档的技术负责人三是对 CLI 工具链和浏览器扩展开发感兴趣、想了解这类工具怎么落地的人。下面我会从它解决的问题、核心机制、CLI 实操、浏览器扩展的用法、和 AI agent 的配合方式以及我自己踩过的坑一层层拆开讲。2. impeccable 的核心机制把设计品味翻译成机器规则2.1 为什么设计规范文档对 AI 基本无效很多人第一反应是我写一份设计规范 Markdown丢给 AI 不就行了我试过效果很差。原因有三个。第一文档是自然语言AI 会选择性忽略。你写了 50 条规范它生成代码时可能只记得住前 5 条剩下的在长上下文里被稀释掉了。第二文档没有强制力。AI 生成完代码没有任何机制去校验它是否遵守了规范全靠你自己肉眼 review。第三文档和代码之间没有映射关系。你写间距使用 8 的倍数但 AI 写了个margin: 13px你得自己去发现。impeccable 的思路完全不同。它不跟你讲道理它直接定义可检测的规则。比如所有间距必须是 4px 的倍数这条在 impeccable 里就是一个可以扫描 CSS/JSX 的检查项扫描到13px直接报错。规则是结构化的、可执行的、有明确判定标准的。这一点是它和普通设计文档最本质的区别。2.2 规则集的四个维度根据我实际使用和拆解下来的理解impeccable 的规则集大致覆盖四个维度这四个维度基本就是前端设计挑不出毛病的全部内涵维度检查内容典型规则举例空间系统间距、内边距、尺寸的一致性间距必须是基准单位的整数倍同类元素间距统一视觉系统颜色、字体、圆角、阴影颜色必须来自设计 token对比度达到 WCAG AA响应式断点、流式布局、溢出断点必须来自预设集合禁止固定宽度导致横向滚动可访问性语义标签、ARIA、键盘可达交互元素必须有可聚焦状态图片必须有 alt这四个维度不是拍脑袋分的而是对应了前端 review 时最常被挑出来的四类问题。你回想一下自己 code review 时说的那些话——这个间距不对这个颜色哪来的手机上会溢出这个按钮键盘点不到——基本都能归到这四类里。impeccable 做的事情就是把这些口头 review 变成自动化检查。2.3 CLI 和浏览器扩展为什么都要有这是很多人会疑惑的点既然有 CLI为什么还要做浏览器扩展反过来也是。答案在于使用时机不同。CLI 面向的是生成后和提交前。你在终端里跑一条命令它扫描你的源码输出一份问题清单。这个场景适合集成到 CI 里或者在你 commit 之前跑一遍。它的优势是能覆盖整个代码库能进流水线能作为质量门禁。浏览器扩展面向的是运行时和实时。你打开页面扩展直接在真实渲染的 DOM 上做检查能发现那些静态扫描发现不了的问题——比如某个元素实际计算出来的对比度不达标、某个交互在真实浏览器里键盘无法聚焦、某个布局在特定视口下溢出。静态分析看的是代码扩展看的是渲染结果两者互补。我个人的用法是写代码时开着扩展边写边看有没有红线提交前跑一遍 CLI确保没有遗漏。两个入口一套规则这是它设计上比较聪明的地方。3. CLI 上手实操从安装到跑通第一条检查3.1 安装与初始化CLI 工具的安装方式通常走包管理器。以常见的 Node 生态为例全局安装或者用 npx 直接跑都可以。我建议先不要全局装用 npx 试一下确认符合预期再决定要不要固化到项目里。# 方式一直接用 npx 试跑不污染全局环境 npx impeccable --version # 方式二装到项目 devDependencies团队统一版本 npm install -D impeccable装到项目里而不是全局是我强烈建议的做法。原因很简单规则集会随版本更新全局装的话你本地是新版、同事是旧版、CI 又是另一个版本检查结果对不上排查起来非常痛苦。锁在package.json里大家用同一个版本结果才可复现。初始化一般会生成一个配置文件类似.impeccablerc或写进package.json的某个字段。这个文件决定了用哪套规则、忽略哪些路径、哪些规则降级为警告。第一次初始化时我建议先全量跑一遍看看你的项目到底有多少问题别急着配忽略规则。很多人一上来就把一堆规则关掉结果工具等于白装。3.2 第一次全量扫描做好心理准备npx impeccable check ./src第一次跑输出大概率会让你头皮发麻。一个中等规模的前端项目几千条警告是常态。这时候千万别慌也别急着一条条改。正确的做法是先分类统计# 按规则类型统计问题数量找出重灾区 npx impeccable check ./src --format json report.json拿到 JSON 报告后按规则 ID 聚合一下你会发现问题高度集中——往往 80% 的问题来自 3 到 5 条规则。比如硬编码颜色值可能占了三分之一间距非基准倍数又占三分之一。先解决高频规则收益最大。这跟性能优化先找热点是一个道理。3.3 配置文件的几个关键字段配置文件里最值得关注的几个字段我逐个说下我的理解rules规则开关和等级。可以设成off、warn、error。我的建议是新项目直接全开error老项目先把高频规则设error其余设warn逐步收紧。ignore忽略路径。第三方库、生成代码、node_modules一定要排除否则报告会被噪音淹没。tokens设计 token 的来源。这是 impeccable 比较核心的配置——你得告诉它你的颜色、间距、字体是从哪来的。通常指向一个tokens.json或 CSS 变量文件。baseline基线机制。老项目可以生成一个基线文件把当前所有问题冻结之后只报新增问题。这个功能对存量项目非常友好不然你永远在还历史债。提示baseline机制要慎用。它能让你快速接入但也容易变成眼不见心不烦的借口。我的做法是给基线设一个过期时间比如三个月内必须把基线里的问题清掉否则 CI 直接失败。3.4 集成到 CI 和 pre-commitCLI 真正的价值在于自动化。两个集成点# pre-commit只检查暂存的文件快 npx impeccable check --staged # CI全量检查作为质量门禁 npx impeccable check ./src --max-warnings 0--staged只扫 git 暂存区的文件速度很快适合放在 pre-commit hook 里不打断开发节奏。CI 里则跑全量--max-warnings 0表示任何警告都导致失败。这里有个经验CI 门禁不要一上来就卡死先跑一段时间只报告不拦截等团队适应了、存量问题清得差不多了再开启拦截。否则第一天就会有人因为提交被卡而骂娘。4. 浏览器扩展在真实渲染里抓那些静态扫描抓不到的问题4.1 扩展装好之后先做这三件事浏览器扩展的安装通常是从扩展商店或者加载本地解压包。装好之后别急着到处点先做三件事第一打开开发者工具找到 impeccable 的面板。它一般会作为一个新的 tab 出现在 DevTools 里和 Elements、Console 并列。第二在一个你熟悉的页面上跑一次检查看看它报出来的问题你认不认。如果它报的问题你觉得是误报那说明规则配置需要调整。第三确认它检查的是渲染后的 DOM 而不是源码。你可以故意写一个运行时才出现的样式问题看它能不能抓到。4.2 运行时检查能发现什么静态检查发现不了的这是扩展的核心价值我举几个真实例子对比度问题。静态扫描只能看到你写的颜色值但实际渲染时元素可能叠加了半透明遮罩、继承了父级颜色、或者被filter改变了。扩展在真实渲染结果上算对比度才能发现看起来还行、实际不达标的情况。键盘可达性。一个div加了onclick但没加tabindex静态看代码可能觉得没问题但实际用键盘 Tab 键根本聚焦不到。扩展能模拟焦点遍历直接告诉你哪些交互元素键盘够不着。响应式溢出。静态分析很难判断某个布局在 375px 宽度下会不会横向滚动因为它依赖真实的盒模型计算。扩展可以切换视口实时检测scrollWidth clientWidth的元素。焦点样式缺失。很多项目全局outline: none之后忘了补自定义焦点样式静态看不出来扩展一测一个准。4.3 扩展和 CLI 的规则一致性这里有个坑要提醒扩展和 CLI 的规则集必须来自同一份配置。如果扩展用的是默认规则、CLI 用的是项目配置两边报出来的问题对不上你会陷入到底信哪个的混乱。我的做法是把配置文件放在项目根目录扩展里手动指向这个文件确保两边读的是同一套规则和同一份 token。另外扩展的检查是实时的页面一变它就重跑。这在开发时很方便但也意味着它可能在你还没写完的时候就疯狂报错干扰视线。大多数扩展都提供暂停检查的开关写布局阶段可以先暂停写完一个模块再打开检查。5. 和 AI coding agents 配合让 AI 自己遵守规范5.1 为什么要把 impeccable 接进 AI 的工作流前面说了AI 写前端最大的问题是没有约束。impeccable 的规则集恰好可以充当这个约束。思路是这样的在 AI 生成代码之后自动跑一遍 impeccable把报出来的问题再喂回给 AI让它自己修。这就形成了一个闭环——生成、检查、修复、再检查。这个闭环的价值在于它把设计品味这个模糊的东西变成了 AI 可以迭代优化的明确目标。AI 不需要理解什么是好的设计它只需要让 impeccable 的报错数量降到零。目标明确可量化可收敛。5.2 具体怎么接三种集成方式方式一手动循环。最简单你让 AI 生成代码然后自己跑 CLI把报错贴回给 AI。适合刚开始尝试、还没搭自动化的阶段。方式二脚本化循环。写一个脚本生成代码后自动跑检查把结果格式化后追加到 AI 的下一轮输入里。伪代码大概是这样# 伪代码示意流程 generate_code() { ... } run_check() { npx impeccable check ./src --format json; } for i in 1 2 3; do generate_code result$(run_check) if [ $(echo $result | jq .errorCount) -eq 0 ]; then break fi # 把 result 作为反馈喂回给 AI feed_back $result done方式三作为 agent 的工具。如果你用的是支持工具调用的 agent 框架可以把 impeccable 包装成一个工具让 agent 在生成代码后主动调用它、读取结果、自行修复。这是最理想的形态但对 agent 框架有要求。5.3 给 AI 的提示词怎么写才有效光有工具不够提示词也得配合。我总结了几条经验第一明确告诉 AI 有检查工具存在。在系统提示里写清楚生成前端代码后会经过 impeccable 检查请确保遵守项目根目录的配置。第二把规则的关键点提炼进提示词。虽然工具有强制力但提前告知能减少返工。第三反馈时给结构化信息。别把一大坨报错原文丢回去按规则分组、给出文件行号和修复建议AI 修起来更准。注意不要让 AI 去关闭规则来通过检查。有些 agent 会走捷径发现改代码麻烦就去改配置文件把规则关掉。一定要在提示词里明确禁止修改配置文件或者在 CI 里校验配置文件没被改动。6. 踩坑实录我在实际使用中遇到的几个真问题6.1 误报规则太严反而拖慢开发刚上手时我把所有规则都设成error结果一个简单的卡片组件报了二十几条。仔细一看有些是误报——比如它把某个第三方组件的内联样式也算进来了。规则不是越严越好得结合项目实际。我的调整策略是先全开跑一周统计每条规则的误报率误报率高的先降级为warn或者加例外等规则打磨准了再收紧。6.2 性能大项目全量扫描慢得离谱一个几万行的项目全量扫描可能要几分钟。放在 CI 里还能接受放在 pre-commit 里就是灾难。解决办法有两个一是用--staged只扫改动文件二是开启缓存impeccable 一般支持把上次的扫描结果缓存起来没改的文件跳过。缓存文件记得加进.gitignore别提交上去。6.3 token 不同步设计改了规则没跟上这是最隐蔽的坑。设计师把主色调从#3B82F6改成了#2563EB但tokens.json没更新结果 impeccable 一直报颜色不在 token 集合里而实际上代码用的是新颜色。token 文件必须和设计源保持同步最好让设计工具导出 token 后自动同步到项目里别靠手动改。6.4 和现有 lint 工具打架项目里本来就有 ESLint、Stylelintimpeccable 一进来同一个问题可能被报两遍。这时候要明确分工ESLint 管代码逻辑和语法Stylelint 管 CSS 语法impeccable 管设计系统一致性。重叠的规则关掉一边别让开发者面对两份重复的报错。7. 一些关于工具选型和长期维护的个人看法用下来这段时间我对 impeccable 这类工具的判断是它的价值不在于检查而在于统一。一个团队里每个人对好看的理解都不一样争论起来没完没了。有了这套规则争论就变成了规则怎么定这个可讨论、可迭代的问题。规则定下来之后人和 AI 都按同一套标准来沟通成本大幅下降。选型上我不建议盲目追新。如果你的项目还很小、就一两个人手写规范加肉眼 review 可能就够了上这套工具反而是负担。但如果你的项目有多个前端、或者大量用 AI 生成代码那这套东西的投入产出比就很高了。判断标准很简单当你发现同一个设计问题被反复提出来的时候就是该把它自动化的时候。长期维护上我的建议是把规则集当成代码来管理。规则变更走 code review规则文件有版本每次变更记录原因。别让规则集变成没人敢动的黑盒。另外定期回顾那些被频繁触发的规则——如果一条规则天天报错但没人修要么是规则不合理要么是团队根本没打算遵守两种情况都需要处理而不是放着不管。最后分享一个小技巧把 impeccable 的检查结果和你的设计系统文档关联起来。每条规则背后都对应设计系统里的一个决策报错时能直接跳到对应的文档说明。这样新人和 AI 都能理解为什么要有这条规则而不是机械地改代码。工具解决的是能不能查出来文档解决的是为什么要这样两者结合前端设计的impeccable才真正立得住。
阅读完成 · 觉得有帮助？
