1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个项目名我脑子里蹦出来的第一反应是——这词儿选得挺有意思。impeccable无瑕疵的、无可挑剔的。放在前端设计和AI编码代理的语境里它其实是在喊一个很实在的口号让AI写出来的前端代码看起来不那么AI味。你如果用过任何AI coding agent帮你生成过页面应该懂我在说什么。它们能跑功能也对但就是透着一股说不清道不明的塑料感——间距要么太紧要么太松颜色搭配像是从2015年的Bootstrap模板里扒出来的圆角、阴影、字体层级全都差那么一口气。代码能交差但离impeccable还差着十万八千里。这个项目瞄准的就是这个痛点。它不是一个从零开始的前端框架也不是又一个组件库。它更像是一套约束层或者说审美规则引擎夹在你的AI编码代理和最终输出之间把那些能跑但难看的结果往能看且耐看的方向拽。核心关键词里出现的CLI、browser extension、AI coding agents基本勾勒出了它的形态一个可以通过命令行调用的工具同时提供浏览器扩展来辅助验证和调试最终服务于AI编码代理的前端产出质量。适合谁看三类人。第一类是把AI coding agent当日常生产力工具的前端开发者你已经在用Codex CLI、Zcode CLI这类工具写代码了但每次生成完UI都得手动调半天。第二类是技术负责人或者团队里的审美把关人你需要一套可复用的规则让团队里所有人用AI生成的界面保持统一水准。第三类是对前端设计有追求但不想每次都从设计系统开始搭的独立开发者你希望AI帮你干活的同时产出能直接见人。我花了大概两周时间把这个项目的核心逻辑摸了一遍也在自己的几个小项目里试了试。下面把我理解的东西拆开讲包括它为什么这么设计、怎么用、踩了哪些坑。2. 核心设计思路拆解为什么是约束而不是生成2.1 AI编码代理在前端场景下的真实短板要理解impeccable的设计逻辑得先搞清楚AI coding agent在前端这件事上到底差在哪。我自己的观察是问题不在能不能写出来而在写出来之后像不像人写的。大语言模型在生成前端代码时有一个很明显的倾向它会优先保证功能正确性和语法正确性然后才考虑视觉呈现。这导致几个典型症状。第一间距系统缺失。模型会随手写margin: 13px或者padding: 0.7rem这种没有规律的值因为它只是在填一个看起来合理的数而不是在遵循一套间距刻度。第二颜色选择随意。除非你在prompt里明确给了色板否则模型倾向于用#333、#666、#f5f5f5这种安全但平庸的颜色偶尔还会蹦出饱和度极高的蓝色或红色。第三层级关系模糊。标题和正文的字号差距不够字重变化不明显导致页面看起来平。这些问题单独看都不致命但叠加在一起就是那种一眼AI的观感。impeccable的思路不是让AI重新学一遍设计而是在输出之后加一层规则化的修正和约束把那些偏离审美基准的值拉回来。2.2 为什么选择CLI加浏览器扩展的组合形态这个项目的形态选择挺讲究的。CLI负责的是批量化、可脚本化的修正浏览器扩展负责的是实时化、可视化的验证。两者分工明确。CLI的定位是嵌入到你的开发流程里。你可以在AI agent生成完代码之后跑一条命令让它扫描你的CSS或者Tailwind类名把不符合规则的间距、颜色、字号标记出来甚至直接自动修正。这种生成-扫描-修正的流水线适合在CI/CD里跑也适合在本地开发时作为pre-commit钩子。浏览器扩展的定位则更偏向调试和验证。你在浏览器里打开页面扩展会实时高亮那些违规的元素告诉你哪个间距不在刻度上、哪个颜色对比度不够、哪个字号跳级了。这种即时反馈对于调UI特别有用因为你不用反复跑CLI再刷新页面。我一开始觉得浏览器扩展有点多余后来发现它解决了一个很实际的问题AI生成的代码你未必会逐行看。很多时候你让agent改一个组件它顺手把旁边的样式也动了你不一定注意到。扩展能帮你把这些顺手改动里的问题揪出来。2.3 规则引擎的核心刻度化与容差机制impeccable最核心的设计我认为是它的刻度化思维加容差机制。这两个词听起来有点抽象我用实际例子解释。刻度化就是说它不要求你的间距必须是某个精确值而是要求你的间距必须落在某个刻度上。比如它定义了一套间距刻度4px、8px、12px、16px、24px、32px、48px、64px。你写margin: 15px它会告诉你这不在刻度上最接近的是16px。你写padding: 1.1rem换算下来是17.6px也不在刻度上建议改成16px或24px。容差机制则是说它不会因为1px的偏差就报错。比如你写margin: 15px如果容差设的是2px那它可能就放过了因为15离16只差1px。但如果容差设的是0那它就会标记出来。这个容差是可以配置的取决于你对impeccable的定义有多严格。这套机制的好处是它给了AI生成结果一个可量化的审美基准。你不需要跟AI解释间距要好看你只需要告诉它间距必须落在这些值上然后让impeccable去检查。这比在prompt里写一堆形容词有效得多。3. 核心细节解析与实操要点3.1 安装与初始化从零到能跑impeccable的安装方式取决于你用的是哪个包管理器。我自己的环境是Node.js 18以上用npm装的。命令大概是这样的npm install -g impeccable-cli装完之后在你的项目根目录跑初始化impeccable init这个命令会做几件事。第一在项目根目录生成一个impeccable.config.json文件里面是默认的规则配置。第二如果你项目里有package.json它会尝试检测你用的CSS方案纯CSS、Sass、Tailwind、CSS-in-JS等然后调整配置里的扫描路径。第三它会生成一个.impeccablerc的忽略文件类似.gitignore用来排除不需要检查的目录。注意如果你用的是monorepo初始化的时候最好在具体的子包目录里跑而不是在根目录。我试过在根目录跑结果它把node_modules里的东西也扫了一遍慢得离谱。初始化完之后你可以先跑一次dry-run看看效果impeccable check --dry-run这个命令不会修改任何文件只会输出一份报告告诉你哪些地方不符合规则。我第一次跑的时候报告里密密麻麻全是警告因为默认配置的容差设得很小。后来我把容差调大了一点才变得可用。3.2 配置文件详解每个参数背后的意图impeccable.config.json的结构不算复杂但每个字段都值得说清楚。我挑几个最关键的讲。{ spacing: { scale: [4, 8, 12, 16, 24, 32, 48, 64], tolerance: 2, autoFix: true }, typography: { scale: [12, 14, 16, 18, 20, 24, 30, 36, 48], tolerance: 1, lineHeightRatio: 1.5 }, color: { palette: [#1a1a1a, #4a4a4a, #8a8a8a, #e0e0e0, #ffffff], contrastMin: 4.5, autoFix: false }, scan: { include: [src/**/*.css, src/**/*.tsx, src/**/*.jsx], exclude: [node_modules, dist, *.test.*] } }spacing.scale就是间距刻度我建议根据你项目的设计系统来定。如果你用的是Tailwind默认配置那刻度就是[0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64]。如果你有自己的设计系统就按你的来。spacing.tolerance是容差单位是px。设成2意味着偏差在2px以内就不报错。我一般设2因为设计稿和实际实现之间总有点误差设0会太吵。spacing.autoFix控制是否自动修正。我建议初期设成false先看看报告确认规则合理了再开自动修正。不然它可能把你一些有意为之的间距也改了。typography.lineHeightRatio是行高比例默认1.5。这个值影响的是正文的行高检查。如果你项目里正文行高是1.6或1.7记得改这个值不然会误报。color.contrastMin是最小对比度默认4.5这是WCAG AA标准。如果你做的是无障碍要求更高的项目可以调到7。但要注意调高之后很多浅色文字都会被标记你得有心理准备。3.3 浏览器扩展的安装与使用浏览器扩展的安装方式取决于你用的浏览器。我是在Chrome里装的从项目的release页面下载crx文件然后拖到扩展管理页面。装完之后你打开任何本地开发服务器上的页面扩展图标会亮起来。点开扩展你会看到一个侧边栏里面列出了当前页面上所有违规的元素。每条违规会告诉你元素选择器、违规类型间距/字号/颜色、当前值、建议值。你可以点击某条违规页面上对应的元素会高亮。提示扩展默认只检查本地开发服务器localhost上的页面。如果你想检查线上页面需要在扩展设置里手动添加域名。但我不建议这么做因为线上页面的样式可能经过了压缩和合并检查结果会不准。扩展还有一个实时模式开启之后你在DevTools里改样式扩展会实时告诉你改后的值是否符合规则。这个功能在手动调UI的时候特别好用相当于有个设计系统警察站在你旁边。3.4 与AI编码代理的集成方式impeccable跟AI coding agent的集成我试过两种方式。第一种是后置修正。你让agent生成完代码然后跑impeccable fix让它自动修正。这种方式简单直接但有个问题agent可能生成了一些结构上的问题比如用了不该用的标签、嵌套层级太深这些impeccable管不了。它只管样式层面的规则。第二种是前置约束。你把impeccable的规则导出成一份简短的说明塞到agent的system prompt或者项目级的instructions文件里。比如本项目遵循以下样式规则 - 间距必须使用以下值之一4, 8, 12, 16, 24, 32, 48, 64 (px) - 字号必须使用以下值之一12, 14, 16, 18, 20, 24, 30, 36, 48 (px) - 颜色必须使用项目色板中的值 - 正文行高为字号的1.5倍这种方式的好处是agent在生成的时候就会尽量遵守规则减少后置修正的工作量。但缺点是agent不一定每次都记得住尤其是对话轮次多了之后。我自己的做法是两者结合在prompt里给规则生成完再跑一次check有问题的手动修或者让agent再改一轮。这样下来最终产出的质量比我之前纯靠agent生成要好不少。4. 实操过程与核心环节实现4.1 一个真实项目的改造记录我拿自己之前做的一个小项目练手是一个任务管理面板大概有十几个组件。原来的代码是让agent生成的功能没问题但UI确实有点AI味。我把impeccable接进去走了一遍完整流程。第一步初始化配置。我根据项目原来的设计稿把间距刻度设成了[4, 8, 12, 16, 24, 32, 48]字号刻度设成了[12, 14, 16, 20, 24, 32]颜色色板用了项目里实际在用的五个颜色。第二步跑dry-run。报告出来之后我数了一下大概有87处违规。其中最多的是间距问题有52处字号问题有21处颜色问题有14处。第三步分析违规。我发现间距问题里大部分是margin: 10px、padding: 6px这种中间值。这些值不在刻度上但也不是完全离谱。字号问题里主要是font-size: 15px和font-size: 22px这种。颜色问题里有几个是agent自己加的强调色不在我的色板里。第四步决定修正策略。间距和字号的违规我开了autoFix让impeccable自动改成最接近的刻度值。颜色的违规我手动处理因为有些强调色其实是有意加的我不想让工具一刀切。第五步跑fix。自动修正了73处剩下14处颜色问题我手动改了。改完之后再跑一次check报告干净了。第六步用浏览器扩展验证。打开页面扩展显示没有违规。我又手动看了几个关键页面确认视觉效果确实比之前整齐了。最明显的变化是间距变得有节奏了之前那种这里紧那里松的感觉没了。4.2 参数调优的实际经验上面那个项目跑完之后我总结了几条参数调优的经验。间距容差不要设0。我一开始设的0结果报告里全是15px不在刻度上这种。但实际上15px和16px在视觉上几乎没区别没必要改。后来设成2报告清爽多了。字号容差可以设1。字号对视觉的影响比间距大所以容差可以小一点。但也不要设0因为有些浏览器的默认字号计算会有小数设0会误报。颜色autoFix慎用。颜色这东西自动修正的风险比较大。它可能把你一个有意为之的品牌色改成色板里的某个近似色结果品牌感就没了。我建议颜色只检查不自动修人工确认。扫描路径要精确。我一开始的include写的是src/**/*结果它把图片、字体文件也扫了报了一堆无关的错。后来改成只扫.css、.tsx、.jsx就正常了。忽略文件要维护。项目里总有些文件是不需要检查的比如第三方组件的覆盖样式、打印样式表。把这些加到.impeccablerc里能减少很多噪音。4.3 与Codex CLI和Zcode CLI的配合热词里提到了Codex CLI和Zcode CLI这两个都是AI编码代理的命令行工具。impeccable跟它们的配合方式我试下来是这样的。Codex CLI的特点是它会在你的项目里直接改文件改完之后你可以跑impeccable check看看它改得怎么样。我一般的工作流是让Codex CLI生成或修改组件然后跑impeccable check --fix然后再让Codex CLI review一遍修正后的代码确认没有逻辑问题。Zcode CLI我用得少一些但逻辑类似。它的输出可能更偏向于代码片段而不是直接改文件所以你需要先把片段贴到项目里再跑impeccable。注意不要让impeccable和AI agent同时修改同一个文件。我有一次让agent在改组件同时跑了impeccable fix结果两边冲突文件里出现了重复的样式声明。后来我养成了习惯agent改完我确认保存了再跑impeccable。4.4 在CI/CD里跑impeccable如果你想让团队里所有人提交的代码都过一遍impeccable可以把它加到CI流程里。我自己的做法是在GitHub Actions里加一个step- name: Run impeccable check run: | npm install -g impeccable-cli impeccable check --ci--ci模式的特点是它不会自动修正只会检查并在有违规时返回非零退出码让CI失败。这样你就能在PR阶段拦住那些不符合规则的代码。但这里有个坑如果你的项目是多人协作且大家的编辑器配置不一样可能会出现我本地跑没问题CI上跑就报错的情况。原因是不同编辑器对CSS的格式化方式不同比如有的会把margin: 0 16px格式化成margin: 0 16px有的会格式化成margin: 0 16px看起来一样但可能有不可见字符差异。我的解决办法是在项目里加一个.editorconfig统一缩进和换行符然后在CI里先跑一遍格式化再跑impeccable。5. 常见问题与排查技巧实录5.1 常见问题速查表问题现象可能原因排查方法解决方案报告里全是违规数量离谱扫描路径太宽扫了node_modules或dist检查config里的include和exclude精确include路径exclude掉不需要的目录自动修正后页面样式乱了autoFix把有意为之的值也改了对比修正前后的diff关掉autoFix或把特定文件加到忽略列表浏览器扩展不显示违规页面不在localhost或扩展没权限检查扩展设置里的域名列表添加localhost或手动添加开发域名CI上报错但本地没问题编辑器格式化差异对比本地和CI的格式化结果加.editorconfigCI里先格式化再检查颜色检查误报太多色板配置和实际用的不一致导出项目里实际用的颜色列表更新config里的palette字号检查漏报字号写在CSS变量里工具没解析检查是否有CSS变量或Sass变量在config里配置变量映射或手动检查修正后代码格式变了autoFix重写了样式声明看diff里的格式变化配合Prettier使用先格式化再修正5.2 几个我踩过的坑坑一Tailwind项目里的任意值。Tailwind支持mt-[13px]这种任意值写法。impeccable默认能识别这种写法但如果你用的是旧版本可能识别不了。我遇到过一次报告里没报但实际页面上间距就是不对。后来升级了版本就好了。如果你用Tailwind建议确认一下impeccable的版本是否支持任意值语法。坑二CSS-in-JS的动态值。如果你的项目用styled-components或emotion样式值是动态计算的比如margin: ${props props.spacing}px。impeccable对这种动态值基本无能为力因为它不知道运行时props.spacing是多少。我的做法是把动态值限制在刻度范围内比如在组件层面做校验而不是依赖impeccable。坑三响应式断点里的值。媒体查询里的样式值impeccable默认也会检查。但有时候你在移动端用了一个不在刻度上的值是因为那个断点下的视觉效果需要微调。这种情况我建议在config里给媒体查询单独设一套容差或者把那个文件加到忽略列表。坑四第三方组件的样式覆盖。你项目里可能引用了某个UI库然后你写了一些覆盖样式。这些覆盖样式里的值可能不在你的刻度上但你是为了对齐第三方组件的默认样式。这种情况我建议把这些覆盖样式单独放在一个文件里然后把这个文件加到.impeccablerc的忽略列表。坑五颜色对比度检查的误报。impeccable的颜色对比度检查是基于WCAG标准的但有时候你的设计就是用了低对比度的颜色比如灰色文字在浅灰背景上这是有意为之的视觉风格。这种情况你可以把contrastMin调低或者把特定选择器加到白名单里。5.3 独家避坑技巧技巧一先跑dry-run再跑fix。这个我说过但值得再强调。dry-run能让你看到所有违规你可以先判断哪些该修哪些不该修。直接跑fix的风险是它可能改了你不想改的东西而你没有备份的话就麻烦了。技巧二用git branch隔离修正。在跑impeccable fix之前先开一个新分支。这样如果修正结果不理想你可以直接丢弃分支不会影响主分支。我一般会开一个style/impeccable-fix这样的分支修完之后review diff确认没问题再merge。技巧三把impeccable的规则同步到设计文档。如果你团队里有设计文档或者设计系统文档把impeccable的刻度值同步过去。这样设计师和开发者用的是同一套标准减少沟通成本。我见过太多团队是设计师给一套值开发者用另一套值最后UI对不上。技巧四定期review忽略列表。.impeccablerc里的忽略项会随着项目演进而变化。有些文件可能一开始需要忽略后来重构了就不需要了。我一般每个月review一次忽略列表把不再需要的项删掉保持检查覆盖率。技巧五用impeccable的输出作为code review的辅助。在PR里贴一份impeccable的检查报告能让reviewer快速了解这个PR在样式层面有没有问题。这比让reviewer逐行看CSS要高效得多。6. 我对这个项目的一些个人看法用了这段时间我对impeccable的定位有了更清晰的认识。它不是一个让AI生成完美UI的银弹它更像是一个质量底线工具。它保证你的UI不会差到离谱但不会让你的UI变得惊艳。惊艳的部分还是得靠人。我觉得它最大的价值在于把审美这件事部分量化了。以前你跟AI说间距要好看AI不知道什么叫好看。现在你告诉它间距必须是4的倍数它就能理解。这种量化虽然粗糙但比没有强。另一个我觉得有意思的点是它其实在倒逼你先定义自己的设计系统。你要用impeccable就得先想清楚你的间距刻度是什么、字号刻度是什么、色板是什么。这个过程本身就是一次设计系统的梳理。我那个小项目在配置impeccable的过程中顺便把设计系统也整理了一遍算是意外收获。当然它也有局限。它管不了布局逻辑、管不了交互状态、管不了响应式策略。这些还是得靠人或者更高级的AI能力。但至少在样式值这个层面上它把AI生成结果的下限拉高了不少。如果你也在用AI coding agent写前端我建议你试试把impeccable接进去。不用一开始就追求完美配置先跑起来看看报告慢慢调。调着调着你对什么是好的前端样式的理解也会更清晰。这个附带收益可能比工具本身更有价值。
1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个项目名我脑子里蹦出来的第一反应是——这词儿选得挺有意思。impeccable无瑕疵的、无可挑剔的。放在前端设计和AI编码代理的语境里它其实是在喊一个很实在的口号让AI写出来的前端代码看起来不那么AI味。你如果用过任何AI coding agent帮你生成过页面应该懂我在说什么。它们能跑功能也对但就是透着一股说不清道不明的塑料感——间距要么太紧要么太松颜色搭配像是从2015年的Bootstrap模板里扒出来的圆角、阴影、字体层级全都差那么一口气。代码能交差但离impeccable还差着十万八千里。这个项目瞄准的就是这个痛点。它不是一个从零开始的前端框架也不是又一个组件库。它更像是一套约束层或者说审美规则引擎夹在你的AI编码代理和最终输出之间把那些能跑但难看的结果往能看且耐看的方向拽。核心关键词里出现的CLI、browser extension、AI coding agents基本勾勒出了它的形态一个可以通过命令行调用的工具同时提供浏览器扩展来辅助验证和调试最终服务于AI编码代理的前端产出质量。适合谁看三类人。第一类是把AI coding agent当日常生产力工具的前端开发者你已经在用Codex CLI、Zcode CLI这类工具写代码了但每次生成完UI都得手动调半天。第二类是技术负责人或者团队里的审美把关人你需要一套可复用的规则让团队里所有人用AI生成的界面保持统一水准。第三类是对前端设计有追求但不想每次都从设计系统开始搭的独立开发者你希望AI帮你干活的同时产出能直接见人。我花了大概两周时间把这个项目的核心逻辑摸了一遍也在自己的几个小项目里试了试。下面把我理解的东西拆开讲包括它为什么这么设计、怎么用、踩了哪些坑。2. 核心设计思路拆解为什么是约束而不是生成2.1 AI编码代理在前端场景下的真实短板要理解impeccable的设计逻辑得先搞清楚AI coding agent在前端这件事上到底差在哪。我自己的观察是问题不在能不能写出来而在写出来之后像不像人写的。大语言模型在生成前端代码时有一个很明显的倾向它会优先保证功能正确性和语法正确性然后才考虑视觉呈现。这导致几个典型症状。第一间距系统缺失。模型会随手写margin: 13px或者padding: 0.7rem这种没有规律的值因为它只是在填一个看起来合理的数而不是在遵循一套间距刻度。第二颜色选择随意。除非你在prompt里明确给了色板否则模型倾向于用#333、#666、#f5f5f5这种安全但平庸的颜色偶尔还会蹦出饱和度极高的蓝色或红色。第三层级关系模糊。标题和正文的字号差距不够字重变化不明显导致页面看起来平。这些问题单独看都不致命但叠加在一起就是那种一眼AI的观感。impeccable的思路不是让AI重新学一遍设计而是在输出之后加一层规则化的修正和约束把那些偏离审美基准的值拉回来。2.2 为什么选择CLI加浏览器扩展的组合形态这个项目的形态选择挺讲究的。CLI负责的是批量化、可脚本化的修正浏览器扩展负责的是实时化、可视化的验证。两者分工明确。CLI的定位是嵌入到你的开发流程里。你可以在AI agent生成完代码之后跑一条命令让它扫描你的CSS或者Tailwind类名把不符合规则的间距、颜色、字号标记出来甚至直接自动修正。这种生成-扫描-修正的流水线适合在CI/CD里跑也适合在本地开发时作为pre-commit钩子。浏览器扩展的定位则更偏向调试和验证。你在浏览器里打开页面扩展会实时高亮那些违规的元素告诉你哪个间距不在刻度上、哪个颜色对比度不够、哪个字号跳级了。这种即时反馈对于调UI特别有用因为你不用反复跑CLI再刷新页面。我一开始觉得浏览器扩展有点多余后来发现它解决了一个很实际的问题AI生成的代码你未必会逐行看。很多时候你让agent改一个组件它顺手把旁边的样式也动了你不一定注意到。扩展能帮你把这些顺手改动里的问题揪出来。2.3 规则引擎的核心刻度化与容差机制impeccable最核心的设计我认为是它的刻度化思维加容差机制。这两个词听起来有点抽象我用实际例子解释。刻度化就是说它不要求你的间距必须是某个精确值而是要求你的间距必须落在某个刻度上。比如它定义了一套间距刻度4px、8px、12px、16px、24px、32px、48px、64px。你写margin: 15px它会告诉你这不在刻度上最接近的是16px。你写padding: 1.1rem换算下来是17.6px也不在刻度上建议改成16px或24px。容差机制则是说它不会因为1px的偏差就报错。比如你写margin: 15px如果容差设的是2px那它可能就放过了因为15离16只差1px。但如果容差设的是0那它就会标记出来。这个容差是可以配置的取决于你对impeccable的定义有多严格。这套机制的好处是它给了AI生成结果一个可量化的审美基准。你不需要跟AI解释间距要好看你只需要告诉它间距必须落在这些值上然后让impeccable去检查。这比在prompt里写一堆形容词有效得多。3. 核心细节解析与实操要点3.1 安装与初始化从零到能跑impeccable的安装方式取决于你用的是哪个包管理器。我自己的环境是Node.js 18以上用npm装的。命令大概是这样的npm install -g impeccable-cli装完之后在你的项目根目录跑初始化impeccable init这个命令会做几件事。第一在项目根目录生成一个impeccable.config.json文件里面是默认的规则配置。第二如果你项目里有package.json它会尝试检测你用的CSS方案纯CSS、Sass、Tailwind、CSS-in-JS等然后调整配置里的扫描路径。第三它会生成一个.impeccablerc的忽略文件类似.gitignore用来排除不需要检查的目录。注意如果你用的是monorepo初始化的时候最好在具体的子包目录里跑而不是在根目录。我试过在根目录跑结果它把node_modules里的东西也扫了一遍慢得离谱。初始化完之后你可以先跑一次dry-run看看效果impeccable check --dry-run这个命令不会修改任何文件只会输出一份报告告诉你哪些地方不符合规则。我第一次跑的时候报告里密密麻麻全是警告因为默认配置的容差设得很小。后来我把容差调大了一点才变得可用。3.2 配置文件详解每个参数背后的意图impeccable.config.json的结构不算复杂但每个字段都值得说清楚。我挑几个最关键的讲。{ spacing: { scale: [4, 8, 12, 16, 24, 32, 48, 64], tolerance: 2, autoFix: true }, typography: { scale: [12, 14, 16, 18, 20, 24, 30, 36, 48], tolerance: 1, lineHeightRatio: 1.5 }, color: { palette: [#1a1a1a, #4a4a4a, #8a8a8a, #e0e0e0, #ffffff], contrastMin: 4.5, autoFix: false }, scan: { include: [src/**/*.css, src/**/*.tsx, src/**/*.jsx], exclude: [node_modules, dist, *.test.*] } }spacing.scale就是间距刻度我建议根据你项目的设计系统来定。如果你用的是Tailwind默认配置那刻度就是[0, 2, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64]。如果你有自己的设计系统就按你的来。spacing.tolerance是容差单位是px。设成2意味着偏差在2px以内就不报错。我一般设2因为设计稿和实际实现之间总有点误差设0会太吵。spacing.autoFix控制是否自动修正。我建议初期设成false先看看报告确认规则合理了再开自动修正。不然它可能把你一些有意为之的间距也改了。typography.lineHeightRatio是行高比例默认1.5。这个值影响的是正文的行高检查。如果你项目里正文行高是1.6或1.7记得改这个值不然会误报。color.contrastMin是最小对比度默认4.5这是WCAG AA标准。如果你做的是无障碍要求更高的项目可以调到7。但要注意调高之后很多浅色文字都会被标记你得有心理准备。3.3 浏览器扩展的安装与使用浏览器扩展的安装方式取决于你用的浏览器。我是在Chrome里装的从项目的release页面下载crx文件然后拖到扩展管理页面。装完之后你打开任何本地开发服务器上的页面扩展图标会亮起来。点开扩展你会看到一个侧边栏里面列出了当前页面上所有违规的元素。每条违规会告诉你元素选择器、违规类型间距/字号/颜色、当前值、建议值。你可以点击某条违规页面上对应的元素会高亮。提示扩展默认只检查本地开发服务器localhost上的页面。如果你想检查线上页面需要在扩展设置里手动添加域名。但我不建议这么做因为线上页面的样式可能经过了压缩和合并检查结果会不准。扩展还有一个实时模式开启之后你在DevTools里改样式扩展会实时告诉你改后的值是否符合规则。这个功能在手动调UI的时候特别好用相当于有个设计系统警察站在你旁边。3.4 与AI编码代理的集成方式impeccable跟AI coding agent的集成我试过两种方式。第一种是后置修正。你让agent生成完代码然后跑impeccable fix让它自动修正。这种方式简单直接但有个问题agent可能生成了一些结构上的问题比如用了不该用的标签、嵌套层级太深这些impeccable管不了。它只管样式层面的规则。第二种是前置约束。你把impeccable的规则导出成一份简短的说明塞到agent的system prompt或者项目级的instructions文件里。比如本项目遵循以下样式规则 - 间距必须使用以下值之一4, 8, 12, 16, 24, 32, 48, 64 (px) - 字号必须使用以下值之一12, 14, 16, 18, 20, 24, 30, 36, 48 (px) - 颜色必须使用项目色板中的值 - 正文行高为字号的1.5倍这种方式的好处是agent在生成的时候就会尽量遵守规则减少后置修正的工作量。但缺点是agent不一定每次都记得住尤其是对话轮次多了之后。我自己的做法是两者结合在prompt里给规则生成完再跑一次check有问题的手动修或者让agent再改一轮。这样下来最终产出的质量比我之前纯靠agent生成要好不少。4. 实操过程与核心环节实现4.1 一个真实项目的改造记录我拿自己之前做的一个小项目练手是一个任务管理面板大概有十几个组件。原来的代码是让agent生成的功能没问题但UI确实有点AI味。我把impeccable接进去走了一遍完整流程。第一步初始化配置。我根据项目原来的设计稿把间距刻度设成了[4, 8, 12, 16, 24, 32, 48]字号刻度设成了[12, 14, 16, 20, 24, 32]颜色色板用了项目里实际在用的五个颜色。第二步跑dry-run。报告出来之后我数了一下大概有87处违规。其中最多的是间距问题有52处字号问题有21处颜色问题有14处。第三步分析违规。我发现间距问题里大部分是margin: 10px、padding: 6px这种中间值。这些值不在刻度上但也不是完全离谱。字号问题里主要是font-size: 15px和font-size: 22px这种。颜色问题里有几个是agent自己加的强调色不在我的色板里。第四步决定修正策略。间距和字号的违规我开了autoFix让impeccable自动改成最接近的刻度值。颜色的违规我手动处理因为有些强调色其实是有意加的我不想让工具一刀切。第五步跑fix。自动修正了73处剩下14处颜色问题我手动改了。改完之后再跑一次check报告干净了。第六步用浏览器扩展验证。打开页面扩展显示没有违规。我又手动看了几个关键页面确认视觉效果确实比之前整齐了。最明显的变化是间距变得有节奏了之前那种这里紧那里松的感觉没了。4.2 参数调优的实际经验上面那个项目跑完之后我总结了几条参数调优的经验。间距容差不要设0。我一开始设的0结果报告里全是15px不在刻度上这种。但实际上15px和16px在视觉上几乎没区别没必要改。后来设成2报告清爽多了。字号容差可以设1。字号对视觉的影响比间距大所以容差可以小一点。但也不要设0因为有些浏览器的默认字号计算会有小数设0会误报。颜色autoFix慎用。颜色这东西自动修正的风险比较大。它可能把你一个有意为之的品牌色改成色板里的某个近似色结果品牌感就没了。我建议颜色只检查不自动修人工确认。扫描路径要精确。我一开始的include写的是src/**/*结果它把图片、字体文件也扫了报了一堆无关的错。后来改成只扫.css、.tsx、.jsx就正常了。忽略文件要维护。项目里总有些文件是不需要检查的比如第三方组件的覆盖样式、打印样式表。把这些加到.impeccablerc里能减少很多噪音。4.3 与Codex CLI和Zcode CLI的配合热词里提到了Codex CLI和Zcode CLI这两个都是AI编码代理的命令行工具。impeccable跟它们的配合方式我试下来是这样的。Codex CLI的特点是它会在你的项目里直接改文件改完之后你可以跑impeccable check看看它改得怎么样。我一般的工作流是让Codex CLI生成或修改组件然后跑impeccable check --fix然后再让Codex CLI review一遍修正后的代码确认没有逻辑问题。Zcode CLI我用得少一些但逻辑类似。它的输出可能更偏向于代码片段而不是直接改文件所以你需要先把片段贴到项目里再跑impeccable。注意不要让impeccable和AI agent同时修改同一个文件。我有一次让agent在改组件同时跑了impeccable fix结果两边冲突文件里出现了重复的样式声明。后来我养成了习惯agent改完我确认保存了再跑impeccable。4.4 在CI/CD里跑impeccable如果你想让团队里所有人提交的代码都过一遍impeccable可以把它加到CI流程里。我自己的做法是在GitHub Actions里加一个step- name: Run impeccable check run: | npm install -g impeccable-cli impeccable check --ci--ci模式的特点是它不会自动修正只会检查并在有违规时返回非零退出码让CI失败。这样你就能在PR阶段拦住那些不符合规则的代码。但这里有个坑如果你的项目是多人协作且大家的编辑器配置不一样可能会出现我本地跑没问题CI上跑就报错的情况。原因是不同编辑器对CSS的格式化方式不同比如有的会把margin: 0 16px格式化成margin: 0 16px有的会格式化成margin: 0 16px看起来一样但可能有不可见字符差异。我的解决办法是在项目里加一个.editorconfig统一缩进和换行符然后在CI里先跑一遍格式化再跑impeccable。5. 常见问题与排查技巧实录5.1 常见问题速查表问题现象可能原因排查方法解决方案报告里全是违规数量离谱扫描路径太宽扫了node_modules或dist检查config里的include和exclude精确include路径exclude掉不需要的目录自动修正后页面样式乱了autoFix把有意为之的值也改了对比修正前后的diff关掉autoFix或把特定文件加到忽略列表浏览器扩展不显示违规页面不在localhost或扩展没权限检查扩展设置里的域名列表添加localhost或手动添加开发域名CI上报错但本地没问题编辑器格式化差异对比本地和CI的格式化结果加.editorconfigCI里先格式化再检查颜色检查误报太多色板配置和实际用的不一致导出项目里实际用的颜色列表更新config里的palette字号检查漏报字号写在CSS变量里工具没解析检查是否有CSS变量或Sass变量在config里配置变量映射或手动检查修正后代码格式变了autoFix重写了样式声明看diff里的格式变化配合Prettier使用先格式化再修正5.2 几个我踩过的坑坑一Tailwind项目里的任意值。Tailwind支持mt-[13px]这种任意值写法。impeccable默认能识别这种写法但如果你用的是旧版本可能识别不了。我遇到过一次报告里没报但实际页面上间距就是不对。后来升级了版本就好了。如果你用Tailwind建议确认一下impeccable的版本是否支持任意值语法。坑二CSS-in-JS的动态值。如果你的项目用styled-components或emotion样式值是动态计算的比如margin: ${props props.spacing}px。impeccable对这种动态值基本无能为力因为它不知道运行时props.spacing是多少。我的做法是把动态值限制在刻度范围内比如在组件层面做校验而不是依赖impeccable。坑三响应式断点里的值。媒体查询里的样式值impeccable默认也会检查。但有时候你在移动端用了一个不在刻度上的值是因为那个断点下的视觉效果需要微调。这种情况我建议在config里给媒体查询单独设一套容差或者把那个文件加到忽略列表。坑四第三方组件的样式覆盖。你项目里可能引用了某个UI库然后你写了一些覆盖样式。这些覆盖样式里的值可能不在你的刻度上但你是为了对齐第三方组件的默认样式。这种情况我建议把这些覆盖样式单独放在一个文件里然后把这个文件加到.impeccablerc的忽略列表。坑五颜色对比度检查的误报。impeccable的颜色对比度检查是基于WCAG标准的但有时候你的设计就是用了低对比度的颜色比如灰色文字在浅灰背景上这是有意为之的视觉风格。这种情况你可以把contrastMin调低或者把特定选择器加到白名单里。5.3 独家避坑技巧技巧一先跑dry-run再跑fix。这个我说过但值得再强调。dry-run能让你看到所有违规你可以先判断哪些该修哪些不该修。直接跑fix的风险是它可能改了你不想改的东西而你没有备份的话就麻烦了。技巧二用git branch隔离修正。在跑impeccable fix之前先开一个新分支。这样如果修正结果不理想你可以直接丢弃分支不会影响主分支。我一般会开一个style/impeccable-fix这样的分支修完之后review diff确认没问题再merge。技巧三把impeccable的规则同步到设计文档。如果你团队里有设计文档或者设计系统文档把impeccable的刻度值同步过去。这样设计师和开发者用的是同一套标准减少沟通成本。我见过太多团队是设计师给一套值开发者用另一套值最后UI对不上。技巧四定期review忽略列表。.impeccablerc里的忽略项会随着项目演进而变化。有些文件可能一开始需要忽略后来重构了就不需要了。我一般每个月review一次忽略列表把不再需要的项删掉保持检查覆盖率。技巧五用impeccable的输出作为code review的辅助。在PR里贴一份impeccable的检查报告能让reviewer快速了解这个PR在样式层面有没有问题。这比让reviewer逐行看CSS要高效得多。6. 我对这个项目的一些个人看法用了这段时间我对impeccable的定位有了更清晰的认识。它不是一个让AI生成完美UI的银弹它更像是一个质量底线工具。它保证你的UI不会差到离谱但不会让你的UI变得惊艳。惊艳的部分还是得靠人。我觉得它最大的价值在于把审美这件事部分量化了。以前你跟AI说间距要好看AI不知道什么叫好看。现在你告诉它间距必须是4的倍数它就能理解。这种量化虽然粗糙但比没有强。另一个我觉得有意思的点是它其实在倒逼你先定义自己的设计系统。你要用impeccable就得先想清楚你的间距刻度是什么、字号刻度是什么、色板是什么。这个过程本身就是一次设计系统的梳理。我那个小项目在配置impeccable的过程中顺便把设计系统也整理了一遍算是意外收获。当然它也有局限。它管不了布局逻辑、管不了交互状态、管不了响应式策略。这些还是得靠人或者更高级的AI能力。但至少在样式值这个层面上它把AI生成结果的下限拉高了不少。如果你也在用AI coding agent写前端我建议你试试把impeccable接进去。不用一开始就追求完美配置先跑起来看看报告慢慢调。调着调着你对什么是好的前端样式的理解也会更清晰。这个附带收益可能比工具本身更有价值。
