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: 1rem，getComputedStyle返回的是16px（假设根字号是 16px）。所以对比的时候要做单位归一化，把所有值转成 px 再比。

另一个坑是性能。如果页面上有几千个元素，每次 DOM 变化都全量遍历，页面会卡死。我的做法是只检查视口内的元素，并且用requestIdleCallback把检查任务放到空闲时间执行。这样既不影响页面交互，又能保证检查覆盖到用户实际看到的部分。

Extension 的输出形式我建议用页面内浮层标注，而不是弹窗或者控制台输出。浮层标注可以直接标在出问题的元素旁边，开发者一眼就能看到是哪个元素、什么问题、期望值是什么。这种反馈比看控制台日志直观得多。

4. 实操流程：从零搭一套 impeccable 校验工具链

4.1 环境准备与工具选型

先列一下我实际在用的工具组合，以及为什么选它们。

安装上，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: 1rem，CLI 看到的是1rem，extension 看到的是16px。如果 token 里定义的是16px，CLI 会认为1rem不匹配，extension 会认为16px匹配。

解决办法是在 CLI 里做单位归一化。写一个 PostCSS 插件，把所有rem、em、%值转成 px 再检查。这样两边标准就一致了。

5.4 常见问题速查表

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"这个标准，那这套工具链能帮你把在意变成可执行、可复现、可持续的流程。