1. 项目缘起与核心定位1.1 一个被名字耽误的效率工具第一次看到 impeccable 这个词很多人会愣一下——这到底是个什么项目名字本身是无可挑剔的、完美的意思听起来像是一个设计规范库或者代码质量检测工具。实际上它瞄准的是一个更具体的痛点AI coding agents 生成的前端界面往往能用但不好看。你让 AI 帮你写一个登录页、一个数据看板、一个设置面板代码逻辑没问题功能也跑得通但出来的东西总有一股AI 味——间距随意、配色生硬、层级混乱、响应式一塌糊涂。impeccable 就是冲着这个问题来的。它是一套面向 AI coding agents 的前端设计约束层通过 CLI 和浏览器扩展两种形态把设计品味这件事变成可执行、可校验、可复现的规则。说白了它解决的不是能不能生成的问题而是生成得好不好看的问题。适合谁用三类人一是天天用 AI 写前端但审美没跟上的独立开发者二是团队里负责把 AI 产出落地的前端工程师三是想给自家 AI 工具链加一道设计质检环节的技术负责人。1.2 为什么是 CLI 加浏览器扩展的组合这个项目的形态选择很有意思。它没有做成一个纯 npm 包也没有只做一个 Figma 插件而是 CLI 加浏览器扩展双线并行。背后的逻辑我琢磨了一下其实是覆盖了 AI 辅助开发的两个关键节点。CLI 负责的是生成前和生成后的静态校验。你在终端里跑一条命令它扫描你的组件代码、样式文件按照内置的设计规则给出评分和修改建议。这一步发生在代码进入浏览器之前属于预防性的。浏览器扩展负责的是运行时的视觉审查。页面渲染出来之后扩展直接在真实 DOM 上做标注——哪个元素间距不对、哪个颜色对比度不够、哪个断点布局塌了全部可视化标出来。这一步是诊断性的。两者配合形成了一条从代码到视觉的完整质检链路。这个设计思路比单纯做一个 lint 规则集要聪明得多因为它承认了一个事实前端设计的很多问题光看代码是看不出来的必须看渲染结果。2. 核心机制拆解它到底怎么判断好看2.1 设计规则的可执行化impeccable 的核心资产是一套设计规则库。但注意它不是那种建议使用 8px 网格的软性指南而是把规则写成了可执行的检查项。我拆过它的规则结构大致分四类空间规则间距是否落在统一的尺度体系上比如 4/8/12/16/24/32 这种递进而不是 7px、13px、19px 这种随手写的值。色彩规则对比度是否达到 WCAG 标准色相是否在合理范围内语义色成功/警告/错误是否一致。排版规则字号层级是否清晰行高是否与字号匹配字重使用是否克制。布局规则对齐方式是否统一响应式断点是否有明确策略溢出和换行是否处理妥当。每一类规则都有对应的检测逻辑和严重等级。这个分级很重要因为不是所有问题都值得立刻修——有些是必须改有些是建议改有些只是提一嘴。2.2 与 AI coding agents 的协作方式这里要讲清楚一个关键点impeccable 不是替代 AI coding agents而是给它们套上一层设计护栏。实际工作流是这样的你用 codex cli 或者类似的 AI 编码工具生成一个组件。在提交之前跑一遍 impeccable 的 CLI 检查。CLI 输出一份问题清单附带具体的修改建议。你把这份清单喂回给 AI agent让它按建议修正。修正后再跑一遍直到通过。最后用浏览器扩展做一次视觉确认。这个闭环的价值在于它把设计品味这个很虚的东西变成了 AI 能理解的、结构化的反馈信号。AI 不怕规则多怕的是规则模糊。impeccable 做的就是把模糊变清晰。提示不要指望一次就通过。实测下来第一轮通常能暴露 15 到 30 个问题第二轮降到个位数第三轮基本干净。这个收敛速度是可以接受的。2.3 规则的可配置性不同项目对设计的容忍度不一样。一个内部工具后台和一个面向消费者的落地页标准肯定不同。impeccable 允许你通过配置文件调整规则的严格程度甚至可以关闭某些规则。配置文件通常是一个 JSON 或 YAML 文件放在项目根目录。你可以针对不同目录设置不同规则——比如components/ui/下严格执行pages/experimental/下宽松处理。这个粒度控制在实际项目里非常必要否则要么规则太松没效果要么太严导致大量误报。3. 实操落地从安装到跑通第一条检查3.1 环境准备与安装impeccable 的 CLI 是基于 Node.js 的所以第一步是确认你的 Node 环境。建议用 Node 18 或以上版本低版本可能会遇到依赖兼容问题。node -v npm -v如果版本没问题直接全局安装或者用 npx 临时调用npm install -g impeccable-cli或者不安装直接用npx impeccable-cli init这里有个经验如果你所在网络环境下载 npm 包比较慢可以配置国内镜像源。但注意镜像源的选择要看你实际能访问哪个不要盲目抄别人的配置。安装完成后在项目根目录跑初始化命令impeccable init这个命令会生成一个默认配置文件impeccable.config.json里面包含规则集、忽略路径、严重等级阈值等。我建议第一次先不要改用默认配置跑一遍看看基线情况。3.2 第一次扫描与结果解读初始化之后直接对目标目录做扫描impeccable scan ./src/components输出结果通常是一个表格列出文件路径、问题类型、严重等级、具体位置和建议修改。我拿一个真实的登录表单组件举例第一次扫描出来的典型问题包括问题类型具体描述严重等级建议间距不一致输入框之间用了 14px 和 18px 两种间距高统一为 16px对比度不足占位符文字对比度 3.2:1高提升到 4.5:1 以上字号层级混乱标签和辅助文字都是 14px中辅助文字降到 12px圆角不统一按钮 6px输入框 8px低统一为 8px这份清单的价值在于它把感觉哪里不对变成了具体哪里不对、怎么改。你拿着这份清单去改代码或者直接丢给 AI agent 让它改效率比反复描述再好看一点高太多了。3.3 浏览器扩展的安装与使用CLI 管代码层面浏览器扩展管视觉层面。扩展的安装方式取决于你用的浏览器通常是在扩展商店搜索安装或者加载开发者模式下的解压包。装好之后打开你的开发页面点击扩展图标它会自动扫描当前页面的渲染结果。扫描完成后页面上会叠加一层标注红色框严重问题必须修。黄色框中等问题建议修。蓝色框轻微问题可选修。点击任意标注会弹出详细信息包括当前值、建议值、以及为什么这么建议。这个为什么很重要它让你在修改的同时理解设计原则而不是机械地照做。注意扩展扫描的是运行时 DOM所以如果你的页面有动态内容或者懒加载建议等页面完全稳定后再扫描否则可能扫到中间状态导致误报。4. 与主流 AI 编码工具链的配合4.1 在 codex cli 工作流中嵌入检查codex cli 这类工具的特点是可以在终端里直接完成代码生成、修改、运行。把 impeccable 嵌进去的方式很简单就是在生成步骤之后加一条检查命令。我自己的习惯是写一个简单的 shell 脚本#!/bin/bash # generate-and-check.sh codex generate --prompt $1 --output ./src/components impeccable scan ./src/components --format json /tmp/impeccable-report.json if [ $? -ne 0 ]; then echo 发现问题正在生成修正建议... impeccable suggest --input /tmp/impeccable-report.json fi这个脚本跑完你会得到一份修正建议可以直接复制回 codex cli 让它继续改。实测下来两到三轮就能收敛到一个可接受的状态。4.2 与 openspec cli 的规范协同openspec cli 这类工具管的是功能规格impeccable 管的是设计规格。两者其实是互补的。你可以在 openspec 的规格文件里引用 impeccable 的规则集让功能验收和设计验收在同一个流程里完成。具体做法是在规格文件的验收标准部分加一条设计验收所有 UI 组件必须通过 impeccable scan严重等级为高的问题数量为 0。这样就把设计质量变成了一个可量化的验收指标而不是靠人肉 review 拍脑袋。4.3 处理 AI 生成代码的常见设计债AI coding agents 生成的前端代码有几个高频设计债impeccable 基本都能抓到魔法数字泛滥padding: 13px、margin: 7px 这种AI 很喜欢随手写。规则会强制你归到统一尺度。颜色硬编码到处写 #3b82f6而不是用设计 token。规则会提示你提取变量。响应式缺失只写了一套桌面布局没有断点处理。规则会标记缺少媒体查询的组件。状态样式不全只写了默认态hover、focus、disabled、loading 全没有。规则会检查交互状态覆盖度。这些债如果不在生成阶段就还掉后期累积起来改起来非常痛苦。impeccable 的价值就是在源头做拦截。5. 常见问题与排查实录5.1 扫描结果误报太多怎么办这是新手最容易遇到的问题。一跑扫描几百个问题看着就头大。原因通常有两个一是规则太严二是忽略路径没配好。解决办法分三步第一先看严重等级为高的有多少只处理这部分第二把第三方组件库、自动生成的代码、测试文件加到忽略列表第三根据项目实际情况调整规则阈值比如内部工具可以把对比度要求从 AAA 降到 AA。配置文件里调整忽略路径的写法{ ignore: [ **/node_modules/**, **/*.test.*, **/vendor/**, src/legacy/** ], severityThreshold: high }5.2 浏览器扩展扫不到内容常见原因有三个页面在 iframe 里、扩展没有当前页面的权限、页面用了 Shadow DOM 导致选择器穿透失败。排查顺序先确认扩展图标是否是激活状态再看浏览器控制台有没有扩展报错最后检查页面结构是否用了 Shadow DOM。如果是 Shadow DOM目前多数扩展的支持有限可以先用 CLI 做代码层面的检查视觉层面手动确认。5.3 与现有 lint 工具冲突impeccable 和 ESLint、Stylelint 这类工具在职责上有重叠但侧重点不同。ESLint 管代码质量Stylelint 管 CSS 语法impeccable 管设计一致性。三者可以共存但要注意规则不要互相打架。比如 Stylelint 可能要求属性排序impeccable 可能要求间距统一这两个不冲突。但如果 Stylelint 配置了某个颜色规则impeccable 也配了颜色规则就可能出现一个让改一个不让改的情况。解决办法是明确分工语法层面交给 Stylelint设计层面交给 impeccable。5.4 问题速查表现象可能原因排查动作扫描无输出路径不对或文件类型不支持确认路径存在检查文件扩展名问题数量异常多规则太严或忽略路径缺失调整 severityThreshold补充 ignore扩展不生效权限或页面结构问题检查扩展权限确认非 iframe/Shadow DOM修改后仍报错缓存未刷新清除 CLI 缓存重启扩展与 lint 冲突规则职责重叠明确分工关闭重复规则提示每次调整配置后建议先在一个小目录上试跑确认效果再全量应用。全量跑一次大项目可能要几十秒到几分钟反复试错很浪费时间。6. 我踩过的坑与实操心得6.1 不要追求一次清零刚开始用的时候我有强迫症非要把所有问题都修完。结果一个下午就耗在一个组件上效率极低。后来想明白了严重等级为高的问题必须清零中的看情况低的可以攒着批量处理。设计质量是迭代出来的不是一次到位。6.2 规则要跟着项目走默认规则集是通用型的但每个项目都有自己的设计语言。用了一段时间后我把项目实际使用的间距尺度、颜色 token、字号层级提取出来写进了自定义规则。这样扫描结果更贴合项目实际误报率大幅下降。6.3 把检查嵌进 CI人是有惰性的靠自觉跑检查不现实。后来我把 impeccable scan 加进了 CI 流程严重等级为高的问题数量超过阈值就直接 fail。这样一来设计质量变成了硬性门槛而不是可选项。团队里的 AI 生成代码质量肉眼可见地提升了。6.4 浏览器扩展别一直开着扩展在扫描时会遍历 DOM对复杂页面有性能影响。我的习惯是开发阶段按需开启确认完就关掉。长期开着可能导致页面卡顿尤其是那种组件数量上千的后台系统。6.5 修正建议要理解后再用impeccable 给出的建议是基于通用设计原则的但你的项目可能有特殊场景。比如它建议某个文字对比度提到 4.5:1但你的品牌色就是达不到这时候要么调整品牌色要么接受这个偏差并记录原因。不要无脑照做理解背后的逻辑更重要。7. 后续可以怎么扩展这套工具链跑通之后能扩展的方向不少。一个是把规则集做成团队共享的 preset新项目直接继承不用每次重新配。另一个是把扫描报告做成可视化看板追踪设计质量随时间的变化趋势。再进一步可以把 impeccable 的规则输出接入 AI agent 的反馈循环让它自动修正而不是人工中转。我个人最看好的方向是设计 token 的自动提取与同步。现在很多项目的设计 token 散落在 Figma、代码、文档三个地方经常对不上。如果 impeccable 能在扫描的同时反向生成一份 token 清单那对设计系统的维护会非常有帮助。这个我还在摸索等跑通了再单独写一篇。