1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的画面前端工程师对着 AI 生成的代码皱眉头——功能是能跑但间距忽大忽小、颜色差一点点、圆角不统一、响应式断点乱成一锅粥。AI coding agents 写业务逻辑越来越靠谱可一到“审美”这件事上就经常掉链子。impeccable 这个项目本质上就是冲着这个痛点来的。它的定位可以概括成一句话给 AI 编码代理装上一双“设计眼”。你给它一个前端界面它帮你判断这个界面在视觉层面是否“无懈可击”——对齐、层级、对比、留白、一致性这些设计基本功有没有做到位。它不是一个 UI 框架也不是一个组件库而更像是一个设计质量的检查器与约束层通过 CLI 和浏览器扩展两种形态把“设计规范”这件事变成 AI 代理可以理解、可以执行的输入。那它适合谁我梳理了三类人。第一类是用 AI 代理写前端但自己设计功底一般的开发者你让 AI 生成页面生成完心里没底不知道好不好看impeccable 能给你一个相对客观的判断。第二类是团队里负责设计规范落地的人你想让所有 AI 生成的界面都符合同一套设计语言impeccable 可以当成一道自动化的“设计门禁”。第三类是对前端细节有强迫症的独立开发者你一个人干活没有设计 reviewimpeccable 相当于一个随叫随到的设计搭档。关键词里出现的 CLI、browser extension、AI coding agents、frontend design其实已经把它的技术轮廓勾出来了命令行工具负责批量和集成浏览器扩展负责实时和可视化AI 代理是它的主要服务对象前端设计是它的核心战场。接下来我会把这几个部分拆开讲清楚它背后的设计思路、实操要点以及我在实际折腾过程中踩过的坑。2. 整体设计思路拆解为什么是 CLI 加浏览器扩展这套组合2.1 为什么不做成纯 Web 服务而是 CLI 优先很多人第一反应会问设计检查这种东西做个网页上传截图不就行了为什么要搞 CLI我一开始也这么想但实际用下来才明白CLI 优先是为了贴合 AI coding agents 的工作流。现在的 AI 代理大多在终端里跑它们能执行命令、读文件、改代码但不太擅长“打开一个网页、点按钮、看结果”这种交互。你把 impeccable 做成 CLI代理就能在生成代码之后直接调用它拿到结构化的检查结果然后自己决定要不要改。这背后的逻辑是把设计检查变成可编程的一步。传统设计 review 是人看人评主观、慢、不可自动化。CLI 化之后检查结果可以是 JSON、可以是退出码、可以是 diff代理和 CI 都能消费。我实测下来这种“机器可读”的设计反馈才是 AI 代理真正能利用起来的形式。你给它一段自然语言说“这个页面不好看”它无从下手你给它“间距不一致第 3 和第 5 个卡片的 padding 差 4px”它立刻就能改。另一个原因是可复现。浏览器里手动点出来的检查换个环境、换个时间可能结果就不一样。CLI 跑的是同一套规则、同一份配置结果稳定适合放进流水线。这点对于团队协作特别重要——你不能今天说合格明天说不合格标准得是钉死的。2.2 浏览器扩展补的是哪块短板CLI 强在自动化和集成但它有个天然短板看不见。设计这件事很多问题是“看一眼就知道”的比如某个元素明显偏了、某个颜色刺眼。CLI 输出的是文字和数字你得在脑子里重建画面。浏览器扩展补的就是这块——它直接在你的页面上叠加可视化的标注哪里对齐有问题、哪里间距不对用高亮、辅助线、色块标出来。我个人的使用习惯是开发阶段用扩展实时看提交前用 CLI 跑一遍做门禁。扩展负责“感觉”CLI 负责“标准”。两者共享同一套规则引擎所以扩展里看到的问题CLI 里一定能复现不会出现“扩展说没问题、CLI 报一堆错”这种割裂。这个设计我觉得挺聪明的它没有让两个形态各搞一套而是一个内核、两种外壳。从技术实现角度推测这部分是基于常见实践的合理补全扩展大概率是通过 content script 注入页面读取计算后的样式computed style和布局盒模型getBoundingClientRect 之类然后跑规则。CLI 则可能是通过无头浏览器加载页面拿到同样的数据再跑同一套规则。这样规则只写一遍两边复用维护成本低。2.3 它和普通 linter 的本质区别有人会说ESLint、Stylelint 不也能查样式问题吗区别在于层次不同。Stylelint 查的是“你的 CSS 写得规不规范”比如有没有用未知属性、有没有重复选择器。impeccable 查的是“你渲染出来的界面好不好看”比如两个本应对齐的元素实际差了 2px、标题和正文的对比度不够、一组卡片的圆角不统一。打个比方Stylelint 像是检查你作文的语法和错别字impeccable 像是检查你这篇作文读起来顺不顺、有没有逻辑断层。前者是规则层面的后者是效果层面的。这也是为什么它必须依赖真实渲染——不渲染出来你根本不知道最终长什么样。这个定位决定了它不能只做静态分析必须能跑起来页面这也是它同时需要 CLI无头渲染和扩展真实浏览器渲染的原因。3. 核心能力解析impeccable 到底检查哪些东西3.1 对齐与间距设计的地基对齐和间距是设计里最基础、也最容易被 AI 忽略的东西。AI 生成代码时经常这里写个margin: 13px那里写个padding: 17px单看每个值都“差不多”放一起就乱了。impeccable 这类工具的核心能力之一就是检测视觉节奏的一致性。具体来说它会看几个维度。第一是同组元素的对齐比如一排卡片的左边缘是不是在同一条垂直线上标题和它下面的正文是不是左对齐。第二是间距的规律性比如所有卡片之间的间距是不是同一个值或者是不是某个基准值的整数倍常见的是 4px 或 8px 网格。第三是边距的对称性比如一个容器左右 padding 是不是相等。我实测过一个典型场景让 AI 生成一个三列卡片布局它给每个卡片写了不同的 margin结果渲染出来卡片宽度参差不齐。CLI 跑一遍直接报出“卡片间距不一致检测到 12px、16px、20px 三种值”。这种反馈对 AI 代理来说就是明确的修改指令它拿到之后会把间距统一成基准值。这就是把模糊的“不好看”翻译成了精确的“哪里不对”。注意间距检查一定要结合设计系统来配。如果你的项目本来就用 4px 网格那基准值就设 4如果用的是 8px就设 8。配错了会导致大量误报反而干扰判断。3.2 对比度与可读性不只是无障碍对比度检查很多工具都有但 impeccable 的侧重点不太一样。常规工具查的是 WCAG 标准比如正文对比度要达到 4.5:1。impeccable 除了这个还会看视觉层级的对比是否合理——标题是不是明显比正文重、次要信息是不是明显比主要信息弱。这个区别很关键。WCAG 达标不代表视觉层级清晰。我见过不少 AI 生成的页面标题和正文颜色都达标了但两者灰度太接近扫一眼分不出主次。impeccable 会检测这种“层级塌陷”提示你标题和正文的对比度差距不够需要拉开。实操上我建议把对比度检查分成两档硬性档是 WCAG 标准不达标直接报错软性档是层级建议不达标给警告。这样既保证了无障碍底线又不会因为层级建议太严格而让代理频繁改动。这个分档思路是我自己加的原工具不一定内置但你可以通过配置规则严重级别来实现。3.3 一致性颜色、圆角、阴影的统一一致性是 AI 生成代码的重灾区。同一个页面里主色可能出现了#3b82f6、#3B82F6、rgb(59,130,246)三种写法虽然渲染出来一样但代码层面已经乱了。更麻烦的是圆角有的卡片border-radius: 8px有的6px有的10px肉眼能看出细微差别但说不清哪里不对。impeccable 的一致性检查会聚类相似值。比如它发现页面上有 6px、7px、8px 三种圆角就会提示“圆角值不统一建议归并到 8px”。颜色同理它会把视觉上接近的颜色归为一组提示你统一。这个能力对 AI 代理特别有用因为代理很容易在生成多个组件时“各写各的”一致性检查相当于一个事后收口。我踩过的一个坑是一致性检查的阈值设太严会误伤。比如设计上故意用两种圆角区分主次卡片工具可能误判为不一致。解决办法是在配置里加白名单把有意为之的差异排除掉。这个配置过程有点繁琐但配好之后一劳永逸。3.4 响应式断点AI 最容易翻车的地方响应式是 AI 生成前端时最容易出问题的地方。它经常只考虑桌面端或者断点设得乱七八糟导致中间尺寸下布局崩坏。impeccable 的响应式检查会在多个视口宽度下渲染页面对比布局变化找出断点设置不合理的地方。具体检查什么比如某个断点下元素溢出了容器、某个断点下文字换行导致高度突变、某个断点下本该隐藏的元素还显示着。这些在单一视口下看不出来必须多视口对比。CLI 形态在这里优势明显因为它可以脚本化地跑多个宽度扩展形态则更适合手动拖动窗口实时看。我一般会配一组标准断点320、375、768、1024、1440。这五个宽度覆盖了主流设备。impeccable 在这五个宽度下各跑一遍输出每个宽度的问题列表。代理拿到之后就能针对性地加媒体查询。这一步能挡掉大量“桌面好看、手机稀烂”的问题。4. 实操过程从安装到跑通第一条检查4.1 环境准备与安装impeccable 的安装按常见 CLI 工具的惯例大概率是通过包管理器分发。我以 npm 生态为例说明如果你的项目用的是别的生态思路类似换对应的包管理器即可。# 全局安装方便在任何项目里调用 npm install -g impeccable # 或者作为项目开发依赖锁定版本适合团队协作 npm install --save-dev impeccable我推荐项目内安装而不是全局安装。原因有两个一是版本锁定团队每个人跑出来的结果一致二是可以写进 package.json 的 scriptsCI 里直接调用。全局安装适合你个人快速试用但正式项目别这么干。安装完之后跑一下版本命令确认装好了impeccable --version如果提示命令找不到八成是全局 bin 目录没在 PATH 里。这时候别急着改 PATH先试试用npx impeccable --versionnpx 会自动找本地或临时安装的包能省掉很多环境折腾。提示如果你所在的环境对包管理器有代理或镜像配置要求记得先配好 registry否则安装会卡住。这部分按你所在团队的标准配置来就行。4.2 初始化配置文件impeccable 这类工具通常需要一个配置文件来定义规则和阈值。按惯例初始化命令会生成一个默认配置impeccable init这会生成一个类似impeccable.config.json的文件。默认配置一般比较宽松我建议第一次先跑默认配置看看报什么再逐步收紧。一上来就配一堆严格规则结果满屏报错反而不知道从哪下手。配置文件里我通常会关注这几项配置项作用我的建议值spacingBase间距基准值4 或 8跟你的设计系统走contrastLevel对比度检查级别AA硬性 层级警告consistencyThreshold一致性聚类阈值中等太严误报多viewports响应式检查视口320/375/768/1024/1440ignore忽略的选择器或路径第三方组件、图标字体这个表是我根据常见实践整理的具体字段名以你装到的版本为准。核心思路是基准值跟设计系统对齐检查级别分硬软两档忽略项把不可控的部分排除掉。4.3 跑第一条检查配置好之后跑检查的命令通常是这样的# 检查本地开发服务器上的页面 impeccable check http://localhost:3000 # 或者检查构建产物里的静态页面 impeccable check ./dist/index.html我建议先对着本地开发服务器跑因为开发服务器有热更新你改完代码刷新就能重跑迭代快。等稳定了再对构建产物跑作为提交前的门禁。第一次跑的结果大概率会让你有点意外——报的问题可能比你想象的多。别慌这是正常的。AI 生成的代码在细节上本来就粗糙impeccable 只是把它量化了。我的做法是先按严重级别排序从 error 开始修warning 攒着批量处理。error 通常是硬伤比如对比度不达标、元素溢出warning 多是建议比如间距可以更统一。4.4 把检查接入 AI 代理的工作流这是 impeccable 最有价值的一环。你要让 AI 代理在生成代码后自动跑检查然后根据结果自我修正。实现方式取决于你用的代理框架但核心逻辑是一样的生成 → 检查 → 解析结果 → 修正 → 再检查。我以常见的脚本化方式举例# 伪代码思路具体命令按你的代理框架调整 impeccable check http://localhost:3000 --format json report.json # 代理读取 report.json针对每条问题生成修改 # 修改后重新跑 check直到 error 清零这里的关键是--format json。人类看文本输出舒服但代理需要结构化数据。JSON 里每条问题包含位置、类型、当前值、建议值代理拿到就能精确修改不用猜。我实测下来这个闭环跑通之后AI 生成的前端质量提升非常明显。以前要人工 review 半天的问题现在代理自己就能修掉七八成。剩下的两三成通常是需要设计判断的比如“这个留白是不是太大”这种主观问题工具给不了答案还得人来定。注意别让代理无限循环修正。设一个最大迭代次数比如 3 次超过就停下来人工介入。否则代理可能在一个问题上反复横跳浪费时间和额度。5. 浏览器扩展的使用与联动5.1 扩展的安装与激活浏览器扩展的安装按惯例是从浏览器的扩展商店获取或者加载开发者模式的解压包。装好之后通常在浏览器工具栏会出现一个图标。点开它它会检测当前页面然后叠加可视化标注。我第一次用的时候有个小困惑扩展在哪些页面上生效。一般它只对本地开发地址localhost、127.0.0.1或者你显式授权的域名生效不会在所有网页上乱跑。这是合理的设计既保护隐私也避免干扰正常浏览。如果你发现扩展没反应先确认当前页面是不是在它的生效范围内。激活之后页面上会出现几种标注对齐辅助线、间距色块、问题高亮。我建议先关掉所有标注只开一类比如只看对齐。全开的话页面会很花反而看不清。一类一类看改完一类再看下一类效率更高。5.2 扩展和 CLI 的配合节奏我的使用节奏是这样的写代码时扩展常开实时看问题提交前 CLI 跑一遍确认清零。扩展的好处是即时你改一行 CSS刷新页面标注立刻更新反馈闭环很短。CLI 的好处是全面和可复现它会把所有视口、所有规则都跑一遍不漏。有个细节值得说扩展里看到的和 CLI 里跑出来的理论上应该一致但偶尔会有差异。差异通常来自两个地方一是扩展用的是你当前浏览器窗口的尺寸CLI 用的是配置里的固定视口二是扩展可能受浏览器插件、字体渲染影响CLI 用的是干净环境。遇到差异以 CLI 为准因为它是标准化的。5.3 把扩展当成设计沟通工具除了自己用扩展还有个妙用跟非技术同事沟通设计问题。你截个图上面带着标注说“这里对齐差了 2px”比纯文字描述直观得多。我试过把扩展标注截图发给产品经理对方一眼就懂了省掉很多来回解释。这个用法虽然不在工具的官方定位里但实际价值很高。设计问题很多时候是“说不清”可视化标注解决了这个沟通成本。如果你在团队里推 impeccable不妨把它当成一个设计沟通的通用语言来推广。6. 常见问题与排查技巧实录6.1 检查结果太多不知道从哪下手这是新手最常见的问题。第一次跑报几百条直接劝退。我的处理办法是分级 分批。先只看 error把 error 清零再看 warning 里出现频率最高的那类批量修最后处理零散的建议。具体操作上CLI 一般支持按级别过滤# 只看 error impeccable check http://localhost:3000 --level error # 只看某一类规则 impeccable check http://localhost:3000 --rule spacing按规则类型过滤特别有用因为同一类问题往往可以用同一个方法批量修。比如所有间距问题你统一改成基准值的倍数一次就能消掉一大片。6.2 误报怎么处理误报是任何静态检查工具都躲不开的。impeccable 的误报通常来自这几种情况设计上故意的不一致比如主次卡片用不同圆角、第三方组件的样式你控制不了、动态内容导致的临时状态比如加载中的骨架屏。处理误报的标准做法是加忽略规则。配置文件里一般有 ignore 字段可以按选择器、按路径、按规则类型忽略。我建议忽略规则要写注释说明为什么忽略否则过几个月你自己都忘了当初为啥放过它。{ ignore: [ { selector: .third-party-widget, reason: 第三方组件样式不可控 }, { rule: consistency, selector: .hero-card, reason: 主卡片故意用更大圆角区分层级 } ] }提示忽略规则要克制。每加一条忽略就少一分检查覆盖。如果某个规则误报特别多先想想是不是阈值配错了而不是无脑忽略。6.3 响应式检查跑得慢多视口渲染确实耗时尤其是页面复杂的时候。我试过跑一个重页面五个视口跑下来要一两分钟。优化思路有几个减少视口数量如果项目只支持桌面和移动就别跑五个、只检查关键页面不是每个页面都要全量跑、并行跑如果工具支持。还有一个技巧开发阶段只跑当前正在改的视口提交前再跑全量。这样日常迭代快门禁又不漏。这个策略我在多个项目里用过平衡了速度和覆盖。6.4 和现有 lint 工具冲突怎么办impeccable 和 Stylelint、ESLint 不是替代关系是互补。但配置不当会互相干扰比如 Stylelint 要求某种写法impeccable 又建议另一种。解决办法是明确分工Stylelint 管代码规范impeccable 管渲染效果。两者规则不重叠就不会冲突。如果确实遇到冲突比如某个属性 Stylelint 要求 A 值、impeccable 建议 B 值那说明你的设计系统本身有矛盾得先在设计层面统一而不是在工具层面打补丁。这种情况我遇到过最后是改了设计 token 才解决的。6.5 常见问题速查表现象可能原因排查方向命令找不到未安装或 PATH 问题用 npx 试检查安装扩展无反应页面不在生效范围确认是本地地址或已授权结果与扩展不一致视口或环境差异以 CLI 为准统一配置误报太多阈值太严或未加忽略调阈值加 ignore 注释跑得慢视口多或页面重减视口只跑关键页代理反复改不好缺结构化反馈用 JSON 输出设迭代上限这张表是我自己踩坑总结的不一定覆盖所有情况但能解决八成常见问题。遇到表里没有的先看工具的日志输出日志通常会告诉你哪一步出了问题。7. 我个人的一些使用体会折腾 impeccable 这段时间最大的感受是AI 生成前端的上限取决于你给它多少结构化的约束。你光说“做好看点”它做不好你给它一套可执行的检查规则它就能一步步逼近“好看”。impeccable 的价值不在于它自己多聪明而在于它把设计这件事翻译成了机器能懂的语言。另一个体会是工具再好也替代不了设计判断。impeccable 能告诉你间距不一致、对比度不够但它没法告诉你“这个页面应该是什么气质”。那些需要审美决策的部分还是得人来。我的用法是让工具处理 80% 的机械问题自己专注剩下 20% 的判断。这个分工我觉得挺舒服。最后分享一个小技巧把 impeccable 的检查结果当成 AI 代理的“设计记忆”。每次代理改完把检查通过的状态存下来下次生成类似组件时把这份“合格样本”作为参考喂给代理。这样代理会逐渐学会你的设计偏好生成的东西越来越接近你的标准。这个做法我还在摸索但初步效果不错值得一试。