AI生成前端代码审美塌陷？用CLI与浏览器扩展构建设计质量检查闭环

1. 从“impeccable”这个词说起：它到底在解决什么问题

第一次看到“impeccable”这个词，很多人会愣一下——它是个形容词，意思是“无可挑剔的、完美的”。但放在 AI coding agents 和 frontend design 的语境里，它其实指向一个非常具体的痛点：AI 写出来的前端代码，往往“能跑”，但离“能看”还差得远。

我自己用各类 AI coding agent 做过不少前端项目，从落地页到后台管理面板都试过。一个反复出现的现象是：AI 生成的 HTML/CSS 结构在功能层面基本没问题，按钮能点、表单能提交、布局不塌，但视觉上总有一种说不出的“塑料感”——间距随意、配色突兀、字体层级混乱、圆角和阴影用得毫无章法。你让它改，它改完可能更糟，因为它并不真正理解“设计意图”，只是在做 token 层面的概率补全。

“impeccable”这个项目标题，加上 AI coding agents、frontend design、CLI、browser extension 这几个关键词，让我判断它大概率是一个面向 AI 编码代理的前端设计质量约束工具或规范层。它的核心价值不在于“帮你写代码”，而在于“让 AI 写出来的前端代码达到无可挑剔的视觉标准”。这跟单纯用 AI 生成代码是两回事——前者是生产力，后者是生产力加审美。

摘要描述和项目正文都是空的，这反而给了我更大的解读空间。结合热搜词里出现的 “impeccable 如何使用”“cli”“codex cli”“codex cli 安装” 等信息，可以合理推断：这个项目很可能提供了一个 CLI 工具，让开发者能在本地或 CI 流程中对 AI 生成的前端代码做设计质量检查，甚至可能配套一个 browser extension，用于在浏览器里实时预览和标注设计问题。

适合谁来读这篇内容？三类人：一是正在用 AI coding agent 做前端开发、但被“AI 审美”折磨的工程师；二是想给团队建立 AI 代码设计规范的 tech lead；三是对 frontend design 自动化质量保障感兴趣的工具党。不管你用的是哪家 CLI，底层思路是相通的。

提示：本文不会涉及任何具体平台的安装包下载或账号配置，只讲方法论和可复现的实操路径。你完全可以用自己熟悉的工具链来落地。

2. AI 生成前端代码的“审美塌陷”：根因不在模型，在约束缺失

2.1 为什么 AI 写的前端总是“差一口气”

要理解 impeccable 这类工具的价值，得先搞清楚 AI 生成前端代码为什么会“审美塌陷”。我总结下来有三个层面的原因，而且它们跟模型能力强不强关系不大。

第一层是训练数据的分布问题。公开代码库里大量前端代码本身就是“能跑就行”的水平——个人项目、教程示例、半成品 demo 占了很大比例。模型学到的“前端代码长什么样”，天然就偏向功能优先、样式凑合。你让它生成一个卡片组件，它给你的 padding 可能是 16px，也可能是 20px，因为训练数据里两种都有，它只是在做概率采样，并没有“8px 网格系统”这种设计约束的概念。

第二层是 token 预测的局部性。语言模型生成代码是逐 token 进行的，它在写第 50 行 CSS 的时候，对第 10 行定义的间距变量已经没有强记忆了。这就导致同一个页面里，两个本该一致的组件用了不同的圆角值。人类设计师会维护一套 design token，AI 不会主动这么做，除非你显式要求。

第三层是反馈闭环的缺失。人类前端开发者写完页面会打开浏览器看效果，觉得不对就调。AI coding agent 大多数时候是“盲写”——它生成完代码就结束了，没有视觉反馈。即使有 browser extension 做预览，如果没有人告诉它“这个间距太大了”，它也不知道要改。

impeccable 这类工具切入的正是第三层：给 AI 编码流程加上设计质量的反馈闭环。它不负责生成代码，而是负责在代码生成后，用一套可量化的设计规则去检查、标注、甚至自动修复。

2.2 设计质量可以被“规则化”吗

有人会质疑：设计是主观的，怎么能用规则去约束？这话对了一半。创意层面的设计确实主观，但工程层面的设计质量高度可规则化。

举个具体的例子。一个页面的视觉一致性，可以拆解成这些可检查的维度：

这些规则不涉及“好不好看”的主观判断，只涉及“一致不一致”“合不合理”的客观标准。impeccable 的核心思路，我推测就是把这套规则做成可执行的检查器，让 AI 生成的前端代码在提交前先过一遍“设计 lint”。

注意：规则化检查的目标不是让页面变得“千篇一律”，而是消除那些明显不专业的随机性。真正有创意的设计，是在规则之上做有意识的突破，而不是在规则之下做无意识的混乱。

2.3 CLI 在这个链路里扮演什么角色

热搜词里 “cli” 出现频率很高，这很合理。CLI 是这类工具最自然的形态，原因有三：

一是可集成。AI coding agent 的工作流大多在终端里，CLI 工具能无缝嵌入generate → check → fix的循环。你让 agent 生成完代码，紧接着跑一条impeccable check ./src，就能拿到设计质量报告。

二是可脚本化。设计检查如果能输出结构化结果（JSON 格式），就可以接入 CI/CD，在 PR 阶段就拦住设计质量不达标的代码。这比人工 review 高效得多。

三是可复现。CLI 的规则配置是文件化的，团队里每个人跑出来的结果一致。不像 browser extension 那样依赖手动操作，CLI 更适合做“守门员”。

至于 browser extension，它的价值在于可视化反馈。CLI 告诉你“第 42 行间距不符合网格”，browser extension 能直接在页面上把那个元素框出来，让你一眼看到问题。两者配合，一个管自动化，一个管交互式调试。

3. 把 impeccable 的思路落地：一套可复现的设计质量检查流程

3.1 环境准备：别急着装工具，先把规则想清楚

很多人一上来就找“impeccable 怎么安装”，但我的经验是：工具安装是最不重要的一步，规则定义才是。你就算装了再好的检查器，如果规则配置不符合你的项目实际，跑出来的报告全是噪音，用两天就弃了。

所以第一步是定义你的项目设计基线。拿一个真实项目举例，假设你在做一个 SaaS 后台，先明确这几件事：

• 间距基准：选 4px 还是 8px？我建议后台系统用 8px，营销页面用 4px，因为后台信息密度高，8px 网格能让布局更稳。
• 字号阶梯：定义 5 到 7 个层级，比如 12/14/16/20/24/32/40，超出这个集合的字号一律标记。
• 色板：主色、辅助色、中性色各定义几个色阶，中性色建议用 50/100/200…900 这种命名，方便检查器识别。
• 圆角策略：要么全用一套（比如统一 8px），要么按组件尺寸分两档（小元件 4px，大容器 12px），不要出现第三种。
• 阴影层级：定义 3 档就够了——卡片、浮层、模态。超过 3 档说明你在滥用阴影。

把这些写成一个配置文件，比如design-tokens.json，这就是你后续所有检查的基准。这一步做完，工具选型反而变得简单了，因为任何合格的检查器都应该能读这份配置。

3.2 CLI 检查器的核心逻辑拆解

假设我们要自己实现一个最小可用的设计质量检查 CLI（这也符合“基于常见实践的合理补全”原则），它的核心逻辑大概是这样的：

// design-lint.js 的核心检查逻辑示意 const fs = require('fs'); const postcss = require('postcss'); const tokens = JSON.parse(fs.readFileSync('./design-tokens.json')); function checkSpacing(cssRoot) { const violations = []; cssRoot.walkDecls(/^(margin|padding|gap)/, decl => { const value = parseFloat(decl.value); if (isNaN(value)) return; if (value % tokens.spacing.base !== 0) { violations.push({ line: decl.source.start.line, property: decl.prop, value: decl.value, rule: 'spacing-grid', message: `间距 ${decl.value} 不符合 ${tokens.spacing.base}px 网格` }); } }); return violations; } function checkFontScale(cssRoot) { const violations = []; cssRoot.walkDecls('font-size', decl => { const value = parseFloat(decl.value); if (!tokens.typography.scale.includes(value)) { violations.push({ line: decl.source.start.line, property: 'font-size', value: decl.value, rule: 'font-scale', message: `字号 ${decl.value} 不在定义的阶梯内` }); } }); return violations; }

这段代码的关键点在于：它不判断“好不好看”，只判断“在不在规则内”。这就是设计 lint 和设计评审的本质区别。lint 负责抓客观违规，评审负责抓主观问题。

实际跑起来，你会得到类似这样的输出：

./src/components/Card.css 12:5 warning spacing-grid 间距 13px 不符合 8px 网格 18:3 warning font-scale 字号 15px 不在定义的阶梯内 24:5 warning radius-consistency 圆角 6px 与项目基准 8px 不一致 3 problems (3 warnings, 0 errors)

这种输出格式跟 ESLint 几乎一样，好处是开发者一看就懂，而且可以直接接入现有的编辑器插件生态。

3.3 自动修复：让 AI agent 闭环的关键一环

光检查不修复，价值减半。impeccable 这类工具如果只做检查，那它就是个“挑刺机器”，用久了会烦。真正有价值的是自动修复能力。

自动修复的逻辑是：对于可安全替换的违规，直接改；对于有歧义的，给出建议但不自动改。比如：

• 间距 13px → 自动改成 16px（就近吸附到网格）
• 字号 15px → 自动改成 16px（就近吸附到阶梯）
• 圆角 6px → 自动改成 8px（统一到基准）
• 颜色#3a3a3a→ 如果色板里有#333333，建议替换但不自动改，因为颜色替换可能影响对比度

# 检查并自动修复 impeccable check ./src --fix # 只检查不修复，输出 JSON 供 CI 使用 impeccable check ./src --format json --output report.json

这里有个实操心得：自动修复一定要加--dry-run选项。我踩过的坑是，有一次批量修复把整个项目的间距从 4px 网格改成了 8px 网格，结果所有紧凑型组件的布局全乱了。后来我学乖了，任何批量修改前先 dry-run 看一遍 diff，确认没问题再实际执行。

提示：自动修复的“就近吸附”策略要谨慎。13px 吸附到 16px 还是 12px，取决于上下文。按钮内边距吸附到 12px 可能更合适，卡片间距吸附到 16px 更合适。高级的检查器应该支持按属性配置吸附策略。

3.4 与 AI coding agent 的集成方式

这是整个链路里最容易被忽略、但最关键的部分。impeccable 如果只是个人开发者手动跑，价值有限；它真正的威力在于嵌入 AI coding agent 的生成循环。

我实测下来，有两种集成模式比较靠谱：

模式一：生成后检查，失败则回炉。你给 AI agent 的 prompt 里加一条指令：“生成代码后，运行impeccable check，如果有违规，根据报告修复后重新生成。” 这样 agent 会自己迭代，直到设计检查通过。这个模式的好处是全自动，坏处是可能陷入无限循环——如果 agent 修不好某个违规，它会一直重试。所以要加一个最大重试次数，比如 3 次，超过就人工介入。

模式二：把设计规则写进 system prompt。与其事后检查，不如事前约束。把 design-tokens 里的核心规则用自然语言写进 agent 的 system prompt，比如“所有间距必须是 8px 的倍数，字号只能从 12/14/16/20/24/32 中选择”。这样 agent 生成时就会尽量遵守，事后检查的违规率会大幅下降。这个模式的好处是从源头减少问题，坏处是 prompt 会变长，占用 context window。

我的建议是两种模式结合：system prompt 里放最核心的 5 条规则，事后检查兜底。这样既控制了 prompt 长度，又保证了最终质量。

4. Browser Extension 的不可替代性：可视化反馈为什么重要

4.1 CLI 报告看不懂？因为设计问题本质是视觉问题

CLI 输出的文本报告有个天然缺陷：它用文字描述视觉问题，但视觉问题用文字描述效率极低。报告说“第 42 行 padding 13px 不符合网格”，你得打开文件、定位到第 42 行、在脑子里想象 13px 和 16px 的差别。这个认知成本很高。

Browser extension 解决的就是这个问题。它直接在渲染后的页面上，把违规元素用高亮框标出来，旁边显示违规详情。你一眼就能看到“哦，这个卡片的内边距确实比旁边那个小一点”。这种所见即所得的反馈，是 CLI 永远做不到的。

我推测 impeccable 配套的 browser extension 大概会有这些功能：

• 元素高亮：违规元素加彩色边框，不同违规类型用不同颜色
• 悬浮详情：鼠标悬停显示具体违规项和建议修复值
• 一键复制修复代码：点击后把修复后的 CSS 复制到剪贴板
• 页面级评分：给整个页面的设计一致性打分，方便快速判断
• 规则开关：临时关闭某类检查，避免噪音干扰

4.2 在浏览器里做设计检查的技术难点

实现一个设计检查 browser extension，技术上最大的难点不是检查逻辑本身，而是如何拿到准确的渲染后样式。

你用getComputedStyle拿到的值是浏览器计算后的最终值，但这里面有个坑：很多值是被继承或默认样式覆盖的，你分不清哪些是开发者显式写的，哪些是浏览器默认的。比如一个 div 没有写 padding，getComputedStyle返回0px，这个 0px 是“没写”还是“显式写了 0”，检查器需要区分。

我的处理思路是：结合 CSSOM 和 computed style 一起判断。遍历document.styleSheets找到实际生效的规则，再跟 computed style 对照。如果某个属性在 CSSOM 里找不到显式声明，就跳过检查，避免误报。

另一个难点是动态样式。现代前端大量使用 CSS-in-JS 和内联样式，这些样式在 CSSOM 里的呈现方式跟传统 CSS 不一样。检查器需要能识别style属性里的内联样式，以及<style>标签里动态注入的规则。

// browser extension 里获取“显式声明样式”的思路 function getExplicitStyles(element) { const explicit = {}; // 内联样式 if (element.style.length > 0) { for (let prop of element.style) { explicit[prop] = element.style.getPropertyValue(prop); } } // 样式表规则 for (let sheet of document.styleSheets) { try { for (let rule of sheet.cssRules) { if (rule.selectorText && element.matches(rule.selectorText)) { for (let prop of rule.style) { explicit[prop] = rule.style.getPropertyValue(prop); } } } } catch (e) { // 跨域样式表无法访问，跳过 } } return explicit; }

这段代码的关键是element.matches(rule.selectorText)，它判断当前元素是否匹配某条 CSS 规则。只有匹配的规则才算“显式声明”，这样就能过滤掉大量无关规则，提高检查准确率。

4.3 一个真实的使用场景还原

假设你在用 AI agent 生成一个 pricing table 组件。Agent 输出了代码，你把它渲染到浏览器里，然后打开 impeccable 的 browser extension。

页面上立刻出现几个高亮框：

• 第一个价格卡片的padding是 22px，被标黄，提示“不符合 8px 网格，建议 24px”
• 第二个卡片的border-radius是 10px，被标红，提示“与项目基准 8px 不一致”
• 三个卡片的font-size分别是 28px、30px、28px，中间那个被标黄，提示“字号不在阶梯内”
• 底部 CTA 按钮的文字颜色对比度只有 3.2:1，被标红，提示“对比度低于 4.5:1 标准”

你点开每个高亮框，能看到具体的修复建议。点“复制修复代码”，把修复后的 CSS 粘贴回项目。整个过程不到两分钟，比对着 CLI 报告逐行找快得多。

这就是 browser extension 的不可替代性：它把抽象的规则违规，转化成了具体的视觉标注。对于设计这种高度依赖视觉判断的领域，这个转化至关重要。

5. 从“检查”到“预防”：把设计约束前移到生成阶段

5.1 事后检查的天花板在哪里

用了几个月设计检查工具后，我发现一个规律：事后检查能抓住 80% 的明显问题，但剩下 20% 的问题会反复出现。因为 AI agent 每次生成都是“从零开始”，它不会记住上次被检查出的问题。你今天修好了间距，明天它生成新组件时又用回随机值。

这就是事后检查的天花板。要突破这个天花板，必须把约束前移——在 agent 生成代码之前，就把设计规则注入它的上下文。

具体怎么做？我实践下来有三个层次：

层次一：system prompt 硬约束。把最核心的规则用祈使句写进 system prompt。比如：“你生成的所有 CSS 必须遵守以下规则：间距只用 8 的倍数；字号只用 12/14/16/20/24/32；圆角只用 8px；颜色只用提供的色板变量。” 这个层次成本最低，效果立竿见影，但规则多了会占用大量 context。

层次二：提供示例代码。在 prompt 里附上一个“符合规范的组件示例”，让 agent 模仿。这比纯文字规则更有效，因为 agent 能直接从示例里学到模式。我通常会附一个 Button 组件和一个 Card 组件的完整代码，这两个组件覆盖了大部分基础样式模式。

层次三：工具调用约束。如果 agent 支持 function calling，可以给它一个getDesignTokens()工具，让它生成前先调用这个工具获取当前项目的设计变量。这样规则就是动态的、项目相关的，而不是硬编码在 prompt 里。

5.2 设计 token 的单一数据源原则

不管是哪个层次，前提都是设计 token 有单一数据源。什么意思？就是间距、字号、颜色这些设计变量，在整个项目里只能有一个定义处，所有地方都从这里引用。

在传统前端项目里，这个数据源可能是tailwind.config.js、theme.js或者 CSS 变量文件。在 AI 辅助开发的项目里，这个数据源还要额外暴露给 agent 和检查器。

我的做法是维护一个design-tokens.json，然后：

• 用构建脚本把它转成 CSS 变量，供页面使用
• 用 CLI 检查器读取它，作为检查基准
• 用 prompt 生成脚本把它转成自然语言规则，注入 agent 的 system prompt

{ "spacing": { "base": 8, "scale": [0, 8, 16, 24, 32, 48, 64] }, "typography": { "scale": [12, 14, 16, 20, 24, 32, 40], "lineHeight": { "tight": 1.2, "normal": 1.5, "loose": 1.8 } }, "radius": { "base": 8, "small": 4, "large": 12 }, "colors": { "primary": "#2563eb", "neutral": { "50": "#f8fafc", "100": "#f1f5f9", "900": "#0f172a" } } }

这份 JSON 就是整个设计系统的“宪法”。检查器、agent、构建脚本都从它派生规则，保证一致性。

5.3 给 AI agent 写设计规则 prompt 的实操模板

基于上面的 token 文件，我写了一个 prompt 生成脚本，把 JSON 转成 agent 能理解的规则描述。模板大概长这样：

你是一个前端开发助手，生成的所有样式必须遵守以下设计系统规则： 【间距规则】 - 所有 margin、padding、gap 的值必须是以下之一：0, 8px, 16px, 24px, 32px, 48px, 64px - 禁止使用不在上述列表中的间距值 - 组件内部间距优先使用 8px 或 16px，组件之间间距优先使用 24px 或 32px 【字号规则】 - 所有 font-size 的值必须是以下之一：12px, 14px, 16px, 20px, 24px, 32px, 40px - 正文使用 16px，辅助文字使用 14px，标题从 20px 起步 - 行高：正文 1.5，标题 1.2 【圆角规则】 - 小元件（按钮、标签、输入框）使用 4px 圆角 - 中等容器（卡片、面板）使用 8px 圆角 - 大容器（模态框、抽屉）使用 12px 圆角 【颜色规则】 - 主色使用 #2563eb - 中性色从 #f8fafc 到 #0f172a 的色阶中选择 - 禁止使用未定义的十六进制颜色值 生成代码后，请自查是否违反上述规则，如有违反请修正后再输出。

这个模板的关键是具体、可执行、有优先级。不要写“保持设计一致性”这种模糊的话，要写“间距必须是 0/8/16/24/32/48/64 之一”。Agent 对具体数字的遵守度远高于抽象原则。

注意：prompt 里的规则不要超过 10 条。超过之后 agent 的遵守率会明显下降，因为它要在生成每个 token 时同时考虑太多约束。把次要规则交给事后检查器兜底。

6. 踩坑记录：我在落地设计质量检查时遇到的五个真实问题

6.1 误报太多导致团队弃用

第一个坑最致命。我最初配置检查器时，把规则设得太严——所有间距必须是 8 的倍数，所有颜色必须来自色板，所有字号必须在阶梯内。结果跑出来 200 多个违规，团队里没人愿意看。

后来我做了三件事把误报降下来：

一是区分 error 和 warning。间距不在网格里是 warning，对比度不达标是 error。Warning 不阻断流程，只提示；error 才阻断。这样团队不会被 warning 淹没。

二是加白名单机制。有些第三方组件、图标字体、特殊布局确实需要打破规则，给它们加/* impeccable-ignore */注释，检查器跳过这些行。

三是分阶段启用规则。第一周只启用对比度检查，第二周加间距，第三周加字号。让团队逐步适应，而不是一次性面对所有规则。

6.2 自动修复把布局改崩了

前面提过，我踩过批量修复把 4px 网格改成 8px 网格导致布局崩坏的坑。后来我总结出自动修复的安全边界：

间距修复之所以危险，是因为它改变了元素的实际占位。一个 13px 的 padding 改成 16px，元素就宽了 6px，可能把旁边的元素挤下去。所以间距修复必须加--dry-run，人工确认后再执行。

6.3 browser extension 在 SPA 里失效

单页应用（SPA）的路由切换不会触发页面刷新，browser extension 如果只在DOMContentLoaded时扫描一次，切换路由后就失效了。解决方案是用MutationObserver监听 DOM 变化，在路由切换后重新扫描。

const observer = new MutationObserver((mutations) => { // 防抖，避免频繁触发 clearTimeout(window.__impeccableTimer); window.__impeccableTimer = setTimeout(() => { runDesignCheck(); }, 500); }); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['class', 'style'] });

这个坑我踩了两天才找到原因，一开始以为是 extension 坏了，后来才发现是 SPA 的 DOM 更新没被监听到。

6.4 agent 不遵守 prompt 里的设计规则

即使把规则写进了 system prompt，agent 有时还是会违反。我的经验是：规则要放在 prompt 的开头和结尾各一次。开头放一次让 agent 建立意识，结尾放一次做最后提醒。中间隔了很长的上下文后，开头的规则容易被“遗忘”。

另外，用否定句不如用肯定句。“不要使用 13px 间距”不如“间距只能使用 8px 的倍数”。否定句需要 agent 先理解什么不能做，再推导什么能做；肯定句直接告诉它做什么，遵守率更高。

6.5 设计 token 和实际代码脱节

最后一个坑是流程问题。设计 token 文件更新了，但代码里还是旧值；或者代码里有人硬编码了颜色，绕过了 token 系统。这种脱节会让检查器的基准失效。

解决方案是在 CI 里加一道 token 同步检查：扫描代码里所有的颜色值、间距值，跟 token 文件比对，发现硬编码就报错。这道检查比设计质量检查更基础，应该先跑。

# 检查是否有硬编码的设计值 impeccable audit-tokens ./src --tokens ./design-tokens.json

7. 这套方法论能走多远：我的个人判断

用了大半年设计质量检查工具，我对它的能力边界有了比较清晰的认识。它能解决的是“工程层面的设计一致性”，解决不了“创意层面的设计品味”。

什么意思？它能保证你的页面间距统一、字号成阶梯、颜色不杂乱、对比度达标。这些做完，页面至少是“专业”的，不会让人觉得是实习生随手写的。但它不能保证页面“好看”——好看需要创意、需要品牌感、需要设计师的审美判断，这些目前还无法规则化。

所以我的定位是：把 impeccable 这类工具当作设计质量的“下限保障”，而不是“上限追求”。它帮你守住底线，让你有精力去追求上限。对于 AI coding agent 来说，这个下限保障尤其重要，因为 agent 没有审美，你不给它约束，它就会给你随机值。

未来如果这类工具继续演进，我猜测会往两个方向走：一是更强的自动修复能力，不只是吸附到网格，还能根据上下文智能判断该用哪个值；二是与设计工具的深度集成，比如从 Figma 直接同步 design token，让设计和代码真正同源。

但不管工具怎么变，核心思路是不变的：把设计规则显式化、可执行化、自动化。只要你还在用 AI 生成前端代码，这个思路就一直有效。

最后分享一个我一直在用的小技巧：每次让 agent 生成新组件前，先让它读一遍项目里已有的同类组件。比如生成新的 Card，先让它看现有的 Card 代码。这样它生成的样式会自然向现有组件靠拢，比任何规则约束都有效。规则是死的，示例是活的，agent 模仿示例的能力远强于遵守规则的能力。