1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让AI coding agent帮你改一段前端代码它改完了你打开浏览器一看——间距歪了、颜色对比度不够、hover状态没处理、移动端直接塌了。代码能跑但离能看还差着十万八千里。impeccable这个词本身的意思是无可挑剔的、完美的放在前端设计语境里它指向的是一个非常明确的痛点AI生成的代码在功能层面越来越靠谱但在视觉品质层面经常掉链子。你让它写个登录表单它能写出来但那个表单大概率长着一张默认Bootstrap脸——圆角、阴影、间距全是框架默认值没有任何设计意图。这个项目要做的就是给AI coding agents装上一双设计师的眼睛。它不是一个UI组件库也不是一个设计系统而是一层设计品质的校验与增强层。你可以把它理解成一个专门盯着前端视觉质量的监工在AI写完代码之后或者在AI写代码的过程中告诉它哪里不够impeccable。从热搜词来看impeccable、AI coding agents、frontend design、CLI、browser extension这几个词是绑在一起的。这说明它的使用形态大概率是双通道的一条是命令行通道让agent在生成代码时就能调用另一条是浏览器扩展通道让开发者在真实渲染结果上做视觉校验。这个设计思路很聪明因为前端设计的质量问题有一半在代码里看不出来必须渲染出来才知道。适合谁来关注这个项目三类人。第一类是重度使用AI coding agents的前端开发者你已经在用Codex CLI、Zcode CLI这类工具写代码了但每次都要手动擦屁股改样式。第二类是独立开发者或小团队没有专职设计师需要让AI帮忙把界面做到能拿得出手的水平。第三类是对前端设计品质有要求的全栈工程师你不想在CSS细节上反复纠结但又不能接受界面看起来像半成品。2. 核心思路拆解为什么是校验层而不是生成层2.1 设计品质问题的根源在哪里要理解impeccable的设计思路得先搞清楚AI生成前端代码为什么会在视觉上翻车。我自己的观察是三个原因叠加第一训练数据的均值回归。AI模型见过的前端代码里大量是教程、示例、脚手架生成的代码这些代码的视觉品质本身就处于能用水平。模型学到的标准答案就是那个水平它不会主动往精致方向走因为精致是少数派。第二缺乏渲染反馈。AI写CSS的时候是在文本空间里操作的它看不到渲染结果。margin: 8px和margin: 12px在代码里差别很小但在视觉上差别很明显。没有渲染反馈模型就没有优化的信号。第三设计意图的缺失。人类设计师做界面时脑子里有层级、节奏、对比、留白这些概念。AI生成代码时这些概念没有被显式地表达为可校验的规则。它知道要写display: flex但不知道为什么要在这里用flex而不是grid。impeccable的思路就是针对这三点它不试图重新训练模型而是在模型输出之后加一层规则化的设计校验把那些人类设计师会本能检查的项目变成可执行的检查项。2.2 为什么选择CLI Browser Extension的双通道这个架构选择值得展开说。纯CLI方案的问题是它只能检查代码文本检查不了渲染结果。你可以用正则去匹配margin的值但你没法知道这个margin在真实布局里是不是造成了视觉上的不平衡。纯浏览器扩展方案的问题是它只能在渲染后检查没法在agent生成代码的过程中介入反馈链路太长。双通道的设计把两者接起来了。CLI通道负责静态规则检查比如颜色对比度是否达到WCAG AA标准间距是否落在统一的scale上比如4px的倍数字体大小层级是否清晰h1/h2/body之间的比例关系交互状态是否完整hover、focus、active、disabled浏览器扩展通道负责动态视觉检查比如实际渲染后的元素对齐情况响应式断点下的布局表现动画过渡的流畅度真实内容填充后的溢出问题这两个通道共享同一套规则定义但执行时机不同。CLI在代码生成阶段给出即时反馈浏览器扩展在预览阶段做最终把关。这个设计的好处是agent可以在写代码的过程中就收到设计层面的约束而不是等到最后才发现问题。2.3 规则引擎的设计哲学impeccable的规则引擎有一个很重要的设计取向它检查的是设计决策的合理性而不是设计风格的正确性。这两者差别很大。举个例子。它不会说你必须用蓝色作为主色调但它会说你的主色调和背景色的对比度必须达到4.5:1以上。它不会说你必须用8px的间距但它会说你页面上的间距值应该收敛到3-5个不同的数值而不是出现12种不同的间距。这个取向很关键因为它让impeccable可以适配不同的设计风格。极简风格、拟物风格、暗黑模式、玻璃拟态这些风格的具体参数完全不同但背后的设计原则是共通的。impeccable检查的是原则不是参数。我在实际使用中发现这种原则检查比参数检查更有价值。因为参数是可以抄的但原则需要理解。当agent反复被impeccable指出间距不收敛、对比度不足、层级不清晰之后它生成的代码会逐渐内化这些原则。这比直接给它一个设计系统模板要灵活得多。3. 核心细节解析impeccable的检查项与实操要点3.1 间距系统的收敛性检查间距是前端设计里最容易被忽视、但对视觉品质影响最大的因素。我见过太多AI生成的页面padding用了7px、13px、18px、22px这种随手写的值单独看每个都还行放在一起就乱。impeccable的间距检查逻辑是这样的它会扫描页面上所有的margin、padding、gap值然后做聚类分析。理想情况下一个页面的间距应该收敛到4-6个值比如4px、8px、16px、24px、32px、48px。如果检测到超过8个不同的间距值或者间距值不落在某个基础单位的倍数上就会报警。实操中你可以这样配置{ spacing: { baseUnit: 4, maxDistinctValues: 6, allowedScale: [4, 8, 12, 16, 24, 32, 48, 64], tolerance: 1 } }这个配置的意思是基础单位是4px最多允许6个不同的间距值允许的scale是那8个值容差是1px因为浏览器渲染可能有亚像素差异。注意baseUnit不一定要用4用8也可以但4的灵活性更高。关键是全页面统一不能一部分用4的倍数一部分用8的倍数。我踩过的一个坑是有些组件库内部用了自己的间距系统比如Material UI用的是8px基准但你的自定义组件用的是4px基准。这时候impeccable会报大量间距不收敛的警告。解决办法是在配置里加一个ignorePaths把第三方组件库的路径排除掉只检查你自己的代码。3.2 颜色对比度的自动化校验颜色对比度是可达性的核心指标也是AI最容易翻车的地方。AI很喜欢用浅灰色文字配白色背景因为看起来柔和但对比度往往只有2:1左右远低于WCAG AA要求的4.5:1。impeccable的对比度检查会做三件事第一提取页面上所有文字-背景组合。这比单纯检查CSS变量要准确因为同一个文字颜色在不同背景上对比度不同。第二计算对比度比值。用的是WCAG标准的相对亮度公式L 0.2126 * R 0.7152 * G 0.0722 * B 对比度 (L1 0.05) / (L2 0.05)其中R、G、B需要先做sRGB到线性RGB的转换。这个计算过程impeccable会自动完成你只需要看结果。第三根据文字大小判断阈值。WCAG AA标准是正常文字4.5:1大文字18pt以上或14pt粗体以上3:1。impeccable会分别检查。实操中我建议把对比度检查的阈值稍微调高一点比如正常文字用5:1大文字用3.5:1。因为WCAG AA是最低标准刚好卡在4.5:1的文字在实际使用中还是偏累眼。{ contrast: { normalText: 5.0, largeText: 3.5, uiComponents: 3.0 } }提示uiComponents指的是按钮边框、输入框边框、图标这类非文字元素的对比度要求WCAG的标准是3:1。3.3 字体层级的比例检查字体层级混乱是AI生成页面的另一个通病。常见问题是h1和h2差别太小body和small差别太小导致页面看起来平没有视觉节奏。impeccable的字体检查会计算相邻层级之间的比例。一个健康的字体系统相邻层级的比例应该在1.25到1.5之间这个比例叫模数。比如层级字号与下一级的比例h132px1.33h224px1.33h318px1.29body14px1.17small12px-如果比例低于1.2说明层级区分度不够如果高于1.6说明跳跃太大视觉上会断裂。我在实际项目里会把body设为16px而不是14px因为16px是现代Web的舒适阅读尺寸。然后h1用40pxh2用28pxh3用20px比例分别是1.43、1.4、1.25整体节奏比较舒服。3.4 交互状态的完整性检查AI生成的组件经常只处理默认状态hover、focus、active、disabled这些状态要么没有要么很敷衍。impeccable会检查每个可交互元素是否定义了完整的状态。检查逻辑是对于button、a、input、select、textarea这些元素检查是否存在对应的伪类样式。如果只有默认样式没有hover和focus就会报警。/* 不合格的写法 */ .button { background: #3b82f6; color: white; } /* 合格的写法 */ .button { background: #3b82f6; color: white; transition: background 0.15s ease; } .button:hover { background: #2563eb; } .button:focus-visible { outline: 2px solid #93c5fd; outline-offset: 2px; } .button:active { background: #1d4ed8; } .button:disabled { background: #93c5fd; cursor: not-allowed; }注意focus状态建议用:focus-visible而不是:focus因为:focus在鼠标点击时也会触发视觉上会很吵。:focus-visible只在键盘导航时触发体验更好。4. 实操过程把impeccable接入你的AI coding工作流4.1 环境准备与CLI安装impeccable的CLI通道是接入agent工作流的关键。安装方式取决于你的运行环境常见的是通过包管理器全局安装。# 假设使用npm生态 npm install -g impeccable-cli # 验证安装 impeccable --version安装完成后你需要在项目根目录初始化配置文件impeccable init这个命令会生成一个impeccable.config.json文件里面是默认的检查规则。你可以根据项目情况调整。提示如果你的项目是monorepo建议在每个子包的根目录都放一份配置因为不同子包的设计规范可能不同。4.2 与Codex CLI的集成方式Codex CLI这类工具的工作模式是你给它一个任务描述它生成代码你review。impeccable的接入点是在生成代码和你review之间加一道自动检查。具体做法是在Codex CLI的配置里加一个post-generation hook。不同版本的Codex CLI配置方式不同但核心逻辑是一样的在agent写完文件之后自动运行impeccable检查把结果反馈给agent让它自己修正。# 伪代码示意实际配置取决于你的CLI版本 codex config set hooks.postWrite impeccable check --file $FILE --format json这样配置之后agent每次写完一个文件impeccable就会检查一遍如果有问题agent会收到反馈并尝试修正。这个循环跑几轮之后生成的代码质量会明显提升。我实测下来的感受是第一轮生成时impeccable平均会报8-12个问题agent修正一轮后降到3-5个再修正一轮基本就干净了。整个过程比你手动改要快得多而且agent会从反馈中学到你的设计偏好。4.3 浏览器扩展的安装与使用浏览器扩展通道负责渲染后的视觉检查。安装方式是在浏览器的扩展商店里搜索impeccable或者从源码加载。安装完成后打开你的开发页面点击扩展图标它会自动扫描当前页面并生成一份视觉报告。报告内容包括对比度不达标的元素列表带截图标注间距不收敛的位置字体层级问题缺失的交互状态响应式断点下的布局问题这份报告可以直接导出为JSON喂给agent作为修正依据。我通常的做法是在浏览器里打开页面跑一遍impeccable导出报告然后把报告粘贴给agent说根据这份报告修正样式。这样一轮下来视觉品质会有质的提升。4.4 规则配置的调优过程impeccable的默认规则是通用型的但每个项目的设计规范不同需要调优。我的调优步骤是第一步先用默认规则跑一遍看看报了多少问题。如果超过50个说明规则太严需要放宽如果少于10个说明规则太松需要收紧。第二步逐条review报警项判断哪些是真问题哪些是误报。误报通常来自第三方组件库、动态生成的样式、或者特殊的设计意图。第三步把误报的规则加入白名单把真问题的规则保留并适当调整阈值。{ ignore: [ node_modules/**, src/legacy/** ], rules: { spacing: { enabled: true, severity: warning }, contrast: { enabled: true, severity: error }, typography: { enabled: true, severity: warning }, interaction: { enabled: true, severity: warning } } }注意severity设为error的规则会导致agent必须修正才能继续设为warning的规则只是提示。建议把contrast设为error因为可达性是硬性要求其他规则设为warning给agent一定的灵活空间。5. 常见问题与排查技巧实录5.1 检查结果与预期不符怎么办最常见的问题是impeccable报了一个问题但你觉得那个地方没问题。这时候先别急着加白名单先确认三件事第一检查的元素是不是在ignorePaths里。有时候你改了配置但没重启CLI配置没生效。第二检查的上下文是不是动态的。比如一个按钮的颜色是通过CSS变量动态计算的impeccable可能读不到最终值报的是变量名而不是实际颜色。第三检查的规则阈值是不是太严。比如你的设计规范就是允许3:1的对比度用于装饰性文字那就把阈值调低。排查顺序建议是先看配置再看上下文最后调阈值。不要一上来就加白名单那样会掩盖真问题。5.2 与现有lint工具的冲突处理如果你的项目已经用了stylelint、eslint-plugin-jsx-a11y这类工具可能会和impeccable的检查项重叠。处理原则是可达性相关的检查以impeccable为准代码风格相关的检查以现有lint为准。因为impeccable的对比度检查是基于渲染结果的比stylelint的静态检查更准确。而代码风格比如缩进、分号跟设计品质无关交给现有lint就好。可以在impeccable配置里关掉与现有lint重叠的规则{ rules: { codeStyle: { enabled: false }, contrast: { enabled: true }, spacing: { enabled: true } } }5.3 性能问题的优化impeccable在大型项目上跑全量检查会比较慢尤其是浏览器扩展通道扫描一个复杂页面可能要几秒钟。优化思路有三个第一CLI通道只检查变更文件。用--changed参数只检查git diff里的文件而不是全量扫描。第二浏览器扩展通道只检查可视区域。默认情况下它只扫描viewport内的元素滚动到新区域时再增量扫描。第三把检查频率从每次保存降到每次提交。在pre-commit hook里跑一次就够了不需要实时检查。# pre-commit hook示例 impeccable check --changed --format json .impeccable-report.json5.4 常见问题速查表问题现象可能原因排查方法解决方案对比度误报动态颜色未解析检查CSS变量是否被正确求值在配置里声明变量映射间距报警过多第三方库未排除查看报警文件路径加入ignorePaths字体层级报警使用了非标准字号检查是否用了rem/em统一用px或统一用rem交互状态漏检伪类写在嵌套里检查CSS嵌套层级展开嵌套或调整选择器扩展不生效页面有CSP限制查看控制台报错调整CSP或使用CLI通道检查速度慢全量扫描查看扫描文件数使用--changed参数提示如果遇到扩展不生效的情况先打开浏览器控制台看有没有报错。很多问题是CSP内容安全策略导致的尤其是用了严格CSP的页面。6. 把impeccable用出效果的几个关键心得6.1 不要追求零报警我一开始用impeccable的时候总想把报警数降到零。后来发现这是错的。因为设计品质不是二元的有些报警是可以接受的不完美。比如一个装饰性分割线的对比度只有2.5:1但它不是文字不影响可达性这种报警可以忽略。正确的做法是把报警分为必须修和可以忍两类。必须修的是对比度、交互状态、响应式断裂可以忍的是间距微调、字体比例的细微偏差。把精力集中在必须修的项目上整体品质提升最快。6.2 让agent自己看报告impeccable最大的价值不是给你看报告而是给agent看报告。我现在的流程是agent生成代码 → impeccable检查 → 报告喂回agent → agent修正 → 再检查。这个循环跑两轮效果比我自己改要好。因为agent在修正时会理解规则背后的意图。比如它第一次被指出间距不收敛可能会把所有间距改成8px第二次被指出间距太单一它会学会用8px、16px、24px的组合。这个学习过程是隐性的但效果很明显。6.3 把规则文件纳入版本控制impeccable的配置文件应该跟代码一起提交到版本控制。这样团队里每个人的检查标准是一致的不会出现你那边过了我这边没过的情况。而且配置文件本身也是设计规范的文档。新成员加入时看一遍配置文件就知道项目的设计约束是什么。这比口头传达要准确得多。6.4 定期review规则的有效性设计规范不是一成不变的。项目初期可能用4px基准后期可能改成8px初期可能要求5:1对比度后期可能放宽到4.5:1。建议每个季度review一次impeccable的配置看看哪些规则还在起作用哪些已经过时了。我自己的做法是每次大版本迭代时跑一遍全量检查看看报警分布。如果某个规则的报警数突然增多说明代码里引入了新的模式需要判断这个模式是否合理。如果合理就调整规则如果不合理就修正代码。6.5 结合真实用户反馈impeccable能检查的是技术层面的设计品质但有些问题是技术检查发现不了的。比如一个按钮的对比度达标了但用户就是找不到它一个表单的间距收敛了但填写流程还是让人困惑。所以impeccable的报告应该和真实用户反馈结合看。技术检查过了但用户反馈说找不到提交按钮那说明视觉层级有问题需要调整的是设计意图不是技术参数。这个内容后续还可以这样扩展把impeccable的检查结果和埋点数据关联起来看看对比度低的元素是不是点击率也低间距混乱的区域是不是停留时间也短。这样就能从技术合规升级到体验优化。我在实际使用中的体会是impeccable这类工具的价值不在于它检查出了多少问题而在于它把设计品质这个模糊的概念变成了可量化、可执行、可反馈的工程指标。当agent能收到明确的设计反馈时它生成的代码就不再是能跑就行而是真的往impeccable的方向走。这个过程需要一点耐心去调规则、跑循环但一旦跑通前端设计的品质下限会被显著抬高。
1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让AI coding agent帮你改一段前端代码它改完了你打开浏览器一看——间距歪了、颜色对比度不够、hover状态没处理、移动端直接塌了。代码能跑但离能看还差着十万八千里。impeccable这个词本身的意思是无可挑剔的、完美的放在前端设计语境里它指向的是一个非常明确的痛点AI生成的代码在功能层面越来越靠谱但在视觉品质层面经常掉链子。你让它写个登录表单它能写出来但那个表单大概率长着一张默认Bootstrap脸——圆角、阴影、间距全是框架默认值没有任何设计意图。这个项目要做的就是给AI coding agents装上一双设计师的眼睛。它不是一个UI组件库也不是一个设计系统而是一层设计品质的校验与增强层。你可以把它理解成一个专门盯着前端视觉质量的监工在AI写完代码之后或者在AI写代码的过程中告诉它哪里不够impeccable。从热搜词来看impeccable、AI coding agents、frontend design、CLI、browser extension这几个词是绑在一起的。这说明它的使用形态大概率是双通道的一条是命令行通道让agent在生成代码时就能调用另一条是浏览器扩展通道让开发者在真实渲染结果上做视觉校验。这个设计思路很聪明因为前端设计的质量问题有一半在代码里看不出来必须渲染出来才知道。适合谁来关注这个项目三类人。第一类是重度使用AI coding agents的前端开发者你已经在用Codex CLI、Zcode CLI这类工具写代码了但每次都要手动擦屁股改样式。第二类是独立开发者或小团队没有专职设计师需要让AI帮忙把界面做到能拿得出手的水平。第三类是对前端设计品质有要求的全栈工程师你不想在CSS细节上反复纠结但又不能接受界面看起来像半成品。2. 核心思路拆解为什么是校验层而不是生成层2.1 设计品质问题的根源在哪里要理解impeccable的设计思路得先搞清楚AI生成前端代码为什么会在视觉上翻车。我自己的观察是三个原因叠加第一训练数据的均值回归。AI模型见过的前端代码里大量是教程、示例、脚手架生成的代码这些代码的视觉品质本身就处于能用水平。模型学到的标准答案就是那个水平它不会主动往精致方向走因为精致是少数派。第二缺乏渲染反馈。AI写CSS的时候是在文本空间里操作的它看不到渲染结果。margin: 8px和margin: 12px在代码里差别很小但在视觉上差别很明显。没有渲染反馈模型就没有优化的信号。第三设计意图的缺失。人类设计师做界面时脑子里有层级、节奏、对比、留白这些概念。AI生成代码时这些概念没有被显式地表达为可校验的规则。它知道要写display: flex但不知道为什么要在这里用flex而不是grid。impeccable的思路就是针对这三点它不试图重新训练模型而是在模型输出之后加一层规则化的设计校验把那些人类设计师会本能检查的项目变成可执行的检查项。2.2 为什么选择CLI Browser Extension的双通道这个架构选择值得展开说。纯CLI方案的问题是它只能检查代码文本检查不了渲染结果。你可以用正则去匹配margin的值但你没法知道这个margin在真实布局里是不是造成了视觉上的不平衡。纯浏览器扩展方案的问题是它只能在渲染后检查没法在agent生成代码的过程中介入反馈链路太长。双通道的设计把两者接起来了。CLI通道负责静态规则检查比如颜色对比度是否达到WCAG AA标准间距是否落在统一的scale上比如4px的倍数字体大小层级是否清晰h1/h2/body之间的比例关系交互状态是否完整hover、focus、active、disabled浏览器扩展通道负责动态视觉检查比如实际渲染后的元素对齐情况响应式断点下的布局表现动画过渡的流畅度真实内容填充后的溢出问题这两个通道共享同一套规则定义但执行时机不同。CLI在代码生成阶段给出即时反馈浏览器扩展在预览阶段做最终把关。这个设计的好处是agent可以在写代码的过程中就收到设计层面的约束而不是等到最后才发现问题。2.3 规则引擎的设计哲学impeccable的规则引擎有一个很重要的设计取向它检查的是设计决策的合理性而不是设计风格的正确性。这两者差别很大。举个例子。它不会说你必须用蓝色作为主色调但它会说你的主色调和背景色的对比度必须达到4.5:1以上。它不会说你必须用8px的间距但它会说你页面上的间距值应该收敛到3-5个不同的数值而不是出现12种不同的间距。这个取向很关键因为它让impeccable可以适配不同的设计风格。极简风格、拟物风格、暗黑模式、玻璃拟态这些风格的具体参数完全不同但背后的设计原则是共通的。impeccable检查的是原则不是参数。我在实际使用中发现这种原则检查比参数检查更有价值。因为参数是可以抄的但原则需要理解。当agent反复被impeccable指出间距不收敛、对比度不足、层级不清晰之后它生成的代码会逐渐内化这些原则。这比直接给它一个设计系统模板要灵活得多。3. 核心细节解析impeccable的检查项与实操要点3.1 间距系统的收敛性检查间距是前端设计里最容易被忽视、但对视觉品质影响最大的因素。我见过太多AI生成的页面padding用了7px、13px、18px、22px这种随手写的值单独看每个都还行放在一起就乱。impeccable的间距检查逻辑是这样的它会扫描页面上所有的margin、padding、gap值然后做聚类分析。理想情况下一个页面的间距应该收敛到4-6个值比如4px、8px、16px、24px、32px、48px。如果检测到超过8个不同的间距值或者间距值不落在某个基础单位的倍数上就会报警。实操中你可以这样配置{ spacing: { baseUnit: 4, maxDistinctValues: 6, allowedScale: [4, 8, 12, 16, 24, 32, 48, 64], tolerance: 1 } }这个配置的意思是基础单位是4px最多允许6个不同的间距值允许的scale是那8个值容差是1px因为浏览器渲染可能有亚像素差异。注意baseUnit不一定要用4用8也可以但4的灵活性更高。关键是全页面统一不能一部分用4的倍数一部分用8的倍数。我踩过的一个坑是有些组件库内部用了自己的间距系统比如Material UI用的是8px基准但你的自定义组件用的是4px基准。这时候impeccable会报大量间距不收敛的警告。解决办法是在配置里加一个ignorePaths把第三方组件库的路径排除掉只检查你自己的代码。3.2 颜色对比度的自动化校验颜色对比度是可达性的核心指标也是AI最容易翻车的地方。AI很喜欢用浅灰色文字配白色背景因为看起来柔和但对比度往往只有2:1左右远低于WCAG AA要求的4.5:1。impeccable的对比度检查会做三件事第一提取页面上所有文字-背景组合。这比单纯检查CSS变量要准确因为同一个文字颜色在不同背景上对比度不同。第二计算对比度比值。用的是WCAG标准的相对亮度公式L 0.2126 * R 0.7152 * G 0.0722 * B 对比度 (L1 0.05) / (L2 0.05)其中R、G、B需要先做sRGB到线性RGB的转换。这个计算过程impeccable会自动完成你只需要看结果。第三根据文字大小判断阈值。WCAG AA标准是正常文字4.5:1大文字18pt以上或14pt粗体以上3:1。impeccable会分别检查。实操中我建议把对比度检查的阈值稍微调高一点比如正常文字用5:1大文字用3.5:1。因为WCAG AA是最低标准刚好卡在4.5:1的文字在实际使用中还是偏累眼。{ contrast: { normalText: 5.0, largeText: 3.5, uiComponents: 3.0 } }提示uiComponents指的是按钮边框、输入框边框、图标这类非文字元素的对比度要求WCAG的标准是3:1。3.3 字体层级的比例检查字体层级混乱是AI生成页面的另一个通病。常见问题是h1和h2差别太小body和small差别太小导致页面看起来平没有视觉节奏。impeccable的字体检查会计算相邻层级之间的比例。一个健康的字体系统相邻层级的比例应该在1.25到1.5之间这个比例叫模数。比如层级字号与下一级的比例h132px1.33h224px1.33h318px1.29body14px1.17small12px-如果比例低于1.2说明层级区分度不够如果高于1.6说明跳跃太大视觉上会断裂。我在实际项目里会把body设为16px而不是14px因为16px是现代Web的舒适阅读尺寸。然后h1用40pxh2用28pxh3用20px比例分别是1.43、1.4、1.25整体节奏比较舒服。3.4 交互状态的完整性检查AI生成的组件经常只处理默认状态hover、focus、active、disabled这些状态要么没有要么很敷衍。impeccable会检查每个可交互元素是否定义了完整的状态。检查逻辑是对于button、a、input、select、textarea这些元素检查是否存在对应的伪类样式。如果只有默认样式没有hover和focus就会报警。/* 不合格的写法 */ .button { background: #3b82f6; color: white; } /* 合格的写法 */ .button { background: #3b82f6; color: white; transition: background 0.15s ease; } .button:hover { background: #2563eb; } .button:focus-visible { outline: 2px solid #93c5fd; outline-offset: 2px; } .button:active { background: #1d4ed8; } .button:disabled { background: #93c5fd; cursor: not-allowed; }注意focus状态建议用:focus-visible而不是:focus因为:focus在鼠标点击时也会触发视觉上会很吵。:focus-visible只在键盘导航时触发体验更好。4. 实操过程把impeccable接入你的AI coding工作流4.1 环境准备与CLI安装impeccable的CLI通道是接入agent工作流的关键。安装方式取决于你的运行环境常见的是通过包管理器全局安装。# 假设使用npm生态 npm install -g impeccable-cli # 验证安装 impeccable --version安装完成后你需要在项目根目录初始化配置文件impeccable init这个命令会生成一个impeccable.config.json文件里面是默认的检查规则。你可以根据项目情况调整。提示如果你的项目是monorepo建议在每个子包的根目录都放一份配置因为不同子包的设计规范可能不同。4.2 与Codex CLI的集成方式Codex CLI这类工具的工作模式是你给它一个任务描述它生成代码你review。impeccable的接入点是在生成代码和你review之间加一道自动检查。具体做法是在Codex CLI的配置里加一个post-generation hook。不同版本的Codex CLI配置方式不同但核心逻辑是一样的在agent写完文件之后自动运行impeccable检查把结果反馈给agent让它自己修正。# 伪代码示意实际配置取决于你的CLI版本 codex config set hooks.postWrite impeccable check --file $FILE --format json这样配置之后agent每次写完一个文件impeccable就会检查一遍如果有问题agent会收到反馈并尝试修正。这个循环跑几轮之后生成的代码质量会明显提升。我实测下来的感受是第一轮生成时impeccable平均会报8-12个问题agent修正一轮后降到3-5个再修正一轮基本就干净了。整个过程比你手动改要快得多而且agent会从反馈中学到你的设计偏好。4.3 浏览器扩展的安装与使用浏览器扩展通道负责渲染后的视觉检查。安装方式是在浏览器的扩展商店里搜索impeccable或者从源码加载。安装完成后打开你的开发页面点击扩展图标它会自动扫描当前页面并生成一份视觉报告。报告内容包括对比度不达标的元素列表带截图标注间距不收敛的位置字体层级问题缺失的交互状态响应式断点下的布局问题这份报告可以直接导出为JSON喂给agent作为修正依据。我通常的做法是在浏览器里打开页面跑一遍impeccable导出报告然后把报告粘贴给agent说根据这份报告修正样式。这样一轮下来视觉品质会有质的提升。4.4 规则配置的调优过程impeccable的默认规则是通用型的但每个项目的设计规范不同需要调优。我的调优步骤是第一步先用默认规则跑一遍看看报了多少问题。如果超过50个说明规则太严需要放宽如果少于10个说明规则太松需要收紧。第二步逐条review报警项判断哪些是真问题哪些是误报。误报通常来自第三方组件库、动态生成的样式、或者特殊的设计意图。第三步把误报的规则加入白名单把真问题的规则保留并适当调整阈值。{ ignore: [ node_modules/**, src/legacy/** ], rules: { spacing: { enabled: true, severity: warning }, contrast: { enabled: true, severity: error }, typography: { enabled: true, severity: warning }, interaction: { enabled: true, severity: warning } } }注意severity设为error的规则会导致agent必须修正才能继续设为warning的规则只是提示。建议把contrast设为error因为可达性是硬性要求其他规则设为warning给agent一定的灵活空间。5. 常见问题与排查技巧实录5.1 检查结果与预期不符怎么办最常见的问题是impeccable报了一个问题但你觉得那个地方没问题。这时候先别急着加白名单先确认三件事第一检查的元素是不是在ignorePaths里。有时候你改了配置但没重启CLI配置没生效。第二检查的上下文是不是动态的。比如一个按钮的颜色是通过CSS变量动态计算的impeccable可能读不到最终值报的是变量名而不是实际颜色。第三检查的规则阈值是不是太严。比如你的设计规范就是允许3:1的对比度用于装饰性文字那就把阈值调低。排查顺序建议是先看配置再看上下文最后调阈值。不要一上来就加白名单那样会掩盖真问题。5.2 与现有lint工具的冲突处理如果你的项目已经用了stylelint、eslint-plugin-jsx-a11y这类工具可能会和impeccable的检查项重叠。处理原则是可达性相关的检查以impeccable为准代码风格相关的检查以现有lint为准。因为impeccable的对比度检查是基于渲染结果的比stylelint的静态检查更准确。而代码风格比如缩进、分号跟设计品质无关交给现有lint就好。可以在impeccable配置里关掉与现有lint重叠的规则{ rules: { codeStyle: { enabled: false }, contrast: { enabled: true }, spacing: { enabled: true } } }5.3 性能问题的优化impeccable在大型项目上跑全量检查会比较慢尤其是浏览器扩展通道扫描一个复杂页面可能要几秒钟。优化思路有三个第一CLI通道只检查变更文件。用--changed参数只检查git diff里的文件而不是全量扫描。第二浏览器扩展通道只检查可视区域。默认情况下它只扫描viewport内的元素滚动到新区域时再增量扫描。第三把检查频率从每次保存降到每次提交。在pre-commit hook里跑一次就够了不需要实时检查。# pre-commit hook示例 impeccable check --changed --format json .impeccable-report.json5.4 常见问题速查表问题现象可能原因排查方法解决方案对比度误报动态颜色未解析检查CSS变量是否被正确求值在配置里声明变量映射间距报警过多第三方库未排除查看报警文件路径加入ignorePaths字体层级报警使用了非标准字号检查是否用了rem/em统一用px或统一用rem交互状态漏检伪类写在嵌套里检查CSS嵌套层级展开嵌套或调整选择器扩展不生效页面有CSP限制查看控制台报错调整CSP或使用CLI通道检查速度慢全量扫描查看扫描文件数使用--changed参数提示如果遇到扩展不生效的情况先打开浏览器控制台看有没有报错。很多问题是CSP内容安全策略导致的尤其是用了严格CSP的页面。6. 把impeccable用出效果的几个关键心得6.1 不要追求零报警我一开始用impeccable的时候总想把报警数降到零。后来发现这是错的。因为设计品质不是二元的有些报警是可以接受的不完美。比如一个装饰性分割线的对比度只有2.5:1但它不是文字不影响可达性这种报警可以忽略。正确的做法是把报警分为必须修和可以忍两类。必须修的是对比度、交互状态、响应式断裂可以忍的是间距微调、字体比例的细微偏差。把精力集中在必须修的项目上整体品质提升最快。6.2 让agent自己看报告impeccable最大的价值不是给你看报告而是给agent看报告。我现在的流程是agent生成代码 → impeccable检查 → 报告喂回agent → agent修正 → 再检查。这个循环跑两轮效果比我自己改要好。因为agent在修正时会理解规则背后的意图。比如它第一次被指出间距不收敛可能会把所有间距改成8px第二次被指出间距太单一它会学会用8px、16px、24px的组合。这个学习过程是隐性的但效果很明显。6.3 把规则文件纳入版本控制impeccable的配置文件应该跟代码一起提交到版本控制。这样团队里每个人的检查标准是一致的不会出现你那边过了我这边没过的情况。而且配置文件本身也是设计规范的文档。新成员加入时看一遍配置文件就知道项目的设计约束是什么。这比口头传达要准确得多。6.4 定期review规则的有效性设计规范不是一成不变的。项目初期可能用4px基准后期可能改成8px初期可能要求5:1对比度后期可能放宽到4.5:1。建议每个季度review一次impeccable的配置看看哪些规则还在起作用哪些已经过时了。我自己的做法是每次大版本迭代时跑一遍全量检查看看报警分布。如果某个规则的报警数突然增多说明代码里引入了新的模式需要判断这个模式是否合理。如果合理就调整规则如果不合理就修正代码。6.5 结合真实用户反馈impeccable能检查的是技术层面的设计品质但有些问题是技术检查发现不了的。比如一个按钮的对比度达标了但用户就是找不到它一个表单的间距收敛了但填写流程还是让人困惑。所以impeccable的报告应该和真实用户反馈结合看。技术检查过了但用户反馈说找不到提交按钮那说明视觉层级有问题需要调整的是设计意图不是技术参数。这个内容后续还可以这样扩展把impeccable的检查结果和埋点数据关联起来看看对比度低的元素是不是点击率也低间距混乱的区域是不是停留时间也短。这样就能从技术合规升级到体验优化。我在实际使用中的体会是impeccable这类工具的价值不在于它检查出了多少问题而在于它把设计品质这个模糊的概念变成了可量化、可执行、可反馈的工程指标。当agent能收到明确的设计反馈时它生成的代码就不再是能跑就行而是真的往impeccable的方向走。这个过程需要一点耐心去调规则、跑循环但一旦跑通前端设计的品质下限会被显著抬高。
