企业官网建设流程全解析

1. 项目缘起：一个叫“impeccable”的AI编码代理到底想解决什么问题

第一次看到“impeccable”这个词，是在一个前端开发者的小圈子里。有人丢了一张截图，说“这玩意儿生成的界面居然不用我手动调间距”。截图里是一个用自然语言描述需求后自动生成的登录页，按钮的圆角、阴影、字体层级、留白节奏，全都对得上主流设计系统的规范。当时我的第一反应是：又一个套壳的AI代码生成器吧。但仔细看完它的交互方式之后，我改变了判断。

impeccable 本质上是一个面向 AI coding agents 的前端设计约束层。它不是一个独立的代码编辑器，也不是一个全新的框架，而是一套通过 CLI 和浏览器扩展协同工作的工具链，核心目标是让 AI 代理在生成前端代码时，能够遵循一套“无可挑剔”的设计规范。换句话说，它解决的是当前 AI 编码代理最大的痛点之一：代码能跑，但界面难看。

这个问题有多普遍？你随便让一个主流的 AI 编码代理生成一个表单页面，大概率会得到这样的结果：输入框宽度撑满整个容器，按钮紧贴着输入框没有呼吸感，标题和正文的字号差距要么太大要么太小，颜色用的是默认的蓝色或者黑色，整体看起来像是二十年前的网页。代码逻辑没问题，但前端设计层面完全不及格。impeccable 要做的就是在这中间加一层“设计翻译层”，把设计系统的最佳实践注入到 AI 代理的生成过程中。

适合谁来用这个项目？我梳理了三类人。第一类是独立开发者或者小团队的全栈工程师，他们能写后端能写逻辑，但前端设计是短板，又请不起专业设计师。第二类是已经在用 AI coding agents 做快速原型的开发者，他们希望原型阶段就能有一个体面的界面，而不是等到后期再返工。第三类是对前端设计系统有兴趣、想了解如何用工具约束 AI 输出质量的技术管理者。如果你属于这三类中的任何一类，impeccable 值得你花时间研究。

2. 核心机制拆解：CLI 与浏览器扩展如何协同工作

2.1 为什么是 CLI 加浏览器扩展的组合

impeccable 选择 CLI 加浏览器扩展的架构，这个决策背后有很实际的考量。CLI 负责的是项目初始化、配置管理、设计令牌的注入和构建流程的集成。浏览器扩展负责的是实时预览、设计规范的视觉反馈和快速迭代。两者分工明确，各司其职。

为什么不用纯 CLI？因为前端设计是一个高度视觉化的过程。你在命令行里敲再多的参数，也不如直接在浏览器里看到效果来得直观。为什么不用纯浏览器扩展？因为设计令牌的管理、项目配置的持久化、与构建工具的集成，这些都需要文件系统级别的操作能力，浏览器扩展做不到。

这个组合让我想起了 codex cli 和 trae cli 这类工具的设计思路。它们都是把命令行的高效性和可视化工具的直接性结合起来。impeccable 在这个基础上更进一步，它不只是让你看到代码运行的结果，而是让你看到设计规范被应用之后的效果。

2.2 设计令牌系统：impeccable 的核心资产

impeccable 最核心的资产是它的设计令牌系统。设计令牌这个概念在前端圈子里不算新，但 impeccable 的做法有自己的特点。它把设计令牌分成了几个层级：基础令牌、语义令牌和组件令牌。

基础令牌是最底层的原子单位，比如颜色值、字号、间距单位、圆角半径、阴影参数。语义令牌是在基础令牌之上的一层抽象，比如“主按钮背景色”对应到某个具体的基础颜色令牌，“卡片内边距”对应到某个具体的间距令牌。组件令牌则是针对特定组件的组合，比如“登录表单”的完整样式定义。

这种分层的好处是，当你想调整整个项目的视觉风格时，只需要修改基础令牌，所有引用这些基础令牌的语义令牌和组件令牌都会自动更新。这比在每个组件里硬编码样式值要高效得多，也更容易维护。

impeccable 内置了一套默认的设计令牌，这套令牌是基于主流设计系统的最佳实践提炼出来的。我对比了一下，它的间距系统用的是 4px 基准的倍数序列，字号用的是 1.25 的模数比例，颜色系统包含了完整的语义色板。这些默认值可以直接用，也可以根据项目需求覆盖。

2.3 与 AI 编码代理的集成方式

impeccable 与 AI 编码代理的集成方式，是我认为这个项目最有价值的部分。它不是简单地给 AI 代理一个提示词模板，而是通过 CLI 在项目里生成一个配置文件，这个配置文件会被 AI 代理读取，从而约束它的输出。

具体来说，当你在项目里运行 impeccable 的初始化命令后，它会生成一个.impeccable目录，里面包含了设计令牌的定义、组件样式的映射规则、以及一份给 AI 代理的指令文件。这份指令文件用自然语言描述了设计规范的核心要点，比如“所有按钮必须有至少 12px 的内边距”、“标题和正文的字号比例不得小于 1.5”、“相邻元素之间的间距必须是 4px 的倍数”。

AI 代理在生成代码时，会读取这份指令文件，并在生成过程中应用这些约束。这比在提示词里临时写几句“请让界面好看一点”要可靠得多。因为提示词是临时的、模糊的，而配置文件是持久的、精确的。

我实测下来，用这种方式约束 AI 代理，生成的前端代码在视觉质量上有明显的提升。当然，它不能保证 100% 符合设计规范，但至少能避免那些最离谱的问题，比如元素重叠、间距混乱、颜色刺眼。

3. 从零开始：impeccable 的完整实操流程

3.1 环境准备与 CLI 安装

在开始之前，你需要确认本地环境满足基本要求。Node.js 版本建议在 18 以上，npm 或者 pnpm 都可以。如果你用的是 pnpm，后续的依赖安装会快很多。另外，你需要一个支持扩展安装的浏览器，Chrome 或者 Edge 都可以。

安装 impeccable CLI 的方式很直接：

npm install -g impeccable-cli

或者如果你用 pnpm：

pnpm add -g impeccable-cli

安装完成后，运行impeccable --version确认安装成功。如果提示命令找不到，检查一下全局安装路径是否在系统的 PATH 环境变量里。这个问题在 Windows 上比较常见，macOS 和 Linux 一般不会有。

注意：如果你之前安装过其他类似的 CLI 工具，比如 codex cli 或者 openspec cli，注意检查是否有命令名冲突。impeccable 的命令名就是impeccable，一般不会冲突，但保险起见还是确认一下。

3.2 项目初始化与设计令牌配置

进入你的项目根目录，运行初始化命令：

impeccable init

这个命令会做几件事。第一，在项目根目录创建.impeccable目录。第二，生成默认的设计令牌文件tokens.json。第三，生成 AI 代理指令文件agent-instructions.md。第四，如果检测到项目里有package.json，会提示你是否安装浏览器扩展的配套依赖。

初始化完成后，你会看到.impeccable目录的结构是这样的：

.impeccable/ ├── tokens.json ├── agent-instructions.md ├── components/ │ └── defaults.json └── config.json

tokens.json是设计令牌的核心文件。我建议你打开看一下，了解它的结构。默认的令牌文件包含了颜色、字号、间距、圆角、阴影等几个大类。每个令牌都有一个名称和一个值。比如：

{ "color": { "primary": "#2563eb", "secondary": "#64748b", "background": "#ffffff", "surface": "#f8fafc" }, "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px" } }

如果你想自定义设计令牌，直接修改这个文件就行。修改之后，运行impeccable sync命令，它会重新生成agent-instructions.md文件，确保 AI 代理读取到的是最新的设计规范。

3.3 浏览器扩展的安装与使用

浏览器扩展的安装方式取决于你用的浏览器。在 Chrome 上，你需要打开扩展管理页面，开启开发者模式，然后加载.impeccable目录下的extension文件夹。这个文件夹在初始化时可能不会自动生成，你需要运行impeccable extension:build命令来构建扩展。

构建完成后，在浏览器里加载这个扩展。扩展安装成功后，你会在浏览器的工具栏看到 impeccable 的图标。点击图标，会弹出一个面板，显示当前页面的设计规范检查结果。

这个面板会列出当前页面上所有不符合设计规范的元素，比如“按钮内边距小于 12px”、“标题字号与正文字号比例不足 1.5”、“相邻元素间距不是 4px 的倍数”。你可以点击每个问题，扩展会高亮对应的元素，并在面板里显示建议的修正值。

我实际用下来的感受是，这个扩展在开发阶段特别有用。你不需要等到代码写完再回头检查设计问题，而是在开发过程中就能实时看到哪些地方不符合规范。这比事后返工要高效得多。

3.4 与 AI 编码代理的配合流程

impeccable 与 AI 编码代理的配合流程，我总结成了三个步骤。

第一步，在项目里初始化 impeccable，确保.impeccable目录存在，并且agent-instructions.md文件是最新的。

第二步，在给 AI 代理的提示词里，明确要求它读取.impeccable/agent-instructions.md文件，并遵循其中的设计规范。比如你可以这样写提示词：“请根据.impeccable/agent-instructions.md中的设计规范，生成一个用户登录页面，包含邮箱输入框、密码输入框和登录按钮。”

第三步，AI 代理生成代码后，在浏览器里打开页面，用 impeccable 扩展检查设计规范的符合程度。如果有问题，把问题反馈给 AI 代理，让它修正。

这个流程的关键在于第二步。很多人在用 AI 代理时，习惯把所有的要求都写在提示词里。但提示词的长度是有限的，而且 AI 代理对提示词的记忆并不稳定。把设计规范放在一个独立的文件里，让 AI 代理去读取，效果会好很多。

4. 设计令牌的深度定制：让 impeccable 适配你的项目

4.1 颜色系统的定制策略

默认的颜色系统是一套通用的蓝色系配色，适合大多数企业级应用。但如果你的项目有品牌色，或者你需要一套深色主题，就需要定制颜色令牌。

定制颜色令牌时，我建议遵循一个原则：先定义基础色板，再定义语义颜色。基础色板是你项目中所有可能用到的颜色值，语义颜色是这些颜色值在具体场景下的应用。

比如，你可以先定义一套基础色板：

{ "color": { "blue-50": "#eff6ff", "blue-100": "#dbeafe", "blue-500": "#3b82f6", "blue-600": "#2563eb", "blue-700": "#1d4ed8", "gray-50": "#f9fafb", "gray-100": "#f3f4f6", "gray-500": "#6b7280", "gray-900": "#111827" } }

然后定义语义颜色：

{ "semantic": { "color": { "primary": "{color.blue-600}", "primary-hover": "{color.blue-700}", "background": "{color.gray-50}", "surface": "#ffffff", "text-primary": "{color.gray-900}", "text-secondary": "{color.gray-500}" } } }

这种引用式的定义方式，让颜色系统变得非常灵活。当你想要调整主色调时，只需要修改primary的引用目标，所有使用primary的地方都会自动更新。

4.2 间距系统的节奏控制

间距系统是前端设计中最容易被忽视，但对视觉效果影响最大的部分。impeccable 默认的间距系统是基于 4px 基准的，这个基准在大多数场景下都适用。但如果你的项目有特殊的密度要求，比如一个信息密集的后台管理系统，你可能需要调整这个基准。

调整间距系统时，我建议保持倍数序列的规律性。比如你可以用 4px 作为基准，定义 xs=4px、sm=8px、md=16px、lg=24px、xl=32px、2xl=48px。这个序列的规律是每个级别大约是前一个级别的 1.5 到 2 倍。这种非线性的增长方式，比线性增长更符合视觉感知的规律。

提示：不要定义太多间距级别。我见过有的项目定义了十几个间距级别，结果开发者在选择时反而不知道该用哪个。一般来说，6 到 8 个级别就足够了。

4.3 字号与行高的搭配原则

字号和行高的搭配，是决定文本可读性的关键因素。impeccable 默认的字号系统用的是 1.25 的模数比例，也就是说每个级别的字号是前一个级别的 1.25 倍。这个比例在大多数场景下都能产生清晰的层级关系。

行高的设置有一个经验法则：字号越小，行高比例越大。比如正文的字号是 16px，行高可以设为 1.5 倍，也就是 24px。标题的字号是 32px，行高可以设为 1.2 倍，也就是 38.4px。这个法则背后的逻辑是，小字号需要更多的行间距来保证可读性，大字号本身已经足够醒目，行高可以相对紧凑一些。

在 impeccable 的令牌文件里，你可以这样定义：

{ "typography": { "fontSize": { "xs": "12px", "sm": "14px", "base": "16px", "lg": "20px", "xl": "25px", "2xl": "31px", "3xl": "39px" }, "lineHeight": { "xs": "1.5", "sm": "1.5", "base": "1.5", "lg": "1.4", "xl": "1.3", "2xl": "1.2", "3xl": "1.1" } } }

4.4 圆角与阴影的视觉语言

圆角和阴影是塑造界面视觉语言的重要元素。圆角的大小决定了界面的“性格”：小圆角显得专业、严谨，大圆角显得友好、轻松。阴影的深浅决定了界面的“层次感”：浅阴影显得轻盈，深阴影显得厚重。

impeccable 默认的圆角系统包含了 none、sm、md、lg、full 五个级别。阴影系统包含了 sm、md、lg、xl 四个级别。我建议你在定制时，先确定项目的整体视觉风格，再选择对应的圆角和阴影级别。

比如，如果你做的是一个面向消费者的应用，可以用较大的圆角（md 或 lg）和较浅的阴影（sm 或 md）。如果你做的是一个企业级后台，可以用较小的圆角（sm 或 none）和较深的阴影（md 或 lg）。

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

5.1 AI 代理不读取指令文件怎么办

这是最常见的问题。你明明在提示词里写了“请读取.impeccable/agent-instructions.md”，但 AI 代理生成出来的代码还是不符合设计规范。

排查思路是这样的。首先，确认.impeccable/agent-instructions.md文件确实存在，并且内容是最新的。运行impeccable sync命令可以强制刷新这个文件。其次，确认 AI 代理有读取项目文件的权限。有些 AI 代理默认只能读取当前打开的文件，不能读取项目里的其他文件。这种情况下，你需要把指令文件的内容直接粘贴到提示词里。最后，确认提示词的表述足够明确。不要写“请参考设计规范”，而要写“请读取.impeccable/agent-instructions.md文件，并严格遵循其中的所有设计约束”。

如果以上都确认了还是不行，那可能是 AI 代理本身的能力限制。不同的 AI 代理对长指令的遵循程度不一样。我实测下来，codex cli 和 trae cli 对这类指令的遵循程度比较好，其他一些代理可能会忽略部分约束。

5.2 设计令牌修改后不生效

修改了tokens.json文件后，发现 AI 代理生成的新代码还是用旧的设计令牌。这个问题通常是因为没有运行impeccable sync命令。

tokens.json是设计令牌的源文件，但 AI 代理读取的是agent-instructions.md文件。这两个文件之间需要通过impeccable sync命令来同步。每次修改tokens.json后，都要运行一次这个命令。

另外，如果你用的是浏览器扩展来检查设计规范，修改令牌后也需要重新加载扩展。在 Chrome 的扩展管理页面，点击 impeccable 扩展的刷新按钮即可。

5.3 浏览器扩展无法加载

浏览器扩展无法加载，通常有几个原因。第一，扩展没有构建。运行impeccable extension:build命令来构建扩展。第二，加载的目录不对。在 Chrome 的扩展管理页面，选择“加载已解压的扩展程序”，然后选择.impeccable/extension目录。第三，浏览器版本太旧。impeccable 的扩展需要 Chrome 100 以上的版本。

如果以上都确认了还是无法加载，打开 Chrome 的扩展管理页面，开启开发者模式，查看是否有错误信息。常见的错误包括 manifest 文件格式错误、权限声明缺失等。这些错误信息会帮助你定位问题。

5.4 生成的前端代码与现有项目风格冲突

impeccable 默认的设计令牌是一套通用的设计系统，可能与你现有项目的风格不一致。这种情况下，你需要定制设计令牌，让它匹配你项目的现有风格。

定制的方法是，先分析你现有项目的设计规范。打开几个典型的页面，用浏览器的开发者工具查看颜色值、字号、间距、圆角等样式属性。把这些值提取出来，填入tokens.json文件。然后运行impeccable sync命令，让 AI 代理读取新的设计规范。

这个过程可能需要几次迭代。第一次定制后，让 AI 代理生成一个测试页面，对比它和你现有页面的视觉风格。如果有差异，继续调整令牌值，直到满意为止。

5.5 常见问题速查表

6. 进阶技巧：让 impeccable 发挥更大价值

6.1 结合组件库使用

如果你的项目已经在用某个组件库，比如 Ant Design、Material UI 或者 Chakra UI，你可以把 impeccable 的设计令牌与组件库的主题配置对接起来。这样 AI 代理生成的代码不仅符合设计规范，还能直接使用组件库的组件，减少重复造轮子的情况。

具体做法是，在tokens.json里定义与组件库主题对应的令牌值。比如 Ant Design 的主色令牌是colorPrimary，你可以在 impeccable 的令牌文件里定义一个同名的令牌，值设为 Ant Design 的主色值。然后在agent-instructions.md里说明，生成代码时优先使用组件库的组件，并引用对应的设计令牌。

6.2 建立项目级的设计规范文档

impeccable 的agent-instructions.md文件是一个很好的起点，但它主要面向 AI 代理。你可以在此基础上，建立一份面向人类开发者的设计规范文档。这份文档可以包含更详细的设计原则、使用场景说明、正反示例对比。

这份文档的价值在于，它让团队里的每个开发者都能理解设计规范背后的逻辑，而不仅仅是机械地遵循规则。当开发者理解了“为什么按钮的内边距不能小于 12px”，他们在面对规范没有覆盖的场景时，也能做出合理的判断。

6.3 与代码审查流程集成

你可以把 impeccable 的设计规范检查集成到代码审查流程里。具体做法是，在 CI 流程里加一个步骤，运行impeccable lint命令，检查生成的前端代码是否符合设计规范。如果不符合，CI 流程会失败，并输出具体的问题列表。

这个做法的好处是，它把设计规范的检查自动化了，不需要人工去逐个检查。而且，它把设计规范的要求前置到了代码合并之前，避免了问题代码进入主分支。

注意：impeccable lint命令目前还在实验阶段，对某些框架的支持可能不完整。建议先在本地测试，确认效果后再集成到 CI 流程。

6.4 多主题切换的实现思路

如果你的项目需要支持多主题，比如浅色主题和深色主题，你可以通过 impeccable 的令牌系统来实现。具体做法是，定义两套语义令牌，一套对应浅色主题，一套对应深色主题。然后在config.json里配置主题切换的策略。

AI 代理在生成代码时，会读取当前激活的主题令牌，生成对应的样式。浏览器扩展在检查设计规范时，也会根据当前主题来验证。

这个方案的优点是，主题切换的逻辑被统一管理在 impeccable 的配置里，不需要在每个组件里写条件判断。当你想增加一个新主题时，只需要定义一套新的语义令牌，不需要修改组件代码。

7. 我对 impeccable 的实际使用体会

用了大概两个月的时间，我把 impeccable 集成到了自己的几个小项目里。最大的感受是，它确实能显著提升 AI 代理生成的前端代码的视觉质量。以前我需要花大量时间在提示词里描述设计细节，现在只需要维护好设计令牌文件，AI 代理就能生成基本符合规范的界面。

但 impeccable 不是银弹。它解决的是设计规范的一致性问题，不解决设计创意的问题。AI 代理生成的界面可能符合规范，但缺乏惊喜。如果你需要的是有独特视觉风格的设计，还是得靠人类设计师。

另外，impeccable 的学习曲线不算平缓。你需要理解设计令牌的概念，需要花时间定制令牌文件，需要适应与 AI 代理配合的工作流程。如果你只是偶尔用 AI 代理生成一两个页面，可能不值得投入这个学习成本。但如果你是长期依赖 AI 代理做前端开发，impeccable 值得你认真研究。

最后分享一个小技巧：在定制设计令牌时，不要一次性追求完美。先定义一套最小可用的令牌，让 AI 代理生成几个页面，看看效果。然后根据实际效果，逐步调整令牌值。这种迭代式的定制方式，比一开始就试图定义一套完整的设计系统要高效得多。