企业官网建设流程全解析

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*(\d+px)/g); if (spacingMatches) { spacingMatches.forEach(match => { const value = match.match(/(\d+px)/)[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: false

allow_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 常见问题速查表

6. 一些踩坑之后的个人体会

这套 impeccable 约束体系我断断续续搭了大概两个月，中间推翻重来过一次。最大的教训是：不要试图一步到位。我一开始想做一个大而全的检查工具，结果配置复杂到我自己都不想用。后来拆成令牌层、CLI 层、扩展层、提示词层四个独立模块，每个模块单独可用，组合起来才形成完整体系，反而落地得更顺。

另一个体会是关于 AI agent 的。很多人觉得 agent 写前端“不够聪明”，我的观察是它其实很聪明，只是缺少约束。你给它清晰的边界，它能在边界内做到相当 impeccable；你不给边界，它就会在无限的可能性里随机游走。所以与其抱怨 agent 写得不规范，不如花时间把约束体系搭好。约束越清晰，agent 的表现越稳定。

最后分享一个我最近在用的技巧：把 CLI 检查的违规输出格式化成一段结构化的 JSON，直接作为下一轮对话的输入喂给 agent。这样 agent 不需要理解自然语言的错误描述，直接读结构化数据就能精准定位问题。实测下来，修正轮次从平均 2.3 轮降到了 1.4 轮，省了不少来回。

这套东西后续还可以往两个方向扩展。一是把视觉回归测试接进来，用截图对比的方式抓出 CLI 和扩展都覆盖不到的布局偏差；二是把令牌体系跟设计工具打通，让设计师改完稿子后令牌自动同步，省掉手动对齐的环节。这两个方向我还在摸索，等跑通了再另开一篇聊。