企业官网建设流程全解析

1. 从"impeccable"这个词说起：它到底想解决什么问题

第一次看到"impeccable"这个词被拿来命名一个开发工具，我的反应是：这名字起得挺狂。impeccable 在英文里的意思是"无可挑剔的、完美的"，一个工具敢叫这个名字，要么是营销噱头，要么是真有两把刷子。实际用下来一段时间之后，我的判断偏向后者——它确实在解决一个很具体的痛点：AI coding agents 生成的前端代码，质量参差不齐，而 impeccable 试图把"设计品味"这件事变成可执行、可校验的规则。

先把话说清楚：impeccable 不是一个 AI 模型，也不是一个代码生成器。它更像是一层"设计质量守门员"，夹在你的 AI coding agent（比如各种 CLI 形态的编码助手）和最终产出的前端代码之间。你让 AI 写一个登录页、一个仪表盘、一个落地页，AI 会给你一堆能跑但很丑的代码——间距随意、颜色乱配、层级混乱、响应式一塌糊涂。impeccable 要做的事情，就是把这些"能跑但难看"的产出，往"能跑且好看"的方向拉。

它主要面向三类人：第一类是用 AI 辅助写前端但自己设计功底一般的开发者，你懂逻辑但配色和排版总是差口气；第二类是独立开发者和小团队，没有专职设计师，但又不想产品看起来像半成品；第三类是对前端交付质量有要求的技术负责人，希望团队用 AI 提效的同时，别把代码质量拉垮。

关键词里出现的 CLI、browser extension、frontend design、AI coding agents，基本勾勒出了它的形态：以命令行工具为核心入口，可能配合浏览器扩展做预览和校验，服务于 AI 编码代理的前端设计环节。下面我会把它拆开讲透，包括它背后的设计逻辑、怎么用、踩过哪些坑，以及为什么我觉得"设计规则可执行化"这个思路值得所有做 AI 辅助开发的人认真对待。

2. 核心设计思路拆解：为什么是"规则引擎"而不是"再训一个模型"

2.1 用规则约束 AI，而不是用 AI 约束 AI

很多人第一反应是：AI 写的前端不好看，那就再上一个 AI 去修不就行了？这个思路听起来顺，但实际做起来问题很大。我试过让一个模型去"评审"另一个模型生成的前端代码，结果经常是评审模型说"整体不错，建议优化间距"，然后你问它具体改成多少 px，它给你一个模棱两可的答案。AI 评审 AI 的最大问题是不可复现——同样的代码，你问两次，它给你两个不同的修改建议，这在工程上是灾难。

impeccable 走的是另一条路：把设计规范沉淀成确定性的规则。比如"相邻元素的间距必须落在 4px 的倍数网格上"、"正文行高不低于 1.5"、"同一页面主色不超过 3 种"、"按钮的最小点击区域不小于 44x44px"。这些规则是死的，可校验、可复现、可版本管理。AI 负责生成，规则负责把关，各司其职。

这个思路的好处在于：规则是可以被团队讨论、被沉淀、被继承的。你今天跟 AI 说"间距用 8 的倍数"，明天换个人用同样的工具，规则还在，产出风格就一致。而如果你依赖 AI 的"品味"，那品味是飘的，今天这样明天那样。

2.2 为什么选择 CLI 作为核心形态

关键词里 CLI 排在很前面，这不是偶然。我分析下来，选 CLI 有几个硬理由：

• 可嵌入工作流：CLI 能被塞进 git hook、CI 流水线、npm scripts，AI 生成代码后自动跑一遍校验，不合格就拦下来。浏览器扩展做不到这一点，它只能在你打开页面时提示，属于"事后诸葛亮"。
• 对 AI agent 友好：现在的 AI coding agents 大多在终端里跑，它们天然能调用 CLI 命令。你让 agent 生成完代码后自己跑一遍impeccable check，它就能根据输出自我修正，形成闭环。这是浏览器扩展给不了的。
• 无头环境可用：服务器上、容器里、远程开发机上，CLI 都能跑，浏览器扩展必须有图形界面。

所以 CLI 是"主干"，浏览器扩展是"辅助"。扩展的价值在于可视化预览和即时反馈——你在浏览器里看到页面，扩展实时标出哪些地方违反了规则，点一下能看到具体是哪条规则、建议怎么改。两者配合，一个管"批量拦截"，一个管"交互调试"。

2.3 与 AI coding agents 的协作模式

这里要重点讲一下 impeccable 和 AI coding agents 的关系，因为这是它最核心的使用场景。现在的编码代理（各种 CLI 形态的助手）能力很强，你给它一句话它能给你生成一整个组件。但它有个通病：它不知道你的设计系统长什么样。

impeccable 的解法是：把设计约束前置到 agent 的上下文里。具体做法通常是在项目根目录放一份配置文件（类似.impeccablerc或写进 agent 的规则文件），里面声明你的设计 token——间距刻度、颜色变量、字体栈、圆角规范、断点设置。agent 在生成代码前读到这些约束，生成时就会尽量遵守；生成后再跑一遍 CLI 校验，双重保险。

我实测下来，加了约束之后 AI 生成的前端代码返工率能降一大截。以前生成一个卡片组件，间距、阴影、圆角全靠它自由发挥，你得手动调半天；现在它知道你的间距是 4/8/12/16/24/32 这套刻度，圆角只有 4 和 8 两档，产出直接就能用。

3. 核心能力与实操要点：规则到底管哪些事

3.1 间距与网格系统：最容易被 AI 搞砸的地方

AI 生成前端代码时，间距是最随意的。你让它写个卡片，它可能给你padding: 13px、margin-top: 7px、gap: 11px这种数字。单看没问题，放一起就乱，因为没有统一的节奏感。

impeccable 的间距规则通常基于一个基础单位（base unit），常见的是 4px 或 8px。所有间距必须是这个单位的整数倍。为什么是 4 或 8？因为屏幕像素密度和人类视觉对节奏的感知，4px 网格在大多数设备上能保证元素对齐不出现半像素模糊，8px 网格则更宽松、更适合大屏。

实操上，你需要在配置里声明你的间距刻度，比如：

{ "spacing": { "baseUnit": 4, "scale": [0, 4, 8, 12, 16, 24, 32, 48, 64] } }

然后 CLI 校验时，会扫描你的 CSS/样式代码，找出所有不在刻度上的间距值，报出来让你改。注意：这里有个坑，很多 UI 库自带的组件内部间距是写死的，不遵守你的刻度。我的做法是把这些第三方组件的间距用 CSS 变量覆盖掉，或者在配置里加白名单，忽略node_modules里的文件。

提示：间距规则不要一上来就卡得太死。我建议先跑一遍"只报告不拦截"模式，看看项目里有多少违规，心里有数之后再逐步收紧。一上来就全拦截，你会被报错淹没。

3.2 颜色系统：从"随便调"到"有据可依"

颜色是第二个重灾区。AI 生成代码时，如果你不给它颜色变量，它会直接写十六进制值，而且经常写出#3b82f6、#3c83f7、#3a81f5这种肉眼几乎分不出来的"近似色"。一个项目里出现十几个蓝色，视觉上就散了。

impeccable 的颜色规则一般包含几层：

• 主色数量限制：一个页面/组件的主色调不超过 2-3 种，避免花哨。
• 对比度校验：文字和背景的对比度要满足可访问性标准（WCAG 的 AA 级通常是 4.5:1，大字号 3:1）。这条规则特别实用，AI 经常生成浅灰字配白底，看着"高级"但根本看不清。
• 禁止硬编码：颜色必须引用设计 token（CSS 变量或主题对象），不能直接写死十六进制值。

对比度这块我要多说一句，因为它是唯一一条有客观标准、不依赖主观审美的规则。WCAG 的对比度计算公式是：

对比度 = (L1 + 0.05) / (L2 + 0.05)

其中 L 是相对亮度，需要先把 sRGB 值转成线性值再算。你不用自己手算，impeccable 这类工具会帮你算。但你要知道为什么是 4.5:1——这是大量可用性测试得出的经验值，低于这个数，视力正常的人在光线稍差的环境下读起来就费劲，视力受损的用户更吃力。

3.3 排版与层级：让页面"有主次"

排版规则管的是字号、字重、行高、字间距这套东西。AI 生成代码时常见的毛病是层级扁平——标题和正文差不多大，重点和次要信息一个样，用户扫一眼不知道看哪。

impeccable 的排版规则通常要求：

• 字号阶梯：定义一套有限的字号（比如 12/14/16/20/24/32/48），不允许出现 17px、19px 这种"野生"字号。
• 行高比例：正文行高建议 1.5-1.7，标题可以紧一点 1.2-1.3。行高太紧读起来压抑，太松则散。
• 字重层级：一个页面里字重不超过 3 档，通常 400（正文）、500/600（强调）、700（标题）就够了。

我个人的经验是，排版规则对"AI 味"的消除效果最明显。AI 生成的页面之所以一眼能看出来是 AI 做的，很大原因就是排版没有节奏——所有文字挤在一起，没有呼吸感。加上排版约束后，页面立刻"专业"了不少。

3.4 响应式与断点：别让 AI 只顾一个尺寸

AI 生成前端时，如果你不特别说明，它默认按桌面宽度写，移动端要么不管，要么随便加个@media糊弄。impeccable 的响应式规则会检查：

• 断点是否使用了预定义的集合（比如 640/768/1024/1280），而不是随手写@media (max-width: 823px)。
• 关键元素在小屏下是否溢出：比如固定宽度的容器、超长的表格、不换行的文本。
• 点击目标尺寸：移动端按钮、链接的点击区域不小于 44x44px（这是苹果和谷歌都推荐的最小值，因为手指触控的精度有限）。

注意：响应式校验是最难做自动化的一条，因为"溢出"需要真实渲染才能判断。impeccable 的浏览器扩展在这里就派上用场了——它能在真实浏览器里加载页面，模拟不同视口，把溢出的元素标出来。CLI 只能做静态检查，比如看有没有用预定义断点。

4. 完整实操流程：从零接入 impeccable

4.1 环境准备与安装

假设你已经在用某个 CLI 形态的 AI 编码助手，项目是一个前端工程（React/Vue/原生都行）。接入 impeccable 的第一步是安装。CLI 工具的安装方式通常是包管理器：

# 以 npm 为例，具体包名以官方为准 npm install -D impeccable-cli

或者全局安装：

npm install -g impeccable-cli

安装完之后，跑一下impeccable --version确认装上了。如果提示命令找不到，检查一下 npm 的全局 bin 目录有没有加到 PATH 里——这是新手最常踩的坑，尤其在 Windows 上。

浏览器扩展的安装一般是从扩展商店装，或者开发者模式下加载本地包。装完之后，扩展会在你打开本地开发服务器（比如localhost:3000）时自动激活，在页面角落显示一个面板。

4.2 初始化配置文件

在项目根目录跑初始化命令：

impeccable init

它会问你几个问题：基础间距单位是多少、用不用暗色模式、目标可访问性等级是 AA 还是 AAA、要不要生成示例配置。回答完之后，根目录会多出一个配置文件，大概长这样：

{ "spacing": { "baseUnit": 4, "scale": [0, 4, 8, 12, 16, 24, 32, 48, 64] }, "colors": { "maxPrimaryColors": 3, "contrastLevel": "AA", "allowHardcoded": false }, "typography": { "fontSizes": [12, 14, 16, 20, 24, 32, 48], "lineHeight": { "body": 1.6, "heading": 1.25 }, "maxFontWeights": 3 }, "breakpoints": [640, 768, 1024, 1280], "ignore": ["node_modules/**", "dist/**"] }

这份配置是整个工具的灵魂，它决定了什么算"合格"。我的建议是：第一版配置别照抄网上的，按你项目实际情况来。如果你项目已经在用 Tailwind，那间距刻度直接对齐 Tailwind 的默认刻度就行；如果你用的是 Ant Design 或 Element，颜色和间距对齐它们的 token。工具是来适配你的，不是让你推倒重来。

4.3 跑第一遍校验

配置好了之后，跑：

impeccable check ./src

它会扫描src目录下的样式相关文件，输出一份报告。报告一般分三档：error（必须改）、warning（建议改）、info（提示）。第一次跑，你大概率会看到满屏的 warning，别慌，这很正常。

我建议的处理顺序是：

1. 先看 error：这些通常是硬伤，比如对比度不达标、点击区域太小，直接影响可用性，优先修。
2. 再看 warning 里的间距和颜色：这两类数量最多，但改起来机械，可以批量处理。
3. info 可以先放着：比如"建议使用语义化标签"这种，不影响功能。

4.4 接入 AI agent 的工作流

这是最关键的一步。你要让 AI agent 在生成代码时就知道这些规则。做法通常有两种：

方式一：把配置写进 agent 的规则文件。很多 CLI 编码助手支持项目级的规则文件（比如AGENTS.md、.cursorrules之类），你把 impeccable 的核心约束用自然语言写进去：

本项目前端代码必须遵守以下设计规范： - 所有间距必须是 4px 的整数倍，优先使用 4/8/12/16/24/32/48/64 - 颜色必须引用 CSS 变量，禁止硬编码十六进制值 - 正文字号 16px，行高 1.6；标题字号从 20/24/32/48 中选 - 文字与背景对比度不低于 4.5:1 - 移动端点击区域不小于 44x44px

方式二：让 agent 生成后自动跑校验。在 agent 的工作流里加一步，生成完代码后执行impeccable check，把输出喂回给 agent，让它自己修。这个闭环一旦跑通，效率提升非常明显。

我实测下来，方式一 + 方式二组合使用效果最好。方式一让 agent 少犯错，方式二兜底。只靠方式二的话，agent 可能要来回修好几轮；只靠方式一的话，agent 偶尔还是会"忘记"。

4.5 浏览器扩展的实时预览

开发过程中，浏览器扩展提供即时反馈。你改一行样式，保存，页面刷新，扩展面板上对应的规则项会实时更新——绿了就是过了，红了就是没过。点红色的项，它会高亮页面上出问题的元素，并告诉你当前值和建议值。

这个交互对调间距和颜色特别有用。因为这两类问题在代码里看不出来，必须看到渲染结果才知道。比如两个元素间距 12px 还是 16px，代码里就差一个数字，但视觉上差别明显。扩展让你边调边看，比盲改快得多。

5. 常见问题与排查技巧实录

5.1 校验报错太多，怎么分批处理

这是新手最常问的问题。我的做法是按规则类型分批，而不是按文件分批。先集中把所有对比度问题修完，再集中修间距，再集中修颜色。因为同一类问题的修法是一样的，批量处理有肌肉记忆，效率高；混着修的话，你脑子要不停切换，反而慢。

具体操作上，可以用 CLI 的过滤参数：

# 只看对比度问题 impeccable check ./src --rule contrast # 只看间距问题 impeccable check ./src --rule spacing

5.2 第三方组件库的样式冲突

UI 库（Ant Design、Element Plus、MUI 等）自带的组件内部样式往往不遵守你的规则。比如它的按钮 padding 是 7px 15px，你的规则要求 4 的倍数，就会报错。

处理方式有三种，按推荐程度排序：

1. 白名单忽略：在配置的ignore里加上node_modules/**，眼不见为净。缺点是你就管不到第三方组件了。
2. CSS 变量覆盖：如果库支持主题定制，通过覆盖 CSS 变量把它的间距、颜色拉到你的体系里。这是最干净的做法。
3. 局部禁用：在特定文件顶部加注释禁用某条规则，比如/* impeccable-disable spacing */。适合个别确实没法改的地方。

提示：不要为了"全绿"去改第三方库的源码，那是给自己挖坑。升级库的时候你的修改全丢，而且容易出诡异 bug。

5.3 AI agent 不遵守规则怎么办

有时候你把规则写进上下文了，agent 生成代码时还是我行我素。原因通常有几个：

• 规则太长，被截断了：agent 的上下文窗口有限，你塞太多规则进去，后面的可能被忽略。解决办法是把规则精简到最核心的 5-8 条，或者用配置文件让 agent 按需读取。
• 规则表述模糊：写"间距要合理"，agent 不知道什么叫合理。写"间距必须是 4 的倍数"，它才懂。规则要具体、可量化。
• agent 版本问题：不同 agent 对规则文件的读取能力不一样，有的支持项目级规则，有的只认全局配置。确认你用的 agent 支持哪种方式。

5.4 常见问题速查表

5.5 几个我踩过的坑

坑一：把 baseUnit 设成 1px。想着"1px 的倍数什么都能过"，结果规则形同虚设，等于没约束。baseUnit 一定要有实际约束力，4 或 8 是经过验证的选择。

坑二：对比度规则设成 AAA。AAA 要求 7:1，非常严格，很多正常的设计都过不了。除非你的产品有明确的强可访问性需求，否则 AA（4.5:1）就够了。设太严会导致你为了过检把设计改得很难看。

坑三：忽略动态内容。CLI 静态扫描只能看代码里写死的样式，但很多样式是运行时算出来的（比如根据数据动态设颜色）。这类问题只能靠浏览器扩展在真实渲染时抓。所以CLI 和扩展要配合用，不能只靠一个。

坑四：规则配置没有版本管理。配置文件一定要提交到 git，因为它是团队共识的载体。谁改了规则、为什么改，都要有记录。我见过团队里有人偷偷把规则放宽，结果产出质量悄悄下滑，很久才发现。

6. 我对这套思路的看法和后续扩展

用了一段时间 impeccable 之后，我最大的感受是：AI 辅助开发的上限，不取决于模型多强，而取决于你给它划的边界多清晰。模型是个能力很强但没主见的执行者，你不告诉它边界，它就自由发挥，发挥出来的东西质量全看运气。你给它清晰的、可校验的边界，它就能稳定产出及格线以上的东西。

这套"规则引擎 + AI 生成 + 自动校验"的模式，我觉得不止适用于前端设计。后端代码规范、API 设计、数据库 schema、甚至文档写作，都可以套这个思路——把领域内的最佳实践沉淀成可执行的规则，让 AI 在规则内发挥。这是我认为未来 AI 辅助开发最务实的方向之一。

后续如果要扩展，我会往两个方向走：一是把规则和设计系统打通，让 impeccable 直接读取 Figma 或设计 token 文件，设计改了规则自动更新，不用手动同步；二是积累项目自己的规则库，每个项目踩过的坑都沉淀成一条规则，时间长了这就是团队最宝贵的资产。

最后分享一个小技巧：规则不要一次加太多，一次加一条，观察一周。加太多你会被报错淹没，然后就想全部关掉。一条一条来，让团队慢慢适应，规则才留得住。这个节奏感，比规则本身还重要。