1. 从“impeccable”这个词说起一个被低估的前端质量命题第一次看到“impeccable”作为项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI coding agent 帮你改一个按钮的 hover 态它改完了功能也对但间距从 16px 变成了 15px圆角从 8px 变成了 6px颜色从设计令牌里的--brand-500变成了硬编码的#3b82f6。功能测试全绿可这个页面已经“不 impeccable”了。这就是我想聊的核心问题。impeccable 这个词本身的意思是“无可挑剔的、完美的”放在前端设计语境里它指向的不是“能跑就行”而是视觉一致性、代码规范性和设计意图的忠实还原。而当下真正让这个话题变得紧迫的是 AI coding agents 的大规模介入——当 Codex CLI、各类 CLI 工具、浏览器扩展开始替我们写前端代码时“无可挑剔”这件事从个人手艺问题变成了一个系统性的工程问题。这个项目/话题适合谁看三类人一是正在用 AI agent 写前端、但被“改一处崩三处”折磨的开发者二是负责前端设计系统、需要保证多人多工具协作下视觉一致性的技术负责人三是对 CLI 工具链和浏览器扩展协同工作流感兴趣、想搭建一套可复现质量门禁的工程师。不管你是刚接触 AI 辅助编码的新手还是已经踩过一堆坑的老手下面这些内容应该都能让你少走点弯路。我先把结论摆出来impeccable 不是一个工具而是一套约束体系。它由三层构成——CLI 层的自动化检查、浏览器扩展层的实时视觉校验、以及 AI agent 层的提示词与上下文约束。三层缺一层你的前端质量就会在某个环节漏掉。2. 为什么 AI 写前端特别容易“不 impeccable”2.1 AI coding agents 的“局部最优”陷阱我用 Codex CLI 和几款主流 CLI 工具做过大量前端生成实验发现一个高度一致的现象AI agent 在单文件、单组件的局部任务上表现极好但一旦涉及跨文件的样式一致性翻车率陡增。原因不复杂——大模型的注意力机制天然偏向“当前上下文窗口内最相关的信息”而设计令牌、全局样式变量、组件库的间距体系这些东西往往散落在多个文件里不在它当前聚焦的那个文件内。举个我实际遇到的例子。我让 agent 给一个卡片组件加阴影它写了个box-shadow: 0 2px 8px rgba(0,0,0,0.1)。单看没问题但我们设计系统里阴影令牌是--shadow-card: 0 1px 3px rgba(0,0,0,0.08), 0 4px 12px rgba(0,0,0,0.06)。它没用令牌因为令牌定义在tokens.css里而它当时只打开了Card.tsx。这就是典型的局部最优——在当前文件里它做到了“无可挑剔”在系统层面它破坏了 impeccable。提示如果你在用 AI agent 写前端务必在每次任务开始前把设计令牌文件、全局样式约定、组件库的间距/圆角/颜色规范作为上下文显式喂给它。不要指望它自己去“发现”这些约束。2.2 CLI 工具链的检查盲区现在 CLI 生态很热闹Codex CLI、各类 code CLI、GitLab CLI 安装后都能跑自动化任务但大多数团队的 CLI 检查停留在 lint 和 type check 层面。ESLint 能抓出未使用的变量TypeScript 能抓出类型错误但它们抓不出“这个间距应该是 16px 而不是 15px”这种设计层面的偏差。我试过用 Stylelint 加自定义规则来补这个缺口效果不错但配置成本高。后来发现更实用的做法是把设计令牌的合法值导出成一份 JSON然后用一个轻量 CLI 脚本在 CI 里做比对。任何硬编码的颜色值、间距值、圆角值只要不在令牌白名单里直接报错。这个脚本我后面会给具体实现。2.3 浏览器扩展层的实时校验价值CLI 检查是事后诸葛亮浏览器扩展能做的是实时拦截。我目前的工作流里装了一个自己写的轻量扩展它做三件事一是高亮页面上所有硬编码样式值非 CSS 变量引用的二是对比当前渲染结果与设计稿的关键尺寸三是把偏差值直接输出到 console 并带上文件行号提示。这个扩展的价值在于缩短反馈回路。CLI 检查要等 commit 或 CI扩展检查在你刷新页面那一刻就告诉你“这个按钮的 padding 不对”。对于 AI agent 生成的前端代码这种即时反馈尤其重要因为你可以在 agent 还在会话中时就让它修正而不是等到代码合并后才发现问题。3. 搭建 impeccable 约束体系的核心组件3.1 设计令牌层单一事实来源一切 impeccable 的基础是设计令牌。没有令牌就没有“正确值”的基准所有检查都无从谈起。我的做法是用一套 JSON 定义所有设计决策然后通过构建脚本生成 CSS 变量、TypeScript 常量和 Tailwind 配置。{ color: { brand: { 500: #3b82f6, 600: #2563eb }, neutral: { 100: #f5f5f5, 900: #171717 } }, spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, radius: { sm: 4px, md: 8px, lg: 12px, full: 9999px }, shadow: { card: 0 1px 3px rgba(0,0,0,0.08), 0 4px 12px rgba(0,0,0,0.06) } }这份 JSON 是整个体系的“宪法”。CLI 检查脚本读它浏览器扩展读它AI agent 的提示词里也嵌入它。任何前端代码里出现的样式值要么是这份 JSON 里的令牌引用要么就是违规。注意令牌命名要有语义不要用blue-500这种纯视觉命名而要用brand-500、danger-600这种带意图的命名。原因很简单——当品牌色从蓝变紫时brand-500不需要改代码blue-500就得全局替换而 AI agent 最容易在全局替换时漏掉几处。3.2 CLI 检查层把设计规范变成可执行门禁CLI 层的核心是一个自定义检查脚本。我不推荐直接用现成的 lint 工具硬套因为设计规范的检查逻辑比较特殊自己写一个 200 行左右的 Node 脚本反而更可控。脚本的核心逻辑分三步。第一步扫描所有.css、.scss、.tsx、.jsx、.vue文件提取所有样式声明。第二步对每个样式值做判断颜色值是否匹配var(--color-*)或令牌白名单间距值是否匹配var(--spacing-*)或令牌白名单以此类推。第三步输出违规列表包含文件路径、行号、违规值和期望的令牌引用。// check-impeccable.js const fs require(fs); const path require(path); const tokens require(./design-tokens.json); const COLOR_WHITELIST new Set( Object.values(tokens.color).flatMap(shade Object.values(shade)) ); const SPACING_WHITELIST new Set(Object.values(tokens.spacing)); function checkFile(filePath) { const content fs.readFileSync(filePath, utf-8); const lines content.split(\n); const violations []; lines.forEach((line, index) { // 检查硬编码颜色 const colorMatches line.match(/#[0-9a-fA-F]{3,8}|rgba?\([^)]\)/g); if (colorMatches) { colorMatches.forEach(color { if (!COLOR_WHITELIST.has(color) !line.includes(var(--color)) { violations.push({ file: filePath, line: index 1, value: color, type: hardcoded-color, suggestion: 使用 var(--color-*) 令牌 }); } }); } // 检查硬编码间距 const spacingMatches line.match(/(?:padding|margin|gap):\s*(\dpx)/g); if (spacingMatches) { spacingMatches.forEach(match { const value match.match(/(\dpx)/)[1]; if (!SPACING_WHITELIST.has(value) !line.includes(var(--spacing)) { violations.push({ file: filePath, line: index 1, value, type: hardcoded-spacing, suggestion: 使用 var(--spacing-*) 令牌 }); } }); } }); return violations; }这个脚本跑起来很快一个中型项目几秒钟出结果。我把它挂在pre-commithook 里任何违规直接阻止提交。对于 AI agent 生成的代码这个门禁尤其关键——agent 不会主动遵守你的设计令牌除非你强制它。3.3 浏览器扩展层实时视觉偏差检测浏览器扩展这部分我用的是 Manifest V3 写的一个轻量工具。它不依赖任何外部服务纯本地运行。核心功能是注入一段 content script遍历页面上所有元素的 computed style对比设计令牌白名单把偏差元素用红色虚线框高亮出来。// content-script.js const tokens { spacing: [4px, 8px, 16px, 24px, 32px], radius: [4px, 8px, 12px, 9999px] }; function auditElement(el) { const style window.getComputedStyle(el); const issues []; const padding style.padding; const paddingValues padding.split( ).filter(v v ! 0px); paddingValues.forEach(v { if (!tokens.spacing.includes(v)) { issues.push(padding: ${v} 不在令牌范围内); } }); const radius style.borderRadius; if (radius ! 0px !tokens.radius.includes(radius)) { issues.push(border-radius: ${radius} 不在令牌范围内); } if (issues.length 0) { el.style.outline 2px dashed red; el.setAttribute(data-impeccable-issues, issues.join(; )); } } document.querySelectorAll(*).forEach(auditElement);这个扩展我平时只在开发环境启用生产环境自动关闭。它的价值不在于替代 CLI 检查而在于让视觉偏差可见。很多时候你盯着页面看不出 15px 和 16px 的区别但红色虚线框一标出来问题就无处遁形了。3.4 AI agent 提示词层把约束写进上下文前面三层都是“检查”这一层是“预防”。我的做法是在每次让 AI agent 写前端代码之前把一份精简的约束清单作为系统提示词的一部分喂给它。这份清单不需要很长但必须包含几个关键点所有颜色必须用var(--color-*)所有间距必须用var(--spacing-*)所有圆角必须用var(--radius-*)禁止硬编码任何样式值。我实测下来加了这段约束后agent 生成代码的令牌使用率从大概 40% 提升到了 85% 以上。剩下的 15% 靠 CLI 检查和浏览器扩展兜底。三层叠加基本能做到“无可挑剔”。提示给 AI agent 的约束清单要放在对话的最前面并且用明确的祈使句。我试过把约束放在对话中间效果明显下降——大模型对上下文开头和结尾的信息注意力最强中间部分容易被忽略。4. 完整实操流程从零搭建一套 impeccable 工作流4.1 第一步定义并生成设计令牌先建一个design-tokens.json把所有设计决策集中管理。然后写一个生成脚本输出三种格式CSS 变量文件、TypeScript 常量文件、以及给 AI agent 用的提示词片段。# 生成 CSS 变量 node scripts/generate-tokens.js --format css --output src/styles/tokens.css # 生成 TS 常量 node scripts/generate-tokens.js --format ts --output src/constants/tokens.ts # 生成 AI 提示词片段 node scripts/generate-tokens.js --format prompt --output .ai/token-constraints.md生成脚本本身不复杂核心就是遍历 JSON 树按格式拼接字符串。我建议把生成脚本也纳入版本控制每次令牌变更后重新生成确保所有消费方拿到的是同一份数据。4.2 第二步配置 CLI 检查并接入 CI把前面写的check-impeccable.js放到scripts/目录然后在package.json里加一条命令{ scripts: { check:impeccable: node scripts/check-impeccable.js --src src/ --tokens design-tokens.json } }本地开发时手动跑CI 里作为必过门禁。我用的 GitLab CI 配置大概长这样impeccable-check: stage: test script: - npm run check:impeccable allow_failure: falseallow_failure: false是关键任何违规直接阻断流水线。我踩过的坑是早期设成了true结果违规越积越多最后没人看了。门禁这东西一旦松一次就再也紧不起来了。4.3 第三步安装并配置浏览器扩展浏览器扩展我建议自己写因为现成的工具很难完全贴合你的令牌体系。代码量不大一个manifest.json加一个content-script.js就够了。关键配置是只在开发环境启用可以通过匹配localhost或内网域名来实现。{ manifest_version: 3, name: Impeccable Auditor, version: 1.0.0, content_scripts: [ { matches: [http://localhost:*/*, http://127.0.0.1:*/*], js: [content-script.js], run_at: document_idle } ] }run_at: document_idle确保页面渲染完成后再审计避免拿到不完整的 computed style。这个细节我调了好几次才找到合适的时机document_start太早document_end偶尔还是会漏掉异步渲染的组件。4.4 第四步把约束写进 AI agent 工作流这一步没有代码但最重要。我的做法是建一个.ai/目录里面放三份文件token-constraints.md令牌约束、component-patterns.md组件编写范式、review-checklist.md自查清单。每次开新会话让 agent 写前端代码时先把这三份文件的内容贴进对话开头。token-constraints.md的内容就是前面生成的提示词片段大概长这样所有颜色必须使用 var(--color-*) 格式禁止硬编码十六进制或 rgb 值。 所有间距必须使用 var(--spacing-*) 格式禁止硬编码 px 值。 所有圆角必须使用 var(--radius-*) 格式禁止硬编码 px 值。 所有阴影必须使用 var(--shadow-*) 格式禁止硬编码 box-shadow 值。 如果某个值在令牌中不存在先提出新增令牌的建议不要直接硬编码。最后一条特别重要。我遇到过 agent 因为找不到合适的令牌就直接硬编码了一个值。加上这条约束后它会主动说“当前令牌体系里没有 20px 的间距建议新增--spacing-lg-plus”而不是偷偷写个20px进去。5. 常见问题与排查技巧实录5.1 令牌值对不上设计稿怎么办这是最高频的问题。设计稿标注 20px但令牌体系里只有 16px 和 24px。我的处理原则是优先调整设计稿而不是新增令牌。令牌体系的价值在于约束如果每遇到一个非标值就新增令牌体系很快就膨胀到失去约束力。具体做法是跟设计师对齐问清楚这个 20px 是刻意为之还是随手标的。十次里有八次是随手标的改成 16px 或 24px 对视觉效果几乎没有影响。剩下两次确实需要 20px 的再新增令牌并且同步更新所有消费方。5.2 AI agent 反复违反约束怎么破我试过三种策略。第一种是每次违规后在对话里纠正它效果一般它会在同一个会话里改但新会话又忘。第二种是把约束写进系统提示词效果好很多但仍有漏网之鱼。第三种是在 agent 生成代码后立即跑 CLI 检查把违规结果贴回对话让它修正这个闭环最有效。我的实际工作流是agent 生成代码 → 我跑npm run check:impeccable→ 把违规输出贴回对话 → agent 修正 → 再跑一次确认。通常一到两轮就能收敛。虽然多了一步但比事后手动改要快得多。5.3 浏览器扩展误报怎么处理误报主要来自第三方组件库。比如你引入了一个 UI 库它的内部样式用了非令牌值扩展会把这些也标红。我的处理方式是加一个忽略列表把第三方库的类名前缀或 DOM 路径排除掉。const IGNORE_SELECTORS [ .ant-, // Ant Design .el-, // Element UI [data-third-party] ]; function shouldIgnore(el) { return IGNORE_SELECTORS.some(sel el.matches(sel) || el.closest(sel)); }在auditElement开头加一个if (shouldIgnore(el)) return;就行。这个忽略列表要定期审查避免把自家组件也误加进去。5.4 CLI 检查跑得太慢怎么优化项目大了之后全量扫描会变慢。我的优化手段有三个一是只扫描变更文件通过git diff --name-only拿到改动列表二是并行处理用worker_threads把文件分片三是缓存令牌白名单避免每个文件都重新加载 JSON。# 只检查变更文件 git diff --name-only HEAD~1 | grep -E \.(css|scss|tsx|jsx|vue)$ | xargs node scripts/check-impeccable.js这个改动让检查时间从 12 秒降到了 2 秒以内体验提升明显。CI 里仍然跑全量本地开发用增量。5.5 常见问题速查表问题现象可能原因排查方向解决手段CLI 检查报大量硬编码颜色agent 未加载令牌约束检查对话开头是否贴了约束文件补上约束重新生成浏览器扩展不生效content script 注入时机不对检查run_at配置改为document_idle令牌生成后样式没更新构建缓存未清除检查构建脚本是否监听令牌文件加--watch或手动清缓存agent 反复用同一个错误值约束描述不够明确检查约束文件措辞改成祈使句加禁止性表述CI 门禁被绕过allow_failure设成了 true检查 CI 配置改为 false强制阻断6. 一些踩坑之后的个人体会这套 impeccable 约束体系我断断续续搭了大概两个月中间推翻重来过一次。最大的教训是不要试图一步到位。我一开始想做一个大而全的检查工具结果配置复杂到我自己都不想用。后来拆成令牌层、CLI 层、扩展层、提示词层四个独立模块每个模块单独可用组合起来才形成完整体系反而落地得更顺。另一个体会是关于 AI agent 的。很多人觉得 agent 写前端“不够聪明”我的观察是它其实很聪明只是缺少约束。你给它清晰的边界它能在边界内做到相当 impeccable你不给边界它就会在无限的可能性里随机游走。所以与其抱怨 agent 写得不规范不如花时间把约束体系搭好。约束越清晰agent 的表现越稳定。最后分享一个我最近在用的技巧把 CLI 检查的违规输出格式化成一段结构化的 JSON直接作为下一轮对话的输入喂给 agent。这样 agent 不需要理解自然语言的错误描述直接读结构化数据就能精准定位问题。实测下来修正轮次从平均 2.3 轮降到了 1.4 轮省了不少来回。这套东西后续还可以往两个方向扩展。一是把视觉回归测试接进来用截图对比的方式抓出 CLI 和扩展都覆盖不到的布局偏差二是把令牌体系跟设计工具打通让设计师改完稿子后令牌自动同步省掉手动对齐的环节。这两个方向我还在摸索等跑通了再另开一篇聊。 1. 从“impeccable”这个词说起一个被低估的前端质量命题第一次看到“impeccable”作为项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI coding agent 帮你改一个按钮的 hover 态它改完了功能也对但间距从 16px 变成了 15px圆角从 8px 变成了 6px颜色从设计令牌里的--brand-500变成了硬编码的#3b82f6。功能测试全绿可这个页面已经“不 impeccable”了。这就是我想聊的核心问题。impeccable 这个词本身的意思是“无可挑剔的、完美的”放在前端设计语境里它指向的不是“能跑就行”而是视觉一致性、代码规范性和设计意图的忠实还原。而当下真正让这个话题变得紧迫的是 AI coding agents 的大规模介入——当 Codex CLI、各类 CLI 工具、浏览器扩展开始替我们写前端代码时“无可挑剔”这件事从个人手艺问题变成了一个系统性的工程问题。这个项目/话题适合谁看三类人一是正在用 AI agent 写前端、但被“改一处崩三处”折磨的开发者二是负责前端设计系统、需要保证多人多工具协作下视觉一致性的技术负责人三是对 CLI 工具链和浏览器扩展协同工作流感兴趣、想搭建一套可复现质量门禁的工程师。不管你是刚接触 AI 辅助编码的新手还是已经踩过一堆坑的老手下面这些内容应该都能让你少走点弯路。我先把结论摆出来impeccable 不是一个工具而是一套约束体系。它由三层构成——CLI 层的自动化检查、浏览器扩展层的实时视觉校验、以及 AI agent 层的提示词与上下文约束。三层缺一层你的前端质量就会在某个环节漏掉。2. 为什么 AI 写前端特别容易“不 impeccable”2.1 AI coding agents 的“局部最优”陷阱我用 Codex CLI 和几款主流 CLI 工具做过大量前端生成实验发现一个高度一致的现象AI agent 在单文件、单组件的局部任务上表现极好但一旦涉及跨文件的样式一致性翻车率陡增。原因不复杂——大模型的注意力机制天然偏向“当前上下文窗口内最相关的信息”而设计令牌、全局样式变量、组件库的间距体系这些东西往往散落在多个文件里不在它当前聚焦的那个文件内。举个我实际遇到的例子。我让 agent 给一个卡片组件加阴影它写了个box-shadow: 0 2px 8px rgba(0,0,0,0.1)。单看没问题但我们设计系统里阴影令牌是--shadow-card: 0 1px 3px rgba(0,0,0,0.08), 0 4px 12px rgba(0,0,0,0.06)。它没用令牌因为令牌定义在tokens.css里而它当时只打开了Card.tsx。这就是典型的局部最优——在当前文件里它做到了“无可挑剔”在系统层面它破坏了 impeccable。提示如果你在用 AI agent 写前端务必在每次任务开始前把设计令牌文件、全局样式约定、组件库的间距/圆角/颜色规范作为上下文显式喂给它。不要指望它自己去“发现”这些约束。2.2 CLI 工具链的检查盲区现在 CLI 生态很热闹Codex CLI、各类 code CLI、GitLab CLI 安装后都能跑自动化任务但大多数团队的 CLI 检查停留在 lint 和 type check 层面。ESLint 能抓出未使用的变量TypeScript 能抓出类型错误但它们抓不出“这个间距应该是 16px 而不是 15px”这种设计层面的偏差。我试过用 Stylelint 加自定义规则来补这个缺口效果不错但配置成本高。后来发现更实用的做法是把设计令牌的合法值导出成一份 JSON然后用一个轻量 CLI 脚本在 CI 里做比对。任何硬编码的颜色值、间距值、圆角值只要不在令牌白名单里直接报错。这个脚本我后面会给具体实现。2.3 浏览器扩展层的实时校验价值CLI 检查是事后诸葛亮浏览器扩展能做的是实时拦截。我目前的工作流里装了一个自己写的轻量扩展它做三件事一是高亮页面上所有硬编码样式值非 CSS 变量引用的二是对比当前渲染结果与设计稿的关键尺寸三是把偏差值直接输出到 console 并带上文件行号提示。这个扩展的价值在于缩短反馈回路。CLI 检查要等 commit 或 CI扩展检查在你刷新页面那一刻就告诉你“这个按钮的 padding 不对”。对于 AI agent 生成的前端代码这种即时反馈尤其重要因为你可以在 agent 还在会话中时就让它修正而不是等到代码合并后才发现问题。3. 搭建 impeccable 约束体系的核心组件3.1 设计令牌层单一事实来源一切 impeccable 的基础是设计令牌。没有令牌就没有“正确值”的基准所有检查都无从谈起。我的做法是用一套 JSON 定义所有设计决策然后通过构建脚本生成 CSS 变量、TypeScript 常量和 Tailwind 配置。{ color: { brand: { 500: #3b82f6, 600: #2563eb }, neutral: { 100: #f5f5f5, 900: #171717 } }, spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, radius: { sm: 4px, md: 8px, lg: 12px, full: 9999px }, shadow: { card: 0 1px 3px rgba(0,0,0,0.08), 0 4px 12px rgba(0,0,0,0.06) } }这份 JSON 是整个体系的“宪法”。CLI 检查脚本读它浏览器扩展读它AI agent 的提示词里也嵌入它。任何前端代码里出现的样式值要么是这份 JSON 里的令牌引用要么就是违规。注意令牌命名要有语义不要用blue-500这种纯视觉命名而要用brand-500、danger-600这种带意图的命名。原因很简单——当品牌色从蓝变紫时brand-500不需要改代码blue-500就得全局替换而 AI agent 最容易在全局替换时漏掉几处。3.2 CLI 检查层把设计规范变成可执行门禁CLI 层的核心是一个自定义检查脚本。我不推荐直接用现成的 lint 工具硬套因为设计规范的检查逻辑比较特殊自己写一个 200 行左右的 Node 脚本反而更可控。脚本的核心逻辑分三步。第一步扫描所有.css、.scss、.tsx、.jsx、.vue文件提取所有样式声明。第二步对每个样式值做判断颜色值是否匹配var(--color-*)或令牌白名单间距值是否匹配var(--spacing-*)或令牌白名单以此类推。第三步输出违规列表包含文件路径、行号、违规值和期望的令牌引用。// check-impeccable.js const fs require(fs); const path require(path); const tokens require(./design-tokens.json); const COLOR_WHITELIST new Set( Object.values(tokens.color).flatMap(shade Object.values(shade)) ); const SPACING_WHITELIST new Set(Object.values(tokens.spacing)); function checkFile(filePath) { const content fs.readFileSync(filePath, utf-8); const lines content.split(\n); const violations []; lines.forEach((line, index) { // 检查硬编码颜色 const colorMatches line.match(/#[0-9a-fA-F]{3,8}|rgba?\([^)]\)/g); if (colorMatches) { colorMatches.forEach(color { if (!COLOR_WHITELIST.has(color) !line.includes(var(--color)) { violations.push({ file: filePath, line: index 1, value: color, type: hardcoded-color, suggestion: 使用 var(--color-*) 令牌 }); } }); } // 检查硬编码间距 const spacingMatches line.match(/(?:padding|margin|gap):\s*(\dpx)/g); if (spacingMatches) { spacingMatches.forEach(match { const value match.match(/(\dpx)/)[1]; if (!SPACING_WHITELIST.has(value) !line.includes(var(--spacing)) { violations.push({ file: filePath, line: index 1, value, type: hardcoded-spacing, suggestion: 使用 var(--spacing-*) 令牌 }); } }); } }); return violations; }这个脚本跑起来很快一个中型项目几秒钟出结果。我把它挂在pre-commithook 里任何违规直接阻止提交。对于 AI agent 生成的代码这个门禁尤其关键——agent 不会主动遵守你的设计令牌除非你强制它。3.3 浏览器扩展层实时视觉偏差检测浏览器扩展这部分我用的是 Manifest V3 写的一个轻量工具。它不依赖任何外部服务纯本地运行。核心功能是注入一段 content script遍历页面上所有元素的 computed style对比设计令牌白名单把偏差元素用红色虚线框高亮出来。// content-script.js const tokens { spacing: [4px, 8px, 16px, 24px, 32px], radius: [4px, 8px, 12px, 9999px] }; function auditElement(el) { const style window.getComputedStyle(el); const issues []; const padding style.padding; const paddingValues padding.split( ).filter(v v ! 0px); paddingValues.forEach(v { if (!tokens.spacing.includes(v)) { issues.push(padding: ${v} 不在令牌范围内); } }); const radius style.borderRadius; if (radius ! 0px !tokens.radius.includes(radius)) { issues.push(border-radius: ${radius} 不在令牌范围内); } if (issues.length 0) { el.style.outline 2px dashed red; el.setAttribute(data-impeccable-issues, issues.join(; )); } } document.querySelectorAll(*).forEach(auditElement);这个扩展我平时只在开发环境启用生产环境自动关闭。它的价值不在于替代 CLI 检查而在于让视觉偏差可见。很多时候你盯着页面看不出 15px 和 16px 的区别但红色虚线框一标出来问题就无处遁形了。3.4 AI agent 提示词层把约束写进上下文前面三层都是“检查”这一层是“预防”。我的做法是在每次让 AI agent 写前端代码之前把一份精简的约束清单作为系统提示词的一部分喂给它。这份清单不需要很长但必须包含几个关键点所有颜色必须用var(--color-*)所有间距必须用var(--spacing-*)所有圆角必须用var(--radius-*)禁止硬编码任何样式值。我实测下来加了这段约束后agent 生成代码的令牌使用率从大概 40% 提升到了 85% 以上。剩下的 15% 靠 CLI 检查和浏览器扩展兜底。三层叠加基本能做到“无可挑剔”。提示给 AI agent 的约束清单要放在对话的最前面并且用明确的祈使句。我试过把约束放在对话中间效果明显下降——大模型对上下文开头和结尾的信息注意力最强中间部分容易被忽略。4. 完整实操流程从零搭建一套 impeccable 工作流4.1 第一步定义并生成设计令牌先建一个design-tokens.json把所有设计决策集中管理。然后写一个生成脚本输出三种格式CSS 变量文件、TypeScript 常量文件、以及给 AI agent 用的提示词片段。# 生成 CSS 变量 node scripts/generate-tokens.js --format css --output src/styles/tokens.css # 生成 TS 常量 node scripts/generate-tokens.js --format ts --output src/constants/tokens.ts # 生成 AI 提示词片段 node scripts/generate-tokens.js --format prompt --output .ai/token-constraints.md生成脚本本身不复杂核心就是遍历 JSON 树按格式拼接字符串。我建议把生成脚本也纳入版本控制每次令牌变更后重新生成确保所有消费方拿到的是同一份数据。4.2 第二步配置 CLI 检查并接入 CI把前面写的check-impeccable.js放到scripts/目录然后在package.json里加一条命令{ scripts: { check:impeccable: node scripts/check-impeccable.js --src src/ --tokens design-tokens.json } }本地开发时手动跑CI 里作为必过门禁。我用的 GitLab CI 配置大概长这样impeccable-check: stage: test script: - npm run check:impeccable allow_failure: falseallow_failure: false是关键任何违规直接阻断流水线。我踩过的坑是早期设成了true结果违规越积越多最后没人看了。门禁这东西一旦松一次就再也紧不起来了。4.3 第三步安装并配置浏览器扩展浏览器扩展我建议自己写因为现成的工具很难完全贴合你的令牌体系。代码量不大一个manifest.json加一个content-script.js就够了。关键配置是只在开发环境启用可以通过匹配localhost或内网域名来实现。{ manifest_version: 3, name: Impeccable Auditor, version: 1.0.0, content_scripts: [ { matches: [http://localhost:*/*, http://127.0.0.1:*/*], js: [content-script.js], run_at: document_idle } ] }run_at: document_idle确保页面渲染完成后再审计避免拿到不完整的 computed style。这个细节我调了好几次才找到合适的时机document_start太早document_end偶尔还是会漏掉异步渲染的组件。4.4 第四步把约束写进 AI agent 工作流这一步没有代码但最重要。我的做法是建一个.ai/目录里面放三份文件token-constraints.md令牌约束、component-patterns.md组件编写范式、review-checklist.md自查清单。每次开新会话让 agent 写前端代码时先把这三份文件的内容贴进对话开头。token-constraints.md的内容就是前面生成的提示词片段大概长这样所有颜色必须使用 var(--color-*) 格式禁止硬编码十六进制或 rgb 值。 所有间距必须使用 var(--spacing-*) 格式禁止硬编码 px 值。 所有圆角必须使用 var(--radius-*) 格式禁止硬编码 px 值。 所有阴影必须使用 var(--shadow-*) 格式禁止硬编码 box-shadow 值。 如果某个值在令牌中不存在先提出新增令牌的建议不要直接硬编码。最后一条特别重要。我遇到过 agent 因为找不到合适的令牌就直接硬编码了一个值。加上这条约束后它会主动说“当前令牌体系里没有 20px 的间距建议新增--spacing-lg-plus”而不是偷偷写个20px进去。5. 常见问题与排查技巧实录5.1 令牌值对不上设计稿怎么办这是最高频的问题。设计稿标注 20px但令牌体系里只有 16px 和 24px。我的处理原则是优先调整设计稿而不是新增令牌。令牌体系的价值在于约束如果每遇到一个非标值就新增令牌体系很快就膨胀到失去约束力。具体做法是跟设计师对齐问清楚这个 20px 是刻意为之还是随手标的。十次里有八次是随手标的改成 16px 或 24px 对视觉效果几乎没有影响。剩下两次确实需要 20px 的再新增令牌并且同步更新所有消费方。5.2 AI agent 反复违反约束怎么破我试过三种策略。第一种是每次违规后在对话里纠正它效果一般它会在同一个会话里改但新会话又忘。第二种是把约束写进系统提示词效果好很多但仍有漏网之鱼。第三种是在 agent 生成代码后立即跑 CLI 检查把违规结果贴回对话让它修正这个闭环最有效。我的实际工作流是agent 生成代码 → 我跑npm run check:impeccable→ 把违规输出贴回对话 → agent 修正 → 再跑一次确认。通常一到两轮就能收敛。虽然多了一步但比事后手动改要快得多。5.3 浏览器扩展误报怎么处理误报主要来自第三方组件库。比如你引入了一个 UI 库它的内部样式用了非令牌值扩展会把这些也标红。我的处理方式是加一个忽略列表把第三方库的类名前缀或 DOM 路径排除掉。const IGNORE_SELECTORS [ .ant-, // Ant Design .el-, // Element UI [data-third-party] ]; function shouldIgnore(el) { return IGNORE_SELECTORS.some(sel el.matches(sel) || el.closest(sel)); }在auditElement开头加一个if (shouldIgnore(el)) return;就行。这个忽略列表要定期审查避免把自家组件也误加进去。5.4 CLI 检查跑得太慢怎么优化项目大了之后全量扫描会变慢。我的优化手段有三个一是只扫描变更文件通过git diff --name-only拿到改动列表二是并行处理用worker_threads把文件分片三是缓存令牌白名单避免每个文件都重新加载 JSON。# 只检查变更文件 git diff --name-only HEAD~1 | grep -E \.(css|scss|tsx|jsx|vue)$ | xargs node scripts/check-impeccable.js这个改动让检查时间从 12 秒降到了 2 秒以内体验提升明显。CI 里仍然跑全量本地开发用增量。5.5 常见问题速查表问题现象可能原因排查方向解决手段CLI 检查报大量硬编码颜色agent 未加载令牌约束检查对话开头是否贴了约束文件补上约束重新生成浏览器扩展不生效content script 注入时机不对检查run_at配置改为document_idle令牌生成后样式没更新构建缓存未清除检查构建脚本是否监听令牌文件加--watch或手动清缓存agent 反复用同一个错误值约束描述不够明确检查约束文件措辞改成祈使句加禁止性表述CI 门禁被绕过allow_failure设成了 true检查 CI 配置改为 false强制阻断6. 一些踩坑之后的个人体会这套 impeccable 约束体系我断断续续搭了大概两个月中间推翻重来过一次。最大的教训是不要试图一步到位。我一开始想做一个大而全的检查工具结果配置复杂到我自己都不想用。后来拆成令牌层、CLI 层、扩展层、提示词层四个独立模块每个模块单独可用组合起来才形成完整体系反而落地得更顺。另一个体会是关于 AI agent 的。很多人觉得 agent 写前端“不够聪明”我的观察是它其实很聪明只是缺少约束。你给它清晰的边界它能在边界内做到相当 impeccable你不给边界它就会在无限的可能性里随机游走。所以与其抱怨 agent 写得不规范不如花时间把约束体系搭好。约束越清晰agent 的表现越稳定。最后分享一个我最近在用的技巧把 CLI 检查的违规输出格式化成一段结构化的 JSON直接作为下一轮对话的输入喂给 agent。这样 agent 不需要理解自然语言的错误描述直接读结构化数据就能精准定位问题。实测下来修正轮次从平均 2.3 轮降到了 1.4 轮省了不少来回。这套东西后续还可以往两个方向扩展。一是把视觉回归测试接进来用截图对比的方式抓出 CLI 和扩展都覆盖不到的布局偏差二是把令牌体系跟设计工具打通让设计师改完稿子后令牌自动同步省掉手动对齐的环节。这两个方向我还在摸索等跑通了再另开一篇聊。