1. 从impeccable说起一个被低估的前端设计关键词第一次看到impeccable这个词是在翻一个海外前端团队的工程博客时。当时他们用这个词来形容一套内部的设计规范工具链大意是让 AI 写出来的界面不至于一眼假。后来这个词慢慢在 AI coding agents 的圈子里传开成了前端设计质量的一个隐性标准——不是能用而是挑不出毛病。这个词本身的意思是无可挑剔的、完美的放在前端设计语境下它指向的是一套非常具体的东西AI 生成的界面在视觉层级、间距节奏、色彩对比、交互反馈、响应式断点这些维度上是否达到了一个资深设计师手工打磨过的水准。这跟能跑起来完全是两码事。我见过太多 AI 生成的页面功能全对但按钮的 padding 是 13px 而不是 12px卡片阴影的模糊半径和偏移量不成比例标题和正文的行高比是 1.2 而不是 1.4——单看每个元素都没错凑在一起就是不对劲。这就是impeccable要解决的问题。它不是一个具体的库或框架而是一个质量目标围绕这个目标社区里逐渐形成了一套工具链和实践方法用 CLI 工具做设计规范的自动化校验用 browser extension 做实时视觉审查用 AI coding agents 做代码生成后的设计层修正。热搜词里出现的cli、zcode cli、codex cli、trae cli、minimax cli这些本质上都是不同团队在尝试用命令行工具把设计质量检查这件事自动化。这篇文章适合三类人看一是正在用 AI coding agents 写前端、但总觉得产出差口气的开发者二是想建立团队级设计规范、但不知道怎么落地的前端负责人三是对 CLI 工具链和 browser extension 感兴趣、想了解怎么把它们串起来做设计质量保障的工程师。我会从设计思路、核心细节、实操流程、问题排查四个层面把这套东西拆开讲清楚。2. 整体设计思路为什么impeccable需要工具链而不是靠人眼2.1 人眼审查的极限与 AI 生成的规模矛盾先说一个我踩过的坑。早期我用 AI coding agents 生成页面生成完自己看一眼觉得还行就提交了。结果上线后收到反馈在 1440px 宽度下卡片间距是 24px在 1280px 下变成了 22px在 1024px 下又变成 20px——因为 AI 在写响应式代码时用了不同的间距值而不是用统一的 spacing scale。这种问题人眼在单个断点下根本看不出来但用户在不同设备上切换时就会觉得哪里怪怪的。AI 生成代码的规模是人工的几十倍。一个中等复杂度的页面AI 可能生成 800 到 1500 行 CSS涉及几十个组件、上百个样式声明。靠人眼逐个检查间距、颜色、字号、行高、阴影、圆角、过渡曲线成本高到不现实。更关键的是人眼对一致性的敏感度远低于对明显错误的敏感度。一个按钮颜色错了你能一眼看出来但 20 个按钮里有 3 个的 hover 状态过渡时间是 0.2s 而其他是 0.3s你基本不可能发现。所以impeccable的第一个设计决策就是把设计质量检查从人眼审查转移到工具链自动校验。这不是说人眼不重要而是说人眼应该用在审美判断上而不是一致性检查上。一致性检查是机械劳动交给 CLI 工具和 browser extension 更靠谱。2.2 为什么选 CLI 作为核心入口热搜词里 CLI 相关的一大堆cli、zcode cli、codex cli、trae cli、minimax cli、openspec cli、gitlab cli安装、codex cli安装、codex cli 命令哪些 /compact /model /resume、删除codex cli指令。这说明什么说明CLI 已经成了 AI 辅助开发的事实标准入口。为什么是 CLI 而不是 GUI 或者 IDE 插件我的理解是三个原因。第一CLI 天然适合做管道——你可以把 AI 生成、设计校验、格式化、提交这一串操作串成一条命令中间不需要人工干预。第二CLI 的输出是文本文本可以被 diff、被 grep、被 CI 系统消费这意味着设计质量检查可以无缝接入现有的工程流程。第三CLI 工具通常比 GUI 工具更轻量、更可组合一个团队可以同时用codex cli做代码生成、用自定义的design-lint做设计校验、用gitlab cli做 MR 管理各司其职。具体到impeccable这个目标CLI 工具链的典型形态是这样的你有一个design-tokens.json或者tailwind.config.js定义设计规范然后有一个 CLI 工具扫描你的代码找出所有偏离规范的样式声明输出一份报告。这份报告可以是一份 JSON也可以是一份带行号的文本直接喂给 AI coding agent 让它修正。2.3 Browser extension 在闭环里的位置CLI 工具能检查代码但检查不了渲染后的实际效果。比如两个元素在代码里间距都是 16px但因为一个用了margin一个用了padding实际渲染出来可能因为盒模型差异导致视觉间距不一致。这种问题只有 browser extension 能发现。Browser extension 的另一个作用是实时反馈。你在编辑器里改代码浏览器里立刻能看到变化extension 可以在这个变化发生的瞬间做一次设计校验把问题标出来。这种反馈循环比改完代码跑一遍 CLI要快得多特别适合调间距、调颜色这种需要反复试的场景。我自己的做法是CLI 做提交前的全量校验browser extension 做开发中的实时校验。两者用同一套设计 token 配置保证检查标准一致。这样既不会在开发中被频繁打断又不会让问题漏到提交阶段。2.4 方案选型的三个关键取舍在搭这套工具链的时候有三个取舍点需要提前想清楚。第一个取舍设计 token 用 JSON 还是用代码配置。JSON 的好处是语言无关任何工具都能读坏处是不能写逻辑比如主色在暗色模式下要变亮 10%这种规则没法表达。代码配置比如tailwind.config.js的好处是灵活坏处是绑定特定框架。我的建议是用 JSON 存基础 token用代码配置存派生规则两者通过一个构建步骤同步。第二个取舍校验规则用内置还是自定义。内置规则比如间距必须是 4 的倍数开箱即用但覆盖不了团队的特殊规范。自定义规则灵活但写起来有成本。我的经验是先跑内置规则把明显问题清掉再针对反复出现的问题写自定义规则。不要一上来就写一堆自定义规则那样维护成本太高。第三个取舍AI 修正用自动还是手动。自动修正是让 AI 直接改代码手动修正是 AI 给出建议、人来决定改不改。自动修正效率高但风险是 AI 可能改错特别是涉及设计意图的地方。我的做法是机械性问题间距、颜色值、字号自动修正判断性问题布局结构、交互逻辑手动确认。3. 核心细节解析设计 token、校验规则与 AI 修正的实操要点3.1 设计 token 的层级结构与命名规范设计 token 是整套工具链的地基。如果 token 定义得乱后面的校验和修正都是空中楼阁。我见过不少团队的 token 文件里面既有primary-color又有color-primary既有spacing-4又有space-md这种混乱会让校验工具无所适从。一个可用的 token 结构应该分三层。第一层是原始值primitive比如blue-500: #3b82f6、gray-100: #f3f4f6这一层只定义颜色本身不定义用途。第二层是语义值semantic比如color-primary: {blue-500}、color-background: {gray-100}这一层把原始值映射到用途上。第三层是组件值component比如button-primary-bg: {color-primary}这一层把语义值映射到具体组件上。为什么要分三层因为改需求的时候你只需要改一层。比如产品说主色从蓝色改成紫色你只需要改color-primary的映射所有用到主色的组件自动跟着变。如果只有一层你就得全局搜索替换很容易漏。命名规范上我推荐用kebab-case 层级前缀比如color-primary、spacing-md、font-size-lg、radius-sm、shadow-md。前缀统一用类别名不要用--或者_这种容易和 CSS 变量混淆的符号。间距的命名我建议用xs/sm/md/lg/xl而不是1/2/3/4/5因为前者有语义后者只是序号时间长了没人记得spacing-3到底是 12px 还是 16px。提示token 文件一定要纳入版本控制并且每次修改都要走 code review。我见过团队因为有人直接改了 token 文件没通知其他人导致整个项目的间距体系崩掉的事故。3.2 校验规则的设计从能跑到impeccable的差距校验规则是这套工具链的核心。规则设计得好能抓住 90% 的设计问题设计得不好要么误报太多没人看要么漏报太多没意义。我把校验规则分成四类。第一类是硬性规则比如颜色值必须来自 token、间距必须是 4 的倍数、字号必须在预设的 scale 里。这类规则没有例外违反了就是错。第二类是软性规则比如相邻元素的间距差异不超过 2 个 token 级别、同一页面内阴影样式不超过 3 种。这类规则是建议性的违反了需要人工判断。第三类是上下文规则比如按钮的 padding 在移动端和桌面端应该一致、卡片圆角应该和内部图片圆角匹配。这类规则需要理解组件结构。第四类是性能规则比如避免使用box-shadow的 spread 值超过 20px、避免在动画中使用width和height。这类规则和设计质量间接相关但影响渲染性能。硬性规则用 CLI 工具直接扫代码就能实现。软性规则需要统计和对比实现起来复杂一些。上下文规则最难通常需要 browser extension 在渲染后做检查。性能规则可以用 Lighthouse 或者自定义的 AST 分析来做。我自己的规则集里硬性规则大概 20 条软性规则 10 条上下文规则 5 条性能规则 8 条。这个规模是经过半年迭代收敛下来的一开始我写了 60 多条规则结果误报太多团队直接不看了。规则不是越多越好而是越准越好。3.3 AI 修正的提示词设计与边界控制AI 修正是这套工具链里最玄的部分。同样一个间距问题提示词写得好AI 改得又快又准写得不好AI 要么不改要么改出新问题。我的提示词模板是这样的先给上下文这是什么项目、用什么框架、设计 token 在哪再给问题具体哪个文件哪一行、违反了哪条规则、当前值是什么、期望值是什么最后给约束只改这一处、不要动其他样式、改完保持代码风格一致。这个模板的关键是约束部分没有约束的 AI 修正很容易顺手改一堆无关的东西。边界控制上我设了三条线。第一条线AI 只能改样式值不能改样式结构。比如把padding: 13px改成padding: 12px可以但把padding改成margin不行。第二条线AI 只能改 token 覆盖范围内的值。如果某个值不在 token 里AI 应该报告而不是自己造一个。第三条线AI 改完必须跑一遍校验。如果改完还有问题说明 AI 没改对需要人工介入。注意AI 修正不要一次性改太多文件。我试过一次让 AI 改 50 个文件的间距问题结果它改到第 20 个文件的时候开始偷懒后面的文件只改了一部分。后来我改成每次最多改 10 个文件改完校验通过再继续。3.4 Browser extension 的实时校验实现思路Browser extension 做实时校验核心是监听 DOM 变化 读取计算样式 对比设计 token。具体来说extension 在页面加载后注入一段脚本用MutationObserver监听 DOM 变化每次变化后遍历新增或修改的元素用getComputedStyle读取实际渲染的样式值然后和 token 里的期望值对比。这里有个坑getComputedStyle返回的值是浏览器计算后的值可能和你写的值不一样。比如你写padding: 1remgetComputedStyle返回的是16px假设根字号是 16px。所以对比的时候要做单位归一化把所有值转成 px 再比。另一个坑是性能。如果页面上有几千个元素每次 DOM 变化都全量遍历页面会卡死。我的做法是只检查视口内的元素并且用requestIdleCallback把检查任务放到空闲时间执行。这样既不影响页面交互又能保证检查覆盖到用户实际看到的部分。Extension 的输出形式我建议用页面内浮层标注而不是弹窗或者控制台输出。浮层标注可以直接标在出问题的元素旁边开发者一眼就能看到是哪个元素、什么问题、期望值是什么。这种反馈比看控制台日志直观得多。4. 实操流程从零搭一套 impeccable 校验工具链4.1 环境准备与工具选型先列一下我实际在用的工具组合以及为什么选它们。工具用途选型理由Node.js 20运行时CLI 工具链的基础生态最全stylelintCSS 静态检查插件生态丰富支持自定义规则PostCSSCSS 解析与转换能拿到 AST方便做 token 替换Puppeteer无头浏览器渲染做渲染后校验比 jsdom 准确Chrome Extension API实时校验直接读计算样式最准确codex cli / trae cliAI 代码生成与修正命令行入口方便串流程安装上stylelint和postcss用 npm 装就行。puppeteer注意要装对应版本的 Chromium国内网络环境下可能需要配置镜像源。Chrome extension 的开发不需要额外安装用 Chrome 的开发者模式加载即可。提示如果你用的是codex cli或者trae cli这类工具注意它们的配置文件位置。codex cli的配置通常在~/.codex/下trae cli的配置在项目根目录的.trae/下。配置里可以指定设计 token 文件的路径这样 AI 生成代码时会自动参考 token。4.2 设计 token 文件的编写与同步先写一个基础的 token 文件。我用 JSON 格式放在项目根目录的design-tokens.json。{ color: { primitive: { blue-500: #3b82f6, blue-600: #2563eb, gray-100: #f3f4f6, gray-900: #111827 }, semantic: { primary: {color.primitive.blue-500}, primary-hover: {color.primitive.blue-600}, background: {color.primitive.gray-100}, text: {color.primitive.gray-900} } }, spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, font-size: { sm: 14px, base: 16px, lg: 18px, xl: 24px, 2xl: 32px }, radius: { sm: 4px, md: 8px, lg: 16px, full: 9999px }, shadow: { sm: 0 1px 2px rgba(0,0,0,0.05), md: 0 4px 6px rgba(0,0,0,0.1), lg: 0 10px 15px rgba(0,0,0,0.1) } }这个文件写完后需要一个同步脚本把它转成 CSS 变量和 JS 常量。CSS 变量供样式使用JS 常量供 browser extension 校验使用。// scripts/sync-tokens.js const fs require(fs); const tokens JSON.parse(fs.readFileSync(design-tokens.json, utf8)); // 生成 CSS 变量 let cssVars :root {\n; for (const [category, values] of Object.entries(tokens)) { for (const [name, value] of Object.entries(values.semantic || values)) { cssVars --${category}-${name}: ${value};\n; } } cssVars }\n; fs.writeFileSync(src/styles/tokens.css, cssVars); // 生成 JS 常量 fs.writeFileSync(src/tokens.js, export const tokens ${JSON.stringify(tokens, null, 2)};);这个脚本每次 token 文件改动后跑一遍保证 CSS 变量和 JS 常量同步。我把它挂在package.json的predev和prebuild钩子上这样开发和生产构建都会自动同步。4.3 stylelint 自定义规则的编写stylelint 内置规则能查语法错误但查不了设计规范。需要写自定义规则。下面是一个检查间距必须是 4 的倍数的规则示例。// stylelint-rules/spacing-multiple-of-4.js const stylelint require(stylelint); const ruleName impeccable/spacing-multiple-of-4; const messages stylelint.utils.ruleMessages(ruleName, { rejected: (value) 间距值 ${value} 不是 4 的倍数, }); module.exports stylelint.createPlugin(ruleName, (enabled) { return (root, result) { if (!enabled) return; root.walkDecls(/^(margin|padding)/, (decl) { const value decl.value; const pxValues value.match(/(\d)px/g) || []; pxValues.forEach((px) { const num parseInt(px); if (num % 4 ! 0) { stylelint.utils.report({ message: messages.rejected(px), node: decl, result, ruleName, }); } }); }); }; });这个规则会扫描所有margin和padding声明提取其中的 px 值检查是否是 4 的倍数。类似的规则还可以写颜色必须来自 token、字号必须在 scale 里、阴影样式不超过 3 种等等。写自定义规则的时候有个技巧先用正则粗筛再用 AST 精查。正则快但容易误报AST 准但慢。先用正则找出可疑的声明再对这些声明做 AST 分析能兼顾速度和准确率。4.4 Puppeteer 渲染后校验的实现静态检查查不出渲染后的问题需要 Puppeteer 起一个无头浏览器加载页面读取计算样式。// scripts/render-check.js const puppeteer require(puppeteer); const tokens require(../src/tokens.js).tokens; (async () { const browser await puppeteer.launch(); const page await browser.newPage(); await page.goto(http://localhost:3000, { waitUntil: networkidle0 }); const issues await page.evaluate((tokens) { const results []; const spacingValues Object.values(tokens.spacing).map((v) parseInt(v)); const colorValues Object.values(tokens.color.semantic); document.querySelectorAll(*).forEach((el) { const style getComputedStyle(el); const padding parseInt(style.paddingTop); if (padding 0 !spacingValues.includes(padding)) { results.push({ selector: el.tagName (el.className ? . el.className.split( )[0] : ), property: padding-top, actual: padding px, expected: spacingValues.join(px, ) px, }); } }); return results; }, tokens); console.log(JSON.stringify(issues, null, 2)); await browser.close(); })();这个脚本会输出所有padding 值不在 spacing scale 里的元素。实际用的时候可以扩展成检查颜色、字号、圆角、阴影等多个维度。注意Puppeteer 校验要在页面完全渲染后执行用networkidle0等待网络空闲。如果页面有懒加载内容还需要额外等待或者滚动触发。4.5 Browser extension 的开发与加载Browser extension 的结构很简单一个manifest.json一个 content script一个 background script。{ manifest_version: 3, name: Impeccable Checker, version: 1.0, content_scripts: [ { matches: [http://localhost:*/*], js: [content.js], css: [overlay.css] } ], permissions: [activeTab] }content script 的核心逻辑是监听 DOM 变化检查样式标注问题。// content.js const tokens window.__DESIGN_TOKENS__; function checkElement(el) { const style getComputedStyle(el); const spacingValues Object.values(tokens.spacing).map((v) parseInt(v)); const padding parseInt(style.paddingTop); if (padding 0 !spacingValues.includes(padding)) { el.style.outline 2px solid red; el.title padding-top: ${padding}px 不在 spacing scale 里; } } const observer new MutationObserver((mutations) { mutations.forEach((mutation) { mutation.addedNodes.forEach((node) { if (node.nodeType 1) { checkElement(node); node.querySelectorAll(*).forEach(checkElement); } }); }); }); observer.observe(document.body, { childList: true, subtree: true });加载方式打开 Chrome 的chrome://extensions/开启开发者模式点加载已解压的扩展程序选择 extension 目录。加载后访问本地开发页面有问题的元素会被红框标出。4.6 把 AI 修正串进流程最后一步是把 AI 修正串进流程。我的做法是写一个 shell 脚本把校验和修正串起来。#!/bin/bash # scripts/impeccable-fix.sh echo Step 1: 同步设计 token node scripts/sync-tokens.js echo Step 2: 静态检查 npx stylelint src/**/*.css --fix echo Step 3: 渲染后检查 node scripts/render-check.js issues.json echo Step 4: AI 修正 if [ -s issues.json ]; then codex cli fix --input issues.json --tokens design-tokens.json --max-files 10 fi echo Step 5: 复检 npx stylelint src/**/*.css node scripts/render-check.js这个脚本跑一遍能自动修掉大部分机械性问题。剩下的判断性问题脚本会输出报告人工处理。5. 常见问题与排查技巧实录5.1 校验工具误报太多怎么办这是最常见的问题。我一开始跑 stylelint报了 300 多个问题团队直接不看了。后来我做了三件事把误报降到 20 个以内。第一把规则分级。硬性规则必须改和软性规则建议改分开跑硬性规则报错软性规则只警告。第二加白名单。有些第三方组件的样式不受我们控制把这些文件或选择器加进白名单不检查。第三调阈值。比如间距必须是 4 的倍数这条规则一开始我设的是严格 4 的倍数后来发现有些设计稿就是 6px、10px改成允许 4 的倍数和 2 的倍数后误报少了很多。提示误报率超过 20% 的规则要么改阈值要么删掉。留着只会让团队对工具失去信任。5.2 AI 修正改出新问题怎么排查AI 修正偶尔会改出新问题比如把padding: 13px改成padding: 12px的同时顺手把margin: 8px改成了margin: 12px。排查这种问题我的做法是每次 AI 修正后跑一遍 git diff人工扫一眼改动范围。如果改动范围超出预期就回滚重来。更根本的解决办法是在提示词里加约束。我现在的提示词里有一句只修改报告中列出的具体属性不要修改任何其他属性。这句话加上后AI 乱改的情况少了很多。5.3 Browser extension 和 CLI 检查结果不一致这个问题的根源通常是检查时机不同。CLI 检查的是源代码extension 检查的是渲染后的计算样式。源代码里写padding: 1remCLI 看到的是1remextension 看到的是16px。如果 token 里定义的是16pxCLI 会认为1rem不匹配extension 会认为16px匹配。解决办法是在 CLI 里做单位归一化。写一个 PostCSS 插件把所有rem、em、%值转成 px 再检查。这样两边标准就一致了。5.4 常见问题速查表问题现象可能原因排查方法解决方案校验报错但代码看着没问题单位不一致检查 rem/px 混用加单位归一化插件AI 修正后校验仍不通过AI 没改全看 git diff缩小单次修正文件数Extension 不生效content script 没注入看 console 报错检查 manifest matches渲染检查超时页面有懒加载看 network 面板加滚动触发或延长等待token 改了但样式没变同步脚本没跑看 tokens.css挂 predev 钩子校验速度太慢全量遍历看性能面板只检查视口内元素5.5 几个我踩过的坑坑一token 文件用 YAML 而不是 JSON。一开始我觉得 YAML 写起来简洁后来发现 YAML 的缩进规则太容易出错而且很多工具对 YAML 的支持不如 JSON 好。换成 JSON 后省心很多。坑二把校验规则写死在代码里。规则应该配置化放在一个单独的rules.json里。这样改规则不用改代码非技术人员也能调。坑三忽略暗色模式。暗色模式下的颜色对比度、阴影可见度都和亮色模式不同需要单独一套校验规则。我一开始没考虑上线后暗色模式下问题一堆。坑四AI 修正没有版本控制。AI 改完代码如果不提交就继续改出问题很难回滚。我的做法是每次 AI 修正前先 commit 一次改完再 commit 一次这样随时能回退。坑五extension 的样式污染页面。Extension 注入的标注样式红框、tooltip可能和页面样式冲突。解决办法是给 extension 的样式加高优先级前缀或者用 Shadow DOM 隔离。6. 从工具链到工作习惯impeccable 的长期维护工具链搭起来只是第一步真正难的是让它持续运转。我见过太多团队工具搭好第一周用得很勤第二周就没人跑了第三周工具就荒废了。我的经验是把校验嵌进 CI。每次提交 MR 的时候自动跑一遍校验不通过就阻止合并。这样不需要靠人的自觉流程本身会强制校验执行。CI 配置大概长这样# .gitlab-ci.yml design-check: stage: test script: - npm run sync-tokens - npx stylelint src/**/*.css - node scripts/render-check.js rules: - if: $CI_MERGE_REQUEST_ID另一个经验是定期回顾规则。每个月花半小时看一下校验报告哪些规则经常触发、哪些规则从没触发过。经常触发的规则说明团队在这块有问题需要加强培训或者调整规范从没触发过的规则说明要么规则没用要么检查没覆盖到需要调整。还有一个经验是把设计 token 的修改权收归一人。Token 是整套体系的地基多人同时改很容易冲突。我们团队的做法是 token 修改必须走一个专门的 MR由设计负责人 review 后才能合并。这样虽然慢一点但保证了 token 体系的稳定性。最后分享一个我最近在试的做法用 AI 生成设计 token 的变更影响报告。每次 token 改动后让 AI 分析一下这次改动会影响哪些组件、哪些页面输出一份报告。这样 review 的时候能快速判断改动范围避免改了一个 token 结果全站样式崩了的事故。这个做法还在磨合中但初步效果不错。这套东西说到底核心不是工具而是对设计质量的较真。工具只是把这种较真自动化了。如果你本身对 13px 和 12px 的差别无所谓再好的工具链也救不了。但如果你确实在意impeccable这个标准那这套工具链能帮你把在意变成可执行、可复现、可持续的流程。