1. 项目缘起为什么我们需要一个叫“impeccable”的东西第一次看到“impeccable”这个词是在一个前端群里有人甩了张截图说“这玩意儿生成的页面比我手写的还干净”。截图里是一个命令行工具的输出终端里几行命令跑完浏览器里就渲染出了一个布局规整、间距舒服、配色克制的落地页。当时群里有人问这是什么答曰impeccable。我后来花了不少时间研究这个东西。简单来说impeccable 是一个面向 AI coding agents 的前端设计约束层。它不是一个独立的代码生成器也不是一个 UI 框架而是一套通过 CLI 和浏览器扩展协同工作的工具链核心目标是让 AI 生成的代码在视觉层面达到“无可挑剔”的水准。你可能会问现在 AI 写代码已经很强了为什么还需要额外的东西来约束这个问题问得好。我自己用各种 AI coding agent 写过不少前端页面踩过的坑包括但不限于生成的 CSS 间距全是 magic number、颜色对比度不达标、响应式断点乱设、组件层级嵌套过深导致样式覆盖失控。AI 能把功能写出来但“好看”这件事它经常差一口气。impeccable 解决的正是这“一口气”的问题。它适合几类人一是经常用 AI 辅助写前端但总觉得差点意思的开发者二是想建立一套可复用的设计规范、让 AI 输出更稳定的团队三是对前端设计有追求、但不想每次都从零调样式的独立开发者。哪怕你是个前端新手只要你能跑命令行、能装浏览器扩展就能用起来。2. 核心机制拆解impeccable 到底在做什么2.1 设计约束的“翻译层”逻辑要理解 impeccable 的价值得先理解一个核心矛盾AI coding agent 擅长的是“从意图到代码”的映射但它对“设计系统”的理解是碎片化的。你告诉它“做一个卡片组件”它会给你一个卡片但这个卡片的圆角是 6px 还是 8px、阴影是0 2px 4px还是0 4px 8px、内边距是 16px 还是 20px它每次都可能不一样。impeccable 的做法是在 AI 和最终代码之间插入一个设计约束层。这个层通过 CLI 定义了一套设计 token 和规则然后浏览器扩展负责在预览环境中实时校验 AI 生成的代码是否符合这些规则。如果不符合它会给出具体的修正建议甚至直接注入修正后的样式。这个思路的巧妙之处在于它没有试图重新训练 AI 或者写一个更复杂的 prompt而是把“设计规范”这件事从 prompt 里抽出来变成一个独立的、可版本控制的、可被工具链消费的实体。你可以把它理解成 ESLint 之于 JavaScript只不过它管的是视觉层面的东西。2.2 CLI 与浏览器扩展的分工impeccable 的 CLI 和浏览器扩展是两条腿走路各管一摊。CLI 负责的是定义和分发。你在项目根目录下创建一个配置文件里面声明你的设计 token——颜色、字体、间距、圆角、阴影、断点等等。然后通过impeccable init初始化impeccable sync把这些 token 同步到你的项目里生成对应的 CSS 变量或者 Tailwind 配置。CLI 还负责和 AI coding agent 的集成比如你可以在 Codex CLI 或者 Claude Code 里直接调用 impeccable 的命令让 AI 在生成代码时自动引用这些 token。浏览器扩展负责的是校验和反馈。你在浏览器里打开 AI 生成的页面扩展会自动扫描 DOM检查实际渲染的样式是否符合 CLI 定义的设计 token。如果发现偏差比如某个按钮的圆角用了 5px 而你的 token 里定义的是 6px扩展会在页面上高亮标注并在控制台输出详细的报告。这个反馈回路非常短你改完代码刷新页面就能看到结果。注意浏览器扩展目前主要支持 Chromium 内核的浏览器Firefox 版本还在开发中。如果你用的是 Safari暂时只能靠 CLI 的静态检查。2.3 为什么不是直接写 prompt有人可能会想我直接在 prompt 里把设计规范写清楚不就行了我试过效果不稳定。原因有几个一是 prompt 长度有限你把所有 token 写进去留给业务逻辑的空间就少了二是 AI 对 prompt 里的数字不敏感你写“圆角用 8px”它可能给你生成border-radius: 0.5rem虽然数值一样但你的设计系统里可能要求统一用 px三是 prompt 没法版本控制你改了设计规范之前的 prompt 就失效了。impeccable 把这些规范从 prompt 里抽出来变成配置文件好处是显而易见的规范可以进 Git可以 review可以复用AI 每次生成代码时通过 CLI 读取最新的配置保证一致性。这就像你把 ESLint 规则写在.eslintrc里而不是每次写代码前跟同事口头说一遍。3. 从零上手impeccable 的完整实操流程3.1 环境准备与 CLI 安装impeccable 的 CLI 是基于 Node.js 的所以第一步是确保你的机器上有 Node 环境。我实测下来Node 18 及以上版本都能跑推荐用 20 LTS。node -v npm -v如果版本没问题直接全局安装npm install -g impeccable-cli安装完成后运行impeccable --version确认一下。如果提示命令找不到检查一下 npm 的全局 bin 目录是否在 PATH 里。Windows 用户可能会遇到这个问题解决办法是在系统环境变量里把%APPDATA%\npm加进去。接下来在你的项目根目录下初始化cd your-project impeccable init这个命令会问你几个问题项目类型React、Vue、原生 HTML 等、是否使用 Tailwind、设计 token 的来源新建还是导入现有的。根据你的实际情况选就行。我一般选“新建”然后手动调整生成的配置文件。初始化完成后项目根目录下会多出一个impeccable.config.json文件这就是你的设计规范中心。3.2 设计 Token 的配置与计算配置文件的结构不复杂但每一项都值得仔细推敲。我拿自己项目里的配置举例{ tokens: { color: { primary: #2563eb, primary-hover: #1d4ed8, surface: #ffffff, surface-alt: #f8fafc, text: #0f172a, text-muted: #64748b, border: #e2e8f0 }, spacing: { unit: 4, scale: [0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64] }, radius: { sm: 4, md: 8, lg: 12, full: 9999 }, font: { family: Inter, system-ui, sans-serif, size: { xs: 12, sm: 14, base: 16, lg: 18, xl: 20, 2xl: 24, 3xl: 30 }, weight: { normal: 400, medium: 500, semibold: 600, bold: 700 } }, shadow: { sm: 0 1px 2px rgba(0,0,0,0.05), md: 0 4px 6px rgba(0,0,0,0.07), lg: 0 10px 15px rgba(0,0,0,0.1) } }, rules: { enforce-spacing-scale: true, enforce-color-contrast: true, min-contrast-ratio: 4.5, enforce-radius-scale: true, max-nesting-depth: 3 } }这里有几个关键点需要解释。间距的 unit 和 scale我设了unit: 4意思是所有间距必须是 4 的倍数。scale数组定义了允许使用的具体数值。比如padding: 16px是合法的因为 16 在 scale 里但padding: 15px就不合法会被 CLI 和浏览器扩展同时标记。这个设计的好处是AI 生成代码时不会出现padding: 13px这种“看起来差不多但就是不对劲”的值。颜色对比度min-contrast-ratio: 4.5是 WCAG AA 标准的要求。浏览器扩展会自动计算文字颜色和背景色的对比度低于这个值就会报警。我踩过的坑是AI 很喜欢用浅灰色文字配白色背景看起来“高级”但对比度只有 2.8 左右完全不可读。有了这个规则AI 生成的颜色组合会被自动拦截。最大嵌套深度max-nesting-depth: 3是为了防止 AI 生成过于复杂的组件结构。AI 有时候会写出.card .card-body .card-content .card-text这种四层嵌套样式覆盖起来非常痛苦。限制在三层以内结构会清晰很多。3.3 与 AI Coding Agent 的集成impeccable 最核心的用法是把它和你的 AI coding agent 串起来。我平时用 Codex CLI 比较多所以以它为例。首先在项目里安装 impeccable 的 agent 插件impeccable agent install codex这个命令会在你的 Codex CLI 配置目录下写入一个 hook让 Codex 在生成前端代码时自动读取impeccable.config.json。安装完成后你正常用 Codex CLI 写代码就行比如codex 帮我写一个登录页面包含邮箱和密码输入框以及一个登录按钮Codex 生成代码后impeccable 的 hook 会自动介入检查生成的 CSS 是否符合配置。如果不符合它会在 Codex 的输出里追加修正建议甚至直接重写不符合的部分。我实测下来开启 impeccable 之后AI 生成的页面在间距和颜色上的一致性提升了非常明显基本不需要我再手动调了。如果你用的是 Claude Code 或者其他支持 hook 的 agentimpeccable 也提供了对应的安装命令impeccable agent install claude impeccable agent install cursor提示安装 agent 插件后建议先跑一个简单的测试用例确认 hook 生效。你可以让 AI 生成一个按钮然后检查生成的 CSS 里border-radius的值是否在你的 radius scale 里。3.4 浏览器扩展的安装与使用CLI 管的是生成阶段浏览器扩展管的是预览阶段。安装方式很简单去 Chrome 应用商店搜索 “impeccable” 就行。安装完成后浏览器工具栏会多一个图标。使用流程是这样的你在本地跑起开发服务器比如npm run dev然后在浏览器里打开页面。点击 impeccable 扩展图标它会自动扫描当前页面的所有元素生成一份报告。报告分三个级别Error严重违反规则比如颜色对比度不达标、间距不在 scale 里。Warning建议修正比如嵌套深度接近上限、使用了未定义的字体权重。Info提示信息比如某个组件可以复用已有的 token。我一般会先把所有 Error 修掉然后看 Warning。Info 级别的基本可以忽略除非你在做设计系统的重构。扩展还有一个很实用的功能实时高亮。你可以在扩展的设置里开启“高亮违规元素”这样页面上所有不符合规范的元素会被红色边框标出来。改代码的时候刷新页面高亮会实时更新反馈非常快。4. 实战案例用 impeccable 重构一个 AI 生成的落地页4.1 初始状态AI 生成的“差不多”页面我拿之前用 Codex CLI 生成的一个落地页做测试。原始 prompt 是“帮我写一个 SaaS 产品的落地页包含导航栏、Hero 区域、三个功能卡片、一个定价表、页脚。” Codex 生成的页面功能上没问题但视觉上问题不少。我打开浏览器扩展扫描报告里列出了 23 个 Error 和 11 个 Warning。挑几个典型的Hero 区域的标题font-size: 2.5rem但我的 font size scale 里没有 2.5rem 这个值最接近的是 2xl24px和 3xl30px。功能卡片的padding: 20px不在 spacing scale 里20 不是 4 的倍数其实是但我的 scale 数组里没有 20 这个值。定价表的“推荐”标签用了#fbbf24作为背景白色文字对比度只有 1.8远低于 4.5。页脚的链接颜色是#94a3b8在白色背景上对比度 2.6也不达标。导航栏的box-shadow用了0 2px 8px rgba(0,0,0,0.15)不在我的 shadow token 里。这些问题单独看都不大但堆在一起页面就显得“不够专业”。这就是 AI 生成前端的典型状态能用但不精致。4.2 修正过程逐项对齐设计 Token修正的过程其实不复杂因为 impeccable 已经给出了具体的修正建议。我挑几个有代表性的说一下。字体大小的修正Hero 标题的2.5rem被建议改成3xl30px或者2xl24px。我选了3xl因为 Hero 区域需要视觉冲击力。这里有个经验不要盲目接受工具的建议要结合设计意图判断。impeccable 告诉你“这个值不在 scale 里”但选哪个值替代需要你自己决定。间距的修正卡片的padding: 20px被建议改成16px或24px。我选了24px因为卡片内容比较多需要足够的呼吸感。修正后三个卡片的间距完全一致视觉上整齐了很多。颜色对比度的修正定价表的“推荐”标签我把背景色从#fbbf24改成了#1d4ed8我的 primary-hover文字保持白色。对比度一下子到了 8.2远超标准。页脚链接颜色从#94a3b8改成#64748b我的 text-muted对比度 4.6刚好达标。阴影的修正导航栏的阴影改成了我的shadow-mdtoken。这里有个细节impeccable 的 shadow token 是完整的 CSS 值不是分开的。所以修正的时候直接替换整个box-shadow属性就行不用逐项调。整个修正过程花了大概 20 分钟改完之后再扫描Error 清零Warning 还剩 3 个都是嵌套深度接近上限的提示。页面的视觉一致性提升非常明显尤其是间距和颜色之前那种“说不上哪里不对但就是不舒服”的感觉消失了。4.3 修正前后的量化对比为了更直观地展示效果我整理了一个对比表格指标修正前修正后Error 数量230Warning 数量113使用的唯一间距值14 个6 个使用的唯一字体大小9 个5 个最低颜色对比度1.84.6最大嵌套深度5 层3 层页面加载后布局偏移CLS0.120.03CLS 的改善是我没想到的。后来分析了一下原因是修正后的间距和字体大小更统一浏览器在渲染时不需要频繁重排。这算是意外收获。5. 常见问题与排查技巧实录5.1 CLI 安装后命令找不到怎么办这是最常见的问题尤其是 Windows 用户。首先确认 npm 全局 bin 目录在 PATH 里npm config get prefix这个命令会输出全局安装路径。Windows 下通常是C:\Users\你的用户名\AppData\Roaming\npm。把这个路径加到系统环境变量的 PATH 里重启终端就行了。如果还是不行试试用npx直接跑npx impeccable-cli initnpx会临时下载并执行不依赖全局安装。缺点是每次都要下载速度慢一点。5.2 浏览器扩展扫描不到页面有时候你打开了页面但扩展图标是灰色的点开显示“未检测到可扫描的页面”。原因通常是页面还没完全加载或者页面用了 iframe 嵌套。解决办法等页面完全加载后再点扩展图标如果是 iframe需要在扩展设置里开启“扫描 iframe 内容”。还有一个可能你的页面是 HTTPS 的但扩展的权限没给全。去chrome://extensions找到 impeccable检查“网站访问权限”是否设为了“在所有网站上”。如果是“仅在点击时”需要手动授权当前域名。5.3 AI Agent 不读取 impeccable 配置如果你装了 agent 插件但 AI 生成的代码还是不符合规范先检查 hook 是否生效。以 Codex CLI 为例codex config list看看输出里有没有impeccable相关的 hook。如果没有重新跑一遍impeccable agent install codex。如果有但还是不生效可能是配置文件路径不对。impeccable 默认从项目根目录读取impeccable.config.json如果你的项目结构比较特殊需要在 agent 配置里手动指定路径。5.4 设计 Token 冲突怎么处理有时候你会遇到两个规则打架的情况。比如你的 spacing scale 里没有 20但某个组件的设计稿要求就是 20px。这时候你有两个选择一是把 20 加到 scale 里二是用 16 或 24 替代。我的经验是尽量不要为了单个组件破坏 scale 的完整性。如果 20px 出现的频率很高那说明你的 scale 需要调整如果只是个别情况用最接近的值替代视觉上几乎看不出差别。5.5 性能影响评估有人担心浏览器扩展会拖慢页面。我实测下来扫描一个中等复杂度的页面大概 500 个 DOM 节点耗时在 200ms 左右对日常开发的影响可以忽略。但如果你在做一个非常复杂的页面比如数据可视化大屏扫描可能会慢一些。这时候可以在扩展设置里关掉“自动扫描”改成手动触发。CLI 的性能影响主要在 agent 集成阶段。每次 AI 生成代码后impeccable 需要读取配置、分析代码、生成建议这个过程大概增加 1-2 秒的延迟。对于日常开发来说这个延迟是可以接受的换来的是视觉一致性的显著提升。6. 进阶用法把 impeccable 接入 CI 流程6.1 在 Git Hook 中做静态检查如果你想让团队所有人都遵守设计规范可以在 Git 的 pre-commit hook 里加入 impeccable 的检查#!/bin/sh npx impeccable-cli lint --staged if [ $? -ne 0 ]; then echo 设计规范检查未通过请修正后再提交 exit 1 fi这个命令会检查暂存区里的前端文件如果有违反设计 token 的地方直接阻止提交。我团队里用了这个之后代码 review 时关于样式的讨论少了很多因为机器已经把关了。6.2 与 CI/CD 流水线集成在 CI 里跑 impeccable 的完整检查# .github/workflows/design-check.yml name: Design Check on: [pull_request] jobs: impeccable: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g impeccable-cli - run: impeccable lint --all这个 workflow 会在每个 PR 上跑一遍设计规范检查不通过就标红。好处是设计规范变成了硬性门槛而不是靠自觉。6.3 多项目共享设计 Token如果你有多个项目共用一套设计系统可以把impeccable.config.json抽出来做成一个 npm 包然后在各个项目里引用npm install your-org/design-tokens然后在impeccable.config.json里{ extends: your-org/design-tokens/impeccable.config.json, tokens: { color: { primary: #你的项目特定颜色 } } }这样基础 token 统一维护项目特定的覆盖在本地。改一次基础 token所有项目同步更新。7. 我踩过的坑与个人体会说几个我实际踩过的坑希望能帮你省点时间。第一个坑一开始就把规则设得太严。我刚开始用的时候把enforce-spacing-scale设成了 truescale 数组只放了 8 个值。结果 AI 生成的代码几乎全军覆没修正建议刷屏根本改不过来。后来我把 scale 放宽到 13 个值Error 数量降到了可管理的范围。经验是规则要循序渐进先松后紧。第二个坑忽略了浏览器扩展的 iframe 限制。我有一个项目用了大量的 iframe 做微前端扩展默认不扫描 iframe 内容导致很多问题没被发现。后来在设置里开了 iframe 扫描才解决。如果你也用微前端架构记得检查这个设置。第三个坑agent hook 和手动修改冲突。有时候我手动改了代码但 agent hook 不知道下次 AI 生成时又覆盖回去了。解决办法是在手动修改后跑一次impeccable sync让 hook 重新读取最新状态。第四个坑颜色对比度规则的误报。有些设计确实需要低对比度比如装饰性的背景文字。impeccable 默认会把这些也标为 Error。你可以在配置里加exclude规则把特定的选择器排除在对比度检查之外。最后分享一个小技巧impeccable 的 CLI 有一个--fix参数可以自动修正常见的违规。我一般先跑impeccable lint --fix把能自动修的修掉剩下的再手动处理。这样效率高很多尤其是间距和圆角这类机械性的修正。这个工具后续还可以这样扩展把它和 Figma 的 design token 导出功能串起来设计稿改了之后自动更新impeccable.config.json然后 CI 自动跑一遍检查。这样设计和开发之间的鸿沟会进一步缩小。我目前正在折腾这个流程等跑通了再分享。