1. 从“impeccable”这个词说起它到底在解决什么问题第一次看到“impeccable”这个词是在一个前端开发者的讨论串里。有人发了一张截图左边是AI coding agent生成的页面右边是经过某个工具处理后的页面配文只有一句“这才是impeccable该有的样子。”我当时的第一反应是这又是什么新出的代码格式化工具点进去才发现它跟传统的Prettier、ESLint完全不是一回事。impeccable这个词本身的意思是“无可挑剔的、完美的”。放在前端设计和AI coding agent的语境下它指向的是一个非常具体的痛点AI生成的代码能跑但不好看。你让Codex CLI或者Zcode CLI帮你写一个登录页它确实能给你一个能用的表单但间距是随意的、颜色是默认的、字体是系统自带的、响应式断点是拍脑袋定的。代码逻辑没问题但视觉上就是“差点意思”。impeccable要做的就是在AI coding agent和最终交付的界面之间加一层“设计品控”。它不是替代AI写代码而是让AI写出来的代码在视觉层面达到一个可交付的标准。你可以把它理解成一个前端设计的自动化审查层——AI负责功能实现impeccable负责让实现出来的东西看起来像是经过设计师打磨过的。这个定位决定了它的使用场景你已经在用AI coding agent写前端代码了但你不想每次都要手动去调间距、改颜色、统一圆角、检查响应式。你希望有一个工具能自动帮你把这些“设计债务”清理掉。impeccable就是干这个的。从热词来看“impeccable 如何使用”和“cli”是搜索量最高的组合说明大部分人第一次接触它的时候最关心的是怎么把它跑起来。而“browser extension”和“two-factor authentication app”的出现则暗示了它的使用方式可能不止一种——既有命令行工具也有浏览器扩展甚至可能涉及到某种认证流程。这些我都会在后面逐一拆解。2. impeccable的三种入口CLI、浏览器扩展与认证流程2.1 为什么一个设计工具会有CLI和浏览器扩展两种形态这是很多人第一次接触impeccable时最困惑的地方。一个做前端设计品控的工具为什么既要提供命令行接口又要做浏览器扩展这不是重复造轮子吗实际上这两种形态对应的是完全不同的工作流。CLI面向的是批量处理和CI/CD集成的场景。比如你有一个用Codex CLI生成的项目里面有二十个页面组件你不可能一个个在浏览器里打开去检查。这时候你需要的是在终端里跑一条命令让它扫描整个项目目录把所有需要调整的设计问题列出来甚至直接自动修复。浏览器扩展面向的则是实时预览和交互式调整的场景。当你在浏览器里打开一个AI生成的页面扩展可以实时分析当前页面的设计问题给你一个可视化的报告告诉你哪些元素的间距不一致、哪些颜色对比度不够、哪些断点没有覆盖到。你可以在浏览器里直接看到修改前后的对比而不需要来回切换终端和编辑器。提示如果你主要用Codex CLI或Zcode CLI在终端里工作优先把CLI跑通如果你更多是在浏览器里调试AI生成的页面先装扩展。2.2 CLI的安装与初始化从零到第一次运行impeccable的CLI安装方式取决于你用的包管理器。根据目前社区里的实践最常见的路径是通过npm全局安装。如果你还没有Node.js环境需要先确保Node版本在18以上因为impeccable的CLI依赖了一些较新的ES模块特性。安装命令本身很简单npm install -g impeccable-cli但这里有一个容易被忽略的细节全局安装的位置。如果你用的是nvm管理Node版本全局安装的包会绑定到当前Node版本。当你切换Node版本后impeccable命令可能会找不到。我的建议是如果你经常切换Node版本考虑用npx impeccable-cli的方式运行或者把impeccable作为项目级的devDependency安装。安装完成后第一次运行impeccable init会在你的项目根目录生成一个配置文件默认叫.impeccablerc。这个文件是整个工具的核心它决定了impeccable用什么样的规则来审查你的前端代码。{ preset: default, rules: { spacing: { enabled: true, scale: 4px }, color: { enabled: true, contrast: AA }, typography: { enabled: true, scale: modular }, responsive: { enabled: true, breakpoints: [640, 768, 1024, 1280] } }, ignore: [node_modules/**, dist/**] }这个默认配置里spacing的scale设为4px意味着impeccable会检查所有间距值是否是4的倍数。这是前端设计里非常常见的一个约定因为4px的基准网格能让视觉节奏更统一。color的contrast设为AA对应的是WCAG无障碍标准里的AA级别对比度要求。typography的scale设为modular表示它会检查字号是否遵循模块化比例比如1.25或1.333的倍数。2.3 浏览器扩展的安装与认证流程浏览器扩展的安装路径通常是通过浏览器的扩展商店但impeccable的扩展在首次使用时需要完成一个认证流程。这就是热词里“enter the code from your two-factor authentication app or browser extension”出现的原因。这个认证流程的设计逻辑是impeccable的扩展需要读取你本地开发环境里的项目配置和代码为了确保只有你本人能访问这些数据它要求你通过两步验证来建立信任。具体操作是当你在扩展里登录后它会显示一个二维码或者一段密钥你需要用你的两步验证应用比如Google Authenticator或Authy扫描或输入然后扩展会要求你输入应用生成的六位动态码。注意这个认证只需要做一次之后扩展会记住你的设备。如果你在多个浏览器里使用每个浏览器都需要单独认证。认证完成后扩展会在你打开本地开发服务器通常是localhost的页面时自动激活。它会在页面右下角显示一个小面板列出当前页面的设计问题。你可以点击每个问题查看详情也可以一键应用修复建议。2.4 两种形态的协同工作方式CLI和浏览器扩展并不是孤立的。它们共享同一个.impeccablerc配置文件。你在CLI里调整的规则扩展会实时读取你在扩展里手动忽略的某个问题CLI下次运行时也会跳过。这种协同的一个典型场景是你先在浏览器里用扩展快速浏览几个核心页面把明显的问题手动修掉然后把剩下的、需要批量处理的问题交给CLI。CLI跑完后会生成一个报告文件你可以把这个报告提交到代码仓库里作为设计审查的记录。3. 核心机制拆解impeccable如何判断“设计有问题”3.1 间距审查4px网格背后的逻辑impeccable最核心的审查能力之一就是间距检查。它默认要求所有margin、padding、gap的值必须是4的倍数。这个规则的依据是什么在前端设计里4px基准网格4px baseline grid是一个被广泛采用的约定。它的逻辑是当所有间距都是4的倍数时元素之间的视觉节奏会自然对齐。比如8px、16px、24px、32px这些值在视觉上会形成一种“韵律感”。而如果你用了7px、13px、22px这样的值虽然单个看起来没问题但放在一起就会显得杂乱。impeccable的间距审查不仅仅是检查数值它还会检查间距的一致性。比如同一个页面里两个功能相似的卡片组件一个用了16px的内边距另一个用了20pximpeccable会标记出来。这种不一致在AI生成的代码里非常常见因为AI每次生成组件时可能用了不同的间距值。/* AI生成的代码间距值不统一 */ .card-a { padding: 16px; margin-bottom: 24px; } .card-b { padding: 20px; margin-bottom: 20px; } /* impeccable建议的统一版本 */ .card-a, .card-b { padding: 16px; margin-bottom: 24px; }3.2 颜色对比度不只是“好看”更是“可读”颜色审查是impeccable另一个核心功能。它默认按照WCAG AA标准检查文本和背景的对比度。AA标准要求普通文本的对比度至少达到4.5:1大号文本18px以上或14px粗体至少达到3:1。这个检查在AI生成的代码里特别有价值因为AI经常生成一些“看起来很美但读起来很累”的配色。比如浅灰色文字配白色背景视觉上很清爽但对比度可能只有2:1完全达不到可读性要求。impeccable在检查对比度时会计算前景色和背景色的相对亮度relative luminance然后套用WCAG的对比度公式。如果你对具体计算过程感兴趣公式是这样的// WCAG相对亮度计算 function luminance(r, g, b) { const [rs, gs, bs] [r, g, b].map(c { c c / 255; return c 0.03928 ? c / 12.92 : Math.pow((c 0.055) / 1.055, 2.4); }); return 0.2126 * rs 0.7152 * gs 0.0722 * bs; } // 对比度计算 function contrastRatio(l1, l2) { const lighter Math.max(l1, l2); const darker Math.min(l1, l2); return (lighter 0.05) / (darker 0.05); }impeccable会把这个计算过程自动化你不需要手动算。但它会在报告里告诉你具体的对比度数值以及建议的调整方向——是加深文字颜色还是调亮背景颜色。3.3 字体比例模块化缩放的实际应用字体审查是impeccable里相对“高级”的一个功能。它默认要求字号遵循模块化比例modular scale。模块化比例的意思是所有字号都是基于一个基准字号乘以一个固定比率得到的。比如基准字号是16px比率是1.25那么字号序列就是16px、20px、25px、31.25px、39.06px……以此类推。这个序列在视觉上会形成一种自然的层次感因为每个层级之间的跳跃幅度是一致的。AI生成的代码经常犯的错误是字号值是随意的14px、15px、17px、19px、22px。这些值单独看没问题但放在一起就没有层次感。impeccable会检测出这些“非模块化”的字号并建议替换成最接近的模块化值。原始字号问题impeccable建议14px不在1.25比例序列中12.8px或16px15px不在1.25比例序列中16px17px不在1.25比例序列中16px或20px19px不在1.25比例序列中20px22px不在1.25比例序列中20px或25px3.4 响应式断点AI最容易忽略的维度响应式审查是impeccable里最“重”的一个功能因为它需要模拟不同视口宽度下的渲染结果。impeccable默认的断点集合是640px、768px、1024px、1280px这四个断点覆盖了从手机到桌面的主要区间。AI生成的代码在响应式方面的问题通常有两类一是完全没有断点所有元素都用固定宽度二是断点值不统一有的组件在768px断点有的在800px断点导致页面在中间宽度下出现布局错乱。impeccable的响应式审查会做两件事首先它会检查所有媒体查询的断点值是否在配置的断点集合里其次它会模拟每个断点下的布局检测是否有元素溢出、重叠或不可见。提示如果你的项目有特定的断点需求比如针对某种设备可以在.impeccablerc里自定义breakpoints数组。但建议不要超过5个断点否则维护成本会很高。4. 和Codex CLI、Zcode CLI配合使用的实际工作流4.1 为什么要把impeccable放在AI coding agent之后Codex CLI和Zcode CLI这类工具的工作方式是你用自然语言描述需求它在终端里生成代码文件。这个流程非常高效但有一个天然的缺陷——AI没有“眼睛”。它不知道生成的页面在浏览器里看起来是什么样它只能根据训练数据里的模式来推断“什么样的代码看起来是对的”。这就导致了一个现象AI生成的代码在语法上无可挑剔在逻辑上也能跑通但在视觉上就是“不对劲”。间距忽大忽小、颜色搭配奇怪、字体层级混乱、响应式完全没考虑。这些问题如果靠人工一个个去调工作量不比手写代码小。impeccable的价值就在于它把“视觉审查”这一步自动化了。你不需要自己去盯着页面看impeccable会告诉你哪里有问题、为什么有问题、怎么改。4.2 一个完整的端到端流程假设你要用Codex CLI生成一个产品落地页。完整的流程是这样的第一步用Codex CLI生成基础代码。codex generate 创建一个产品落地页包含导航栏、英雄区域、三个功能卡片、一个定价表、一个页脚Codex CLI会在当前目录下生成一组HTML、CSS和JavaScript文件。这时候页面能跑但视觉上很粗糙。第二步运行impeccable的CLI审查。impeccable check ./srcimpeccable会扫描./src目录下的所有前端文件生成一份审查报告。报告会按文件分组列出每个文件里的设计问题。第三步查看报告并决定修复策略。报告的输出格式默认是表格包含以下列文件行号问题类型当前值建议值严重程度hero.css12spacing18px16px低hero.css24color#999 on #fff#666 on #fff高cards.css8typography17px16px中cards.css15responsive无断点添加768px断点高第四步自动修复低风险问题。impeccable fix ./src --severity low这个命令会自动修复所有“低”严重程度的问题比如间距值调整、字号微调。对于“高”严重程度的问题比如颜色对比度不足、响应式缺失impeccable会给出建议但不会自动修改因为这些修改可能影响设计意图需要人工确认。第五步在浏览器里用扩展做最终检查。打开本地开发服务器激活impeccable扩展逐个页面检查。扩展会实时显示当前页面的设计问题你可以直接在扩展面板里点击“应用”来修复。4.3 把impeccable集成到CI流程里如果你在一个团队里工作或者你的项目有持续集成流程可以把impeccable的检查作为CI的一个步骤。这样每次有人提交代码时CI会自动跑一遍设计审查如果发现严重问题就阻止合并。# .github/workflows/design-check.yml name: Design Check on: [pull_request] jobs: impeccable: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - run: npm install -g impeccable-cli - run: impeccable check ./src --severity high --exit-on-error这个配置的意思是在每次PR时跑impeccable检查如果发现“高”严重程度的问题就以非零状态码退出从而阻止PR合并。注意CI环境里没有浏览器所以响应式审查的模拟渲染可能不完整。建议在CI里只跑静态审查间距、颜色、字体响应式审查留给本地开发时做。5. 踩坑记录我在使用impeccable过程中遇到的五个问题5.1 认证流程卡住两步验证码总是提示错误第一次配置浏览器扩展时我卡在两步验证这一步很久。扩展显示了一个二维码我用Google Authenticator扫了输入生成的六位码但一直提示“验证码错误”。排查过程是这样的首先确认手机时间是否准确。两步验证的算法是基于时间同步的如果手机时间比服务器时间慢了超过30秒生成的码就会失效。我检查了一下手机时间是自动同步的没问题。然后我注意到一个细节扩展显示的二维码旁边有一行小字写着“如果扫码失败请手动输入密钥”。我重新扫码发现Google Authenticator里已经有一个同名条目了。原来是我之前扫过一次但没完成验证流程导致Authenticator里存了一个旧的密钥。删掉旧条目重新扫码这次就成功了。提示如果你在两步验证环节卡住先检查验证器应用里是否有重复的条目。有的话删掉重来。5.2 CLI在monorepo项目里找不到配置文件我的一个项目是monorepo结构前端代码在packages/web目录下但我在根目录运行impeccable check时它提示找不到.impeccablerc文件。原因是impeccable默认只在当前工作目录查找配置文件不会向上递归。解决办法有两个一是在根目录也放一份配置文件二是在命令里指定配置路径impeccable check ./packages/web --config ./packages/web/.impeccablerc我选择了第二种因为不同package可能有不同的设计规范。5.3 自动修复把有意的设计改掉了impeccable的自动修复功能很强大但有时候它会“过度修复”。比如我有一个卡片组件设计上就是要有20px的内边距比标准的16px大一点为了突出这个卡片但impeccable把它改成了16px。解决办法是在配置文件里加一个ignore规则针对特定文件或特定选择器跳过间距检查{ rules: { spacing: { enabled: true, scale: 4px, exceptions: [.featured-card, .hero-section] } } }5.4 响应式审查在动态内容上误报impeccable的响应式审查是基于静态渲染的。如果你的页面有动态加载的内容比如通过JavaScript异步加载的列表impeccable在审查时可能看不到这些内容导致误报“元素溢出”。我的处理方式是在审查前先确保页面处于“完整渲染”状态。对于用React或Vue的项目可以在审查前跑一次构建让所有动态内容都静态化。或者在配置文件里把动态内容的容器加入ignore列表。5.5 和现有ESLint/Prettier规则的冲突impeccable的某些规则和ESLint/Prettier有重叠。比如Prettier也会格式化CSS但它关注的是代码风格缩进、换行而impeccable关注的是设计值间距、颜色、字号。两者理论上不冲突但在实际运行中如果Prettier先跑把CSS格式改了impeccable可能会因为格式变化而重新计算某些值。我的建议是先跑impeccable再跑Prettier。在package.json的scripts里调整顺序{ scripts: { design-check: impeccable check ./src, format: prettier --write ./src, pre-commit: npm run design-check npm run format } }6. 进阶用法自定义规则与团队协作6.1 写一条自己的impeccable规则impeccable支持自定义规则。如果你团队有特定的设计规范比如“所有按钮的圆角必须是8px”你可以写一条自定义规则。自定义规则的格式是一个JavaScript模块导出一个对象包含name、check和fix三个字段module.exports { name: button-radius, check: (node) { if (node.selector.includes(button) node.styles.borderRadius ! 8px) { return { message: 按钮圆角应为8px当前为${node.styles.borderRadius}, severity: medium }; } return null; }, fix: (node) { node.styles.borderRadius 8px; return node; } };然后在.impeccablerc里引用这个规则{ customRules: [./rules/button-radius.js] }6.2 团队协作时的配置管理在团队里使用impeccable时.impeccablerc应该提交到代码仓库作为团队共享的设计规范。但每个人的本地环境可能不同所以需要一个“本地覆盖”机制。impeccable支持.impeccablerc.local文件这个文件不提交到仓库只在本机生效。你可以用它来覆盖一些个人偏好比如临时关闭某个规则{ rules: { typography: { enabled: false } } }6.3 把审查报告变成设计文档impeccable的审查报告可以导出为Markdown格式impeccable check ./src --format markdown --output design-report.md这个报告可以提交到仓库的docs/目录下作为设计审查的记录。每次审查后更新这个文件团队就能看到设计质量的变化趋势。审查日期高严重问题中严重问题低严重问题2025-01-101234562025-01-17828452025-01-2431530这种趋势表比单纯的“问题列表”更有说服力因为它展示了改进的过程。7. 我对impeccable的实际使用体会用了一段时间之后我最大的感受是impeccable解决的不是“设计好不好看”的问题而是“设计有没有系统性”的问题。AI生成的代码最大的毛病不是丑而是乱——间距没有规律、颜色没有体系、字号没有层次。impeccable把这些“乱”的地方找出来让你有机会去建立一套系统。另一个体会是impeccable的自动修复功能要慎用。我现在的习惯是先跑impeccable check看报告手动确认哪些问题需要修、哪些是有意为之然后再用impeccable fix批量处理确认过的问题。直接跑fix有时候会把一些有意的设计决策改掉。最后分享一个小技巧如果你在用Codex CLI生成代码可以在prompt里直接加上“生成的代码要能通过impeccable的默认审查”。这样AI在生成时就会尽量遵循4px网格、WCAG AA对比度和模块化字号后续的审查和修复工作量会小很多。我试过几次效果确实比不加这句话要好。
1. 从“impeccable”这个词说起它到底在解决什么问题第一次看到“impeccable”这个词是在一个前端开发者的讨论串里。有人发了一张截图左边是AI coding agent生成的页面右边是经过某个工具处理后的页面配文只有一句“这才是impeccable该有的样子。”我当时的第一反应是这又是什么新出的代码格式化工具点进去才发现它跟传统的Prettier、ESLint完全不是一回事。impeccable这个词本身的意思是“无可挑剔的、完美的”。放在前端设计和AI coding agent的语境下它指向的是一个非常具体的痛点AI生成的代码能跑但不好看。你让Codex CLI或者Zcode CLI帮你写一个登录页它确实能给你一个能用的表单但间距是随意的、颜色是默认的、字体是系统自带的、响应式断点是拍脑袋定的。代码逻辑没问题但视觉上就是“差点意思”。impeccable要做的就是在AI coding agent和最终交付的界面之间加一层“设计品控”。它不是替代AI写代码而是让AI写出来的代码在视觉层面达到一个可交付的标准。你可以把它理解成一个前端设计的自动化审查层——AI负责功能实现impeccable负责让实现出来的东西看起来像是经过设计师打磨过的。这个定位决定了它的使用场景你已经在用AI coding agent写前端代码了但你不想每次都要手动去调间距、改颜色、统一圆角、检查响应式。你希望有一个工具能自动帮你把这些“设计债务”清理掉。impeccable就是干这个的。从热词来看“impeccable 如何使用”和“cli”是搜索量最高的组合说明大部分人第一次接触它的时候最关心的是怎么把它跑起来。而“browser extension”和“two-factor authentication app”的出现则暗示了它的使用方式可能不止一种——既有命令行工具也有浏览器扩展甚至可能涉及到某种认证流程。这些我都会在后面逐一拆解。2. impeccable的三种入口CLI、浏览器扩展与认证流程2.1 为什么一个设计工具会有CLI和浏览器扩展两种形态这是很多人第一次接触impeccable时最困惑的地方。一个做前端设计品控的工具为什么既要提供命令行接口又要做浏览器扩展这不是重复造轮子吗实际上这两种形态对应的是完全不同的工作流。CLI面向的是批量处理和CI/CD集成的场景。比如你有一个用Codex CLI生成的项目里面有二十个页面组件你不可能一个个在浏览器里打开去检查。这时候你需要的是在终端里跑一条命令让它扫描整个项目目录把所有需要调整的设计问题列出来甚至直接自动修复。浏览器扩展面向的则是实时预览和交互式调整的场景。当你在浏览器里打开一个AI生成的页面扩展可以实时分析当前页面的设计问题给你一个可视化的报告告诉你哪些元素的间距不一致、哪些颜色对比度不够、哪些断点没有覆盖到。你可以在浏览器里直接看到修改前后的对比而不需要来回切换终端和编辑器。提示如果你主要用Codex CLI或Zcode CLI在终端里工作优先把CLI跑通如果你更多是在浏览器里调试AI生成的页面先装扩展。2.2 CLI的安装与初始化从零到第一次运行impeccable的CLI安装方式取决于你用的包管理器。根据目前社区里的实践最常见的路径是通过npm全局安装。如果你还没有Node.js环境需要先确保Node版本在18以上因为impeccable的CLI依赖了一些较新的ES模块特性。安装命令本身很简单npm install -g impeccable-cli但这里有一个容易被忽略的细节全局安装的位置。如果你用的是nvm管理Node版本全局安装的包会绑定到当前Node版本。当你切换Node版本后impeccable命令可能会找不到。我的建议是如果你经常切换Node版本考虑用npx impeccable-cli的方式运行或者把impeccable作为项目级的devDependency安装。安装完成后第一次运行impeccable init会在你的项目根目录生成一个配置文件默认叫.impeccablerc。这个文件是整个工具的核心它决定了impeccable用什么样的规则来审查你的前端代码。{ preset: default, rules: { spacing: { enabled: true, scale: 4px }, color: { enabled: true, contrast: AA }, typography: { enabled: true, scale: modular }, responsive: { enabled: true, breakpoints: [640, 768, 1024, 1280] } }, ignore: [node_modules/**, dist/**] }这个默认配置里spacing的scale设为4px意味着impeccable会检查所有间距值是否是4的倍数。这是前端设计里非常常见的一个约定因为4px的基准网格能让视觉节奏更统一。color的contrast设为AA对应的是WCAG无障碍标准里的AA级别对比度要求。typography的scale设为modular表示它会检查字号是否遵循模块化比例比如1.25或1.333的倍数。2.3 浏览器扩展的安装与认证流程浏览器扩展的安装路径通常是通过浏览器的扩展商店但impeccable的扩展在首次使用时需要完成一个认证流程。这就是热词里“enter the code from your two-factor authentication app or browser extension”出现的原因。这个认证流程的设计逻辑是impeccable的扩展需要读取你本地开发环境里的项目配置和代码为了确保只有你本人能访问这些数据它要求你通过两步验证来建立信任。具体操作是当你在扩展里登录后它会显示一个二维码或者一段密钥你需要用你的两步验证应用比如Google Authenticator或Authy扫描或输入然后扩展会要求你输入应用生成的六位动态码。注意这个认证只需要做一次之后扩展会记住你的设备。如果你在多个浏览器里使用每个浏览器都需要单独认证。认证完成后扩展会在你打开本地开发服务器通常是localhost的页面时自动激活。它会在页面右下角显示一个小面板列出当前页面的设计问题。你可以点击每个问题查看详情也可以一键应用修复建议。2.4 两种形态的协同工作方式CLI和浏览器扩展并不是孤立的。它们共享同一个.impeccablerc配置文件。你在CLI里调整的规则扩展会实时读取你在扩展里手动忽略的某个问题CLI下次运行时也会跳过。这种协同的一个典型场景是你先在浏览器里用扩展快速浏览几个核心页面把明显的问题手动修掉然后把剩下的、需要批量处理的问题交给CLI。CLI跑完后会生成一个报告文件你可以把这个报告提交到代码仓库里作为设计审查的记录。3. 核心机制拆解impeccable如何判断“设计有问题”3.1 间距审查4px网格背后的逻辑impeccable最核心的审查能力之一就是间距检查。它默认要求所有margin、padding、gap的值必须是4的倍数。这个规则的依据是什么在前端设计里4px基准网格4px baseline grid是一个被广泛采用的约定。它的逻辑是当所有间距都是4的倍数时元素之间的视觉节奏会自然对齐。比如8px、16px、24px、32px这些值在视觉上会形成一种“韵律感”。而如果你用了7px、13px、22px这样的值虽然单个看起来没问题但放在一起就会显得杂乱。impeccable的间距审查不仅仅是检查数值它还会检查间距的一致性。比如同一个页面里两个功能相似的卡片组件一个用了16px的内边距另一个用了20pximpeccable会标记出来。这种不一致在AI生成的代码里非常常见因为AI每次生成组件时可能用了不同的间距值。/* AI生成的代码间距值不统一 */ .card-a { padding: 16px; margin-bottom: 24px; } .card-b { padding: 20px; margin-bottom: 20px; } /* impeccable建议的统一版本 */ .card-a, .card-b { padding: 16px; margin-bottom: 24px; }3.2 颜色对比度不只是“好看”更是“可读”颜色审查是impeccable另一个核心功能。它默认按照WCAG AA标准检查文本和背景的对比度。AA标准要求普通文本的对比度至少达到4.5:1大号文本18px以上或14px粗体至少达到3:1。这个检查在AI生成的代码里特别有价值因为AI经常生成一些“看起来很美但读起来很累”的配色。比如浅灰色文字配白色背景视觉上很清爽但对比度可能只有2:1完全达不到可读性要求。impeccable在检查对比度时会计算前景色和背景色的相对亮度relative luminance然后套用WCAG的对比度公式。如果你对具体计算过程感兴趣公式是这样的// WCAG相对亮度计算 function luminance(r, g, b) { const [rs, gs, bs] [r, g, b].map(c { c c / 255; return c 0.03928 ? c / 12.92 : Math.pow((c 0.055) / 1.055, 2.4); }); return 0.2126 * rs 0.7152 * gs 0.0722 * bs; } // 对比度计算 function contrastRatio(l1, l2) { const lighter Math.max(l1, l2); const darker Math.min(l1, l2); return (lighter 0.05) / (darker 0.05); }impeccable会把这个计算过程自动化你不需要手动算。但它会在报告里告诉你具体的对比度数值以及建议的调整方向——是加深文字颜色还是调亮背景颜色。3.3 字体比例模块化缩放的实际应用字体审查是impeccable里相对“高级”的一个功能。它默认要求字号遵循模块化比例modular scale。模块化比例的意思是所有字号都是基于一个基准字号乘以一个固定比率得到的。比如基准字号是16px比率是1.25那么字号序列就是16px、20px、25px、31.25px、39.06px……以此类推。这个序列在视觉上会形成一种自然的层次感因为每个层级之间的跳跃幅度是一致的。AI生成的代码经常犯的错误是字号值是随意的14px、15px、17px、19px、22px。这些值单独看没问题但放在一起就没有层次感。impeccable会检测出这些“非模块化”的字号并建议替换成最接近的模块化值。原始字号问题impeccable建议14px不在1.25比例序列中12.8px或16px15px不在1.25比例序列中16px17px不在1.25比例序列中16px或20px19px不在1.25比例序列中20px22px不在1.25比例序列中20px或25px3.4 响应式断点AI最容易忽略的维度响应式审查是impeccable里最“重”的一个功能因为它需要模拟不同视口宽度下的渲染结果。impeccable默认的断点集合是640px、768px、1024px、1280px这四个断点覆盖了从手机到桌面的主要区间。AI生成的代码在响应式方面的问题通常有两类一是完全没有断点所有元素都用固定宽度二是断点值不统一有的组件在768px断点有的在800px断点导致页面在中间宽度下出现布局错乱。impeccable的响应式审查会做两件事首先它会检查所有媒体查询的断点值是否在配置的断点集合里其次它会模拟每个断点下的布局检测是否有元素溢出、重叠或不可见。提示如果你的项目有特定的断点需求比如针对某种设备可以在.impeccablerc里自定义breakpoints数组。但建议不要超过5个断点否则维护成本会很高。4. 和Codex CLI、Zcode CLI配合使用的实际工作流4.1 为什么要把impeccable放在AI coding agent之后Codex CLI和Zcode CLI这类工具的工作方式是你用自然语言描述需求它在终端里生成代码文件。这个流程非常高效但有一个天然的缺陷——AI没有“眼睛”。它不知道生成的页面在浏览器里看起来是什么样它只能根据训练数据里的模式来推断“什么样的代码看起来是对的”。这就导致了一个现象AI生成的代码在语法上无可挑剔在逻辑上也能跑通但在视觉上就是“不对劲”。间距忽大忽小、颜色搭配奇怪、字体层级混乱、响应式完全没考虑。这些问题如果靠人工一个个去调工作量不比手写代码小。impeccable的价值就在于它把“视觉审查”这一步自动化了。你不需要自己去盯着页面看impeccable会告诉你哪里有问题、为什么有问题、怎么改。4.2 一个完整的端到端流程假设你要用Codex CLI生成一个产品落地页。完整的流程是这样的第一步用Codex CLI生成基础代码。codex generate 创建一个产品落地页包含导航栏、英雄区域、三个功能卡片、一个定价表、一个页脚Codex CLI会在当前目录下生成一组HTML、CSS和JavaScript文件。这时候页面能跑但视觉上很粗糙。第二步运行impeccable的CLI审查。impeccable check ./srcimpeccable会扫描./src目录下的所有前端文件生成一份审查报告。报告会按文件分组列出每个文件里的设计问题。第三步查看报告并决定修复策略。报告的输出格式默认是表格包含以下列文件行号问题类型当前值建议值严重程度hero.css12spacing18px16px低hero.css24color#999 on #fff#666 on #fff高cards.css8typography17px16px中cards.css15responsive无断点添加768px断点高第四步自动修复低风险问题。impeccable fix ./src --severity low这个命令会自动修复所有“低”严重程度的问题比如间距值调整、字号微调。对于“高”严重程度的问题比如颜色对比度不足、响应式缺失impeccable会给出建议但不会自动修改因为这些修改可能影响设计意图需要人工确认。第五步在浏览器里用扩展做最终检查。打开本地开发服务器激活impeccable扩展逐个页面检查。扩展会实时显示当前页面的设计问题你可以直接在扩展面板里点击“应用”来修复。4.3 把impeccable集成到CI流程里如果你在一个团队里工作或者你的项目有持续集成流程可以把impeccable的检查作为CI的一个步骤。这样每次有人提交代码时CI会自动跑一遍设计审查如果发现严重问题就阻止合并。# .github/workflows/design-check.yml name: Design Check on: [pull_request] jobs: impeccable: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 with: node-version: 18 - run: npm install -g impeccable-cli - run: impeccable check ./src --severity high --exit-on-error这个配置的意思是在每次PR时跑impeccable检查如果发现“高”严重程度的问题就以非零状态码退出从而阻止PR合并。注意CI环境里没有浏览器所以响应式审查的模拟渲染可能不完整。建议在CI里只跑静态审查间距、颜色、字体响应式审查留给本地开发时做。5. 踩坑记录我在使用impeccable过程中遇到的五个问题5.1 认证流程卡住两步验证码总是提示错误第一次配置浏览器扩展时我卡在两步验证这一步很久。扩展显示了一个二维码我用Google Authenticator扫了输入生成的六位码但一直提示“验证码错误”。排查过程是这样的首先确认手机时间是否准确。两步验证的算法是基于时间同步的如果手机时间比服务器时间慢了超过30秒生成的码就会失效。我检查了一下手机时间是自动同步的没问题。然后我注意到一个细节扩展显示的二维码旁边有一行小字写着“如果扫码失败请手动输入密钥”。我重新扫码发现Google Authenticator里已经有一个同名条目了。原来是我之前扫过一次但没完成验证流程导致Authenticator里存了一个旧的密钥。删掉旧条目重新扫码这次就成功了。提示如果你在两步验证环节卡住先检查验证器应用里是否有重复的条目。有的话删掉重来。5.2 CLI在monorepo项目里找不到配置文件我的一个项目是monorepo结构前端代码在packages/web目录下但我在根目录运行impeccable check时它提示找不到.impeccablerc文件。原因是impeccable默认只在当前工作目录查找配置文件不会向上递归。解决办法有两个一是在根目录也放一份配置文件二是在命令里指定配置路径impeccable check ./packages/web --config ./packages/web/.impeccablerc我选择了第二种因为不同package可能有不同的设计规范。5.3 自动修复把有意的设计改掉了impeccable的自动修复功能很强大但有时候它会“过度修复”。比如我有一个卡片组件设计上就是要有20px的内边距比标准的16px大一点为了突出这个卡片但impeccable把它改成了16px。解决办法是在配置文件里加一个ignore规则针对特定文件或特定选择器跳过间距检查{ rules: { spacing: { enabled: true, scale: 4px, exceptions: [.featured-card, .hero-section] } } }5.4 响应式审查在动态内容上误报impeccable的响应式审查是基于静态渲染的。如果你的页面有动态加载的内容比如通过JavaScript异步加载的列表impeccable在审查时可能看不到这些内容导致误报“元素溢出”。我的处理方式是在审查前先确保页面处于“完整渲染”状态。对于用React或Vue的项目可以在审查前跑一次构建让所有动态内容都静态化。或者在配置文件里把动态内容的容器加入ignore列表。5.5 和现有ESLint/Prettier规则的冲突impeccable的某些规则和ESLint/Prettier有重叠。比如Prettier也会格式化CSS但它关注的是代码风格缩进、换行而impeccable关注的是设计值间距、颜色、字号。两者理论上不冲突但在实际运行中如果Prettier先跑把CSS格式改了impeccable可能会因为格式变化而重新计算某些值。我的建议是先跑impeccable再跑Prettier。在package.json的scripts里调整顺序{ scripts: { design-check: impeccable check ./src, format: prettier --write ./src, pre-commit: npm run design-check npm run format } }6. 进阶用法自定义规则与团队协作6.1 写一条自己的impeccable规则impeccable支持自定义规则。如果你团队有特定的设计规范比如“所有按钮的圆角必须是8px”你可以写一条自定义规则。自定义规则的格式是一个JavaScript模块导出一个对象包含name、check和fix三个字段module.exports { name: button-radius, check: (node) { if (node.selector.includes(button) node.styles.borderRadius ! 8px) { return { message: 按钮圆角应为8px当前为${node.styles.borderRadius}, severity: medium }; } return null; }, fix: (node) { node.styles.borderRadius 8px; return node; } };然后在.impeccablerc里引用这个规则{ customRules: [./rules/button-radius.js] }6.2 团队协作时的配置管理在团队里使用impeccable时.impeccablerc应该提交到代码仓库作为团队共享的设计规范。但每个人的本地环境可能不同所以需要一个“本地覆盖”机制。impeccable支持.impeccablerc.local文件这个文件不提交到仓库只在本机生效。你可以用它来覆盖一些个人偏好比如临时关闭某个规则{ rules: { typography: { enabled: false } } }6.3 把审查报告变成设计文档impeccable的审查报告可以导出为Markdown格式impeccable check ./src --format markdown --output design-report.md这个报告可以提交到仓库的docs/目录下作为设计审查的记录。每次审查后更新这个文件团队就能看到设计质量的变化趋势。审查日期高严重问题中严重问题低严重问题2025-01-101234562025-01-17828452025-01-2431530这种趋势表比单纯的“问题列表”更有说服力因为它展示了改进的过程。7. 我对impeccable的实际使用体会用了一段时间之后我最大的感受是impeccable解决的不是“设计好不好看”的问题而是“设计有没有系统性”的问题。AI生成的代码最大的毛病不是丑而是乱——间距没有规律、颜色没有体系、字号没有层次。impeccable把这些“乱”的地方找出来让你有机会去建立一套系统。另一个体会是impeccable的自动修复功能要慎用。我现在的习惯是先跑impeccable check看报告手动确认哪些问题需要修、哪些是有意为之然后再用impeccable fix批量处理确认过的问题。直接跑fix有时候会把一些有意的设计决策改掉。最后分享一个小技巧如果你在用Codex CLI生成代码可以在prompt里直接加上“生成的代码要能通过impeccable的默认审查”。这样AI在生成时就会尽量遵循4px网格、WCAG AA对比度和模块化字号后续的审查和修复工作量会小很多。我试过几次效果确实比不加这句话要好。
