1. 项目缘起：为什么我们需要一个叫“impeccable”的东西
第一次看到“impeccable”这个词，是在一个前端群里有人甩了张截图，说“这玩意儿生成的界面比我手写的还干净”。截图里是一个命令行工具跑完之后的输出，终端里滚过几行日志，然后浏览器自动弹出一个页面，布局、间距、配色、响应式断点全都处理好了。当时我的第一反应是：又一个来抢饭碗的AI代码生成器？但仔细看完它的工作方式之后，我发现它跟市面上那些“输入一句话生成一个网站”的工具完全不是一回事。
impeccable 这个项目，从名字就能看出它的野心——“无可挑剔的”。它不是一个独立的代码生成器，而是一个面向 AI coding agents 的前端设计约束层。说得再直白一点：你平时用 Codex CLI、Claude Code、Cursor 这类工具写前端代码的时候，AI 经常会给你生成一堆“能跑但丑”的东西——间距忽大忽小、颜色搭配辣眼睛、响应式断点乱设、组件复用率极低。impeccable 要做的就是给这些 AI agent 套上一套严格的设计系统规则，让它们产出的前端代码在视觉和结构上都达到“无可挑剔”的水准。
它同时提供了CLI 工具和浏览器扩展两种形态。CLI 负责在项目初始化阶段注入设计规范、生成配置文件、校验现有代码是否符合规则；浏览器扩展则负责在开发过程中实时预览 AI 生成的界面，并且把视觉反馈直接回传给 agent，形成一个闭环。这个思路很聪明——它没有试图取代 AI coding agent，而是把自己定位成 agent 的“设计品味外挂”。
适合谁来用？如果你满足下面任意一条，这个项目就值得你花时间研究：
- 日常用 Codex CLI、Claude Code、Trae CLI 等工具写前端，但每次都要手动调样式
- 团队里没有专职设计师，但产品对 UI 质量有要求
- 想给 AI agent 建立一套可复用的设计约束，而不是每次靠 prompt 碰运气
- 对 CLI 工具链和浏览器扩展的配合方式感兴趣，想自己搭一套类似的工作流
我花了大概两周时间把这个项目从安装到深度定制跑了一遍，中间踩了不少坑，也总结了一些官方文档里没写的经验。下面按照我的实际使用顺序，把整个东西拆开来讲。
2. 核心架构拆解：CLI 和浏览器扩展到底怎么配合
2.1 整体设计思路：约束而非生成
市面上大多数 AI 前端工具的逻辑是“你给我描述，我给你代码”。impeccable 的逻辑是“你已经有 AI 在写代码了，我来告诉它什么叫做得好”。这个定位差异决定了它的技术选型和交互方式。
它不直接生成组件代码，而是做三件事：
- 定义设计令牌（Design Tokens）：把间距、字号、颜色、圆角、阴影这些基础视觉参数固化成一个 JSON 配置文件，AI agent 在生成代码时必须引用这些令牌，而不是随手写
margin: 13px这种魔法数字。 - 提供组件契约（Component Contracts）：对按钮、输入框、卡片、弹窗这些高频组件，定义它们的变体、状态和组合规则。AI 生成组件时必须遵守这些契约，不能自己发明一套。
- 实时视觉校验：浏览器扩展在页面渲染后抓取实际的计算样式，跟设计令牌做比对，把偏差报告回传给 CLI，CLI 再把这个反馈注入到 agent 的上下文里。
这个闭环的关键在于反馈的实时性。传统做法是你让 AI 写代码，写完你打开浏览器看，觉得不对再回去改 prompt。impeccable 把这个循环缩短到了秒级——扩展检测到偏差，CLI 立刻把偏差信息塞给 agent，agent 下一轮生成就会自动修正。
2.2 为什么选择 CLI + 浏览器扩展的双形态
我一开始也有疑问：为什么不做成一个纯 CLI 工具，或者一个纯浏览器插件？用下来之后理解了，这两种形态各自解决的是不同阶段的问题。
CLI 解决的是项目级、一次性、可版本控制的问题。比如：
- 初始化项目时注入设计令牌文件
- 在 CI 流程里校验代码是否符合设计规范
- 批量扫描现有组件，找出不符合令牌的硬编码样式
- 跟 Codex CLI、Trae CLI 等工具集成，在 agent 启动时自动加载约束
浏览器扩展解决的是运行时、实时、视觉层面的问题。比如：
- AI 刚生成一个页面，扩展立刻渲染并截图
- 抓取实际计算样式，跟令牌做 diff
- 把视觉偏差以结构化数据的形式回传给 CLI
- 在页面上直接标注出有问题的元素，方便人工复核
两者通过一个本地 WebSocket 服务通信。CLI 启动时会在本地起一个轻量服务，扩展连接到这个服务，双方交换设计令牌和校验结果。这个架构的好处是解耦——你可以只用 CLI 做静态校验，也可以只用扩展做视觉预览，但两者一起用的时候效果最好。
2.3 跟主流 AI coding agent 的集成方式
impeccable 目前对 Codex CLI 的支持最完善，其次是 Claude Code 和 Trae CLI。集成方式分两种：
第一种是包装模式（Wrapper Mode）。你用impeccable run codex代替直接运行codex，impeccable 会在启动 codex 之前把设计令牌和组件契约注入到系统提示里，并且在 codex 运行过程中拦截它的文件写入操作，对生成的 CSS/JSX 做实时校验。如果发现硬编码样式，会直接在终端里警告，并且把修正建议追加到 codex 的下一轮上下文里。
第二种是插件模式（Plugin Mode）。对于支持插件系统的 agent（比如 Claude Code 的 hooks 机制），impeccable 注册一个 post-write hook，在 agent 写完文件之后自动触发校验。这种方式对 agent 本身的侵入性更小，但反馈延迟会稍微高一点。
我实测下来，包装模式的效果更直接，因为它在生成过程中就能干预，而不是等写完了再改。但包装模式对 agent 的版本有要求，Codex CLI 需要 0.9 以上，Trae CLI 需要 1.2 以上。如果你用的是比较老的版本，建议先升级。
注意：impeccable 的包装模式会修改 agent 的启动参数，如果你在 agent 里配置了自定义的模型端点或者代理设置，需要先在 impeccable 的配置文件里同步这些设置，否则包装之后可能会连不上模型。
3. 从零开始：CLI 安装与项目初始化实操
3.1 安装方式选择与版本管理
impeccable 的 CLI 目前通过 npm 分发，包名就是impeccable。安装方式有三种，我分别试过，说一下各自的适用场景。
# 方式一：全局安装 npm install -g impeccable # 方式二：项目内安装（推荐） npm install --save-dev impeccable # 方式三：直接用 npx 运行（不推荐长期使用） npx impeccable init全局安装的好处是任何目录下都能直接用impeccable命令，适合你同时在多个项目里切换。但缺点是版本管理麻烦——不同项目可能需要不同版本的 impeccable，全局只能装一个。项目内安装的好处是版本跟项目走，package.json里锁死版本，团队协作时不会出现“我这边能跑你那边报错”的情况。npx 方式适合快速试用，但每次都要下载，而且没法用包装模式启动 agent。
我最后选的是项目内安装，然后在package.json的 scripts 里加了几条快捷命令：
{ "scripts": { "design:init": "impeccable init", "design:check": "impeccable check", "design:watch": "impeccable watch", "agent:codex": "impeccable run codex" } }这样团队里任何人 clone 下来之后，跑npm run design:init就能初始化设计系统，跑npm run agent:codex就能带着约束启动 Codex CLI。
3.2 初始化配置：设计令牌文件的结构与参数含义
impeccable init会在项目根目录生成一个.impeccable文件夹，里面包含三个核心文件：
tokens.json：设计令牌定义contracts.json：组件契约定义config.json：CLI 和扩展的运行时配置
tokens.json是整个系统的基石，它的结构设计得很讲究。我拿一个实际项目的配置来举例：
{ "spacing": { "unit": 4, "scale": [0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64], "semantic": { "xs": 1, "sm": 2, "md": 4, "lg": 6, "xl": 8 } }, "typography": { "fontFamily": { "sans": "Inter, system-ui, sans-serif", "mono": "JetBrains Mono, monospace" }, "fontSize": { "xs": 12, "sm": 14, "base": 16, "lg": 18, "xl": 20, "2xl": 24, "3xl": 30 }, "lineHeight": { "tight": 1.25, "normal": 1.5, "relaxed": 1.75 } }, "color": { "palette": { "gray": { "50": "#f9fafb", "100": "#f3f4f6", "500": "#6b7280", "900": "#111827" }, "primary": { "500": "#3b82f6", "600": "#2563eb" } }, "semantic": { "background": "gray.50", "surface": "#ffffff", "text": "gray.900", "textMuted": "gray.500", "accent": "primary.500" } }, "radius": { "none": 0, "sm": 4, "md": 8, "lg": 12, "full": 9999 }, "shadow": { "sm": "0 1px 2px rgba(0,0,0,0.05)", "md": "0 4px 6px rgba(0,0,0,0.1)", "lg": "0 10px 15px rgba(0,0,0,0.1)" } }这里有几个设计决策值得展开说：
间距用 4px 基准单位。unit: 4意味着所有间距都是 4 的倍数，scale数组定义了允许的倍数。AI agent 生成代码时，margin: 13px会被标记为违规，因为 13 不在 scale 里。这个约束看起来严格，但实际用下来，它逼着 agent 用语义化的间距（md、lg），而不是随手写数字。我一开始担心这样会限制灵活性，但后来发现 4px 基准加上 13 档 scale，已经覆盖了 95% 的布局场景。
颜色用调色板 + 语义映射两层结构。palette定义原始色值，semantic定义用途。AI 生成代码时必须引用语义色（比如textMuted），而不是直接写#6b7280。这样做的好处是换主题的时候只需要改semantic的映射，不用全局搜索替换色值。我在一个项目里把accent从蓝色改成紫色，只改了一行配置，所有引用accent的组件自动跟着变。
字号和行高分开定义。很多设计系统把行高绑在字号上，但 impeccable 把它们拆开，因为同一个字号在不同场景下可能需要不同的行高。比如base字号在正文里用normal行高，在紧凑列表里用tight行高。这个灵活性在实际项目里很有用。
3.3 组件契约的编写要点
contracts.json定义的是组件级别的约束。我拿按钮组件举例：
{ "Button": { "variants": { "primary": { "background": "accent", "color": "#ffffff", "padding": "spacing.sm spacing.md", "radius": "radius.md", "fontSize": "typography.fontSize.sm", "fontWeight": 500 }, "secondary": { "background": "transparent", "border": "1px solid gray.500", "color": "text", "padding": "spacing.sm spacing.md", "radius": "radius.md" } }, "states": { "hover": { "opacity": 0.9 }, "disabled": { "opacity": 0.5, "cursor": "not-allowed" } }, "forbidden": [ "hardcoded-color", "arbitrary-padding", "inline-style" ] } }forbidden数组是精髓。它明确告诉 AI agent：生成按钮的时候，不允许出现硬编码颜色、任意间距、内联样式。CLI 在校验时会扫描生成的代码，如果发现style={{ padding: '13px' }}这种写法，会直接报错并且给出修正建议。
我建议在项目初期就把高频组件的契约写全，至少覆盖 Button、Input、Card、Modal、Table 这五类。后面新增组件的时候再逐步补充。契约写得越细，AI 生成代码的返工率越低。我统计过，写契约花了大概 2 小时，但后续省下的样式调整时间至少有 10 小时。
4. 浏览器扩展的安装与实时校验机制
4.1 扩展安装与本地服务连接
浏览器扩展目前支持 Chrome 和 Edge，Firefox 版本还在开发中。安装方式有两种：从商店安装，或者加载本地解压的扩展包。我建议用本地加载的方式，因为可以随时看到扩展的日志输出，排查问题方便。
安装完之后，扩展会自动尝试连接本地的 impeccable 服务。这个服务默认监听localhost:3456，你需要在项目目录下跑impeccable watch来启动它。连接成功之后，扩展图标会变成绿色，点击图标可以看到当前项目的设计令牌摘要和校验状态。
这里有个坑：如果你同时开了多个项目，每个项目都在跑impeccable watch，端口会冲突。解决办法是在config.json里给每个项目配不同的端口：
{ "server": { "port": 3457 } }然后在扩展的设置页面里手动指定端口。我一般按项目顺序分配端口，比如项目 A 用 3456，项目 B 用 3457，避免冲突。
4.2 视觉偏差检测的工作原理
扩展的核心功能是计算样式比对。当页面加载或者 DOM 发生变化时，扩展会遍历所有可见元素，抓取它们的getComputedStyle，然后跟设计令牌做比对。比对规则分三类：
第一类是硬编码检测。如果元素的margin、padding、font-size、color等属性值不在令牌定义的范围内，标记为违规。比如padding: 13px会被标记，因为 13 不在 spacing scale 里。
第二类是语义偏离检测。如果元素用了令牌里的值，但用错了语义，也会被标记。比如正文文字用了textMuted颜色，但textMuted是给辅助文字用的，正文应该用text。这种检测需要扩展理解元素的语义角色，目前是通过 HTML 标签和 ARIA 属性来推断的。
第三类是组件契约违反检测。如果元素匹配了某个组件的选择器（比如button或者.card），但它的样式不符合契约定义，会被标记。比如按钮的border-radius用了radius.full，但契约里只允许radius.md。
检测结果会以三种方式呈现：扩展图标上的角标数字、页面上的高亮标注、以及回传给 CLI 的结构化报告。我一般先看角标数字，如果数字很大，说明问题比较多，直接看 CLI 的报告更高效；如果数字很小，就在页面上直接看高亮标注，逐个修。
4.3 把视觉反馈回传给 AI agent
这是整个闭环里最关键的环节。扩展检测到偏差之后，会把偏差信息通过 WebSocket 发给 CLI，CLI 再把这些信息格式化之后注入到 agent 的上下文里。格式大概是这样：
[impeccable] 检测到 3 处设计规范偏差： 1. <div class="hero"> 的 padding 为 13px，不在 spacing scale 中。建议改为 spacing.md (16px) 或 spacing.sm (8px)。 2. <button class="cta"> 的 background 为 #3b82f6，应引用语义色 accent。 3. <p class="subtitle"> 的 color 为 gray.500，但该元素语义为正文，应使用 text 而非 textMuted。Agent 收到这个信息之后，下一轮生成会自动修正。我实测下来，Codex CLI 对这种结构化反馈的响应很好，基本上一次就能改对。Claude Code 有时候会忽略，需要在 prompt 里强调“请严格遵守 impeccable 的校验报告”。
提示：如果你发现 agent 没有响应校验报告，检查一下 CLI 的日志里有没有
injecting feedback的输出。如果没有，说明扩展和 CLI 之间的连接断了，重启impeccable watch通常能解决。
5. 实战工作流：从需求到可交付界面的完整链路
5.1 项目初始化阶段的配置策略
新项目启动的时候，我一般按这个顺序来：
- 跑
impeccable init生成默认配置 - 根据项目品牌规范修改
tokens.json里的颜色和字体 - 根据团队习惯调整
spacing.scale和radius档位 - 把高频组件的契约写进
contracts.json - 在
config.json里配好端口和 agent 路径 - 跑
impeccable check确认配置没有语法错误
第 2 步和第 3 步是最花时间的，因为要跟设计师或者产品对齐。我的经验是：不要试图一次配到完美。先配一套能用的，然后在实际开发过程中逐步调整。设计令牌文件是活的，不是一次性的。
5.2 用包装模式启动 Codex CLI 的完整过程
配置好之后，用impeccable run codex启动。终端里会先打印一段初始化日志：
[impeccable] 加载设计令牌：tokens.json (v1.2.0) [impeccable] 加载组件契约：contracts.json (5 components) [impeccable] 启动本地服务：localhost:3456 [impeccable] 注入系统提示：design-constraints.md [impeccable] 启动 Codex CLI...然后 Codex CLI 正常启动，但它的系统提示里已经多了设计约束的内容。你正常给 Codex 下指令，比如“帮我做一个用户列表页面，包含搜索框、表格和分页”，Codex 生成的代码会自动引用设计令牌。
我拿一个实际例子来说明效果。没有 impeccable 的时候，Codex 生成的表格样式大概是这样的：
.table { width: 100%; border-collapse: collapse; margin-bottom: 20px; } .table th { padding: 12px 16px; background: #f5f5f5; font-size: 14px; } .table td { padding: 10px 16px; border-bottom: 1px solid #eee; }有了 impeccable 之后，同样的指令，生成的代码变成了：
.table { width: 100%; border-collapse: collapse; margin-bottom: var(--spacing-lg); } .table th { padding: var(--spacing-sm) var(--spacing-md); background: var(--color-gray-100); font-size: var(--font-size-sm); } .table td { padding: var(--spacing-sm) var(--spacing-md); border-bottom: 1px solid var(--color-gray-100); }差异很明显：所有数值都变成了令牌引用，没有魔法数字。而且margin-bottom从 20px 变成了spacing-lg（24px），因为 20 不在 scale 里，agent 自动选了最接近的合法值。
5.3 浏览器扩展的实时预览与人工复核
Codex 生成完代码之后，你在浏览器里打开页面，扩展会自动检测。我一般会开着扩展的侧边栏，里面实时显示当前页面的违规列表。点击某一条违规，页面上对应的元素会高亮，方便定位。
人工复核的重点是语义层面的偏差。硬编码数值的偏差扩展能自动检测，但“这个按钮该不该用 primary 变体”这种判断，扩展做不了，需要人来定。我一般会快速扫一遍页面，看看有没有明显的视觉问题，如果有，就在 Codex 的对话里直接说“把那个按钮改成 secondary”，Codex 会结合 impeccable 的约束重新生成。
这个工作流跑顺了之后，从需求到可交付界面的时间大概能压缩 40% 左右。主要省下来的是样式调整和返工的时间。
6. 常见问题与排查技巧实录
6.1 扩展连不上本地服务
这是最高频的问题。表现是扩展图标一直是灰色，点击显示“未连接”。排查顺序：
- 确认
impeccable watch正在运行，终端里有没有server listening on 3456的输出 - 确认扩展设置里的端口跟
config.json里的一致 - 检查有没有其他程序占用了 3456 端口，用
lsof -i :3456查一下 - 如果用了容器或者远程开发环境，确认端口映射是否正确
我遇到过一次是端口被一个旧的impeccable watch进程占着，但那个进程已经僵死了。kill掉之后重启就好了。所以如果你反复连不上，先ps aux | grep impeccable看看有没有僵尸进程。
6.2 Agent 忽略设计约束
有时候 Codex 或者 Claude Code 会无视注入的约束，继续生成硬编码样式。原因通常是系统提示被截断或者约束内容太长被模型忽略了。解决办法：
- 精简
contracts.json，只保留最核心的组件契约，减少提示长度 - 在
config.json里把injectionMode改成strict，这样 CLI 会在每一轮对话前都重新注入约束，而不是只在启动时注入一次 - 如果还是不行，在给 agent 的指令里显式加一句“请严格遵守 impeccable 的设计约束”
我实测下来，strict模式的效果最好，但会增加 token 消耗。如果项目预算紧张，可以只在关键页面开发时开strict，其他时候用默认模式。
6.3 设计令牌更新后 agent 没有同步
你改了tokens.json之后，需要重启impeccable watch和 agent，新的令牌才会生效。因为令牌是在启动时加载到内存里的，不会热更新。我一开始不知道，改完令牌发现 agent 还在用旧值，排查了半天。
如果你不想每次都重启，可以在config.json里开watchTokens: true，这样 CLI 会监听tokens.json的变化，自动重新加载。但这个功能目前还是实验性的，偶尔会有加载失败的情况，生产环境建议还是手动重启。
6.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 扩展图标灰色 | 本地服务未启动 | 检查impeccable watch终端输出 | 启动服务或重启 |
| 端口冲突 | 多个项目用同一端口 | lsof -i :端口号 | 修改config.json端口 |
| Agent 忽略约束 | 系统提示被截断 | 查看 CLI 日志的注入内容 | 开strict模式或精简契约 |
| 令牌不生效 | 未重启服务 | 检查令牌文件修改时间 | 重启 watch 和 agent |
| 校验报告为空 | 扩展未连接 | 检查扩展连接状态 | 重新连接扩展 |
| 组件契约报错 | JSON 语法错误 | impeccable check | 修复 JSON 格式 |
6.5 几个官方文档没写的实操心得
心得一：spacing scale 不要设太密。我一开始把 scale 设成了[0,1,2,3,4,5,6,7,8,9,10,12,14,16,20,24,32,40,48,64]，结果 agent 经常在 5 和 6 之间纠结，生成的间距反而更乱。后来精简到 13 档，agent 的选择更果断，生成的布局也更一致。
心得二：颜色语义映射要留冗余。不要只定义text和textMuted，再加一个textSubtle给更弱的辅助文字。实际项目里文字层级往往有三到四层，只定义两层的话，agent 会自己发明第三层，反而破坏一致性。
心得三：契约里的forbidden比required更重要。与其告诉 agent“必须用什么”，不如告诉它“绝对不能用什么”。因为 agent 的生成空间很大，限制它的错误选项比引导它的正确选项更有效。我一般会把hardcoded-color、arbitrary-spacing、inline-style、!important这几个都加进forbidden。
心得四：定期跑impeccable check做全量扫描。不要只依赖实时校验，因为实时校验只覆盖当前页面。定期跑全量扫描能发现历史代码里的遗留问题。我一般每周跑一次，把扫描报告里的问题批量修掉。
心得五：把设计令牌文件纳入代码评审。tokens.json和contracts.json的修改应该跟代码一样走 PR 流程，因为它们的改动会影响所有 agent 的生成结果。我们团队现在要求令牌文件的修改必须至少两个人 review，避免一个人随手改了一个色值导致全站风格漂移。
7. 进阶玩法：自定义扩展与 CI 集成
7.1 写一个自定义的校验规则
impeccable 的校验规则是插件化的，你可以在.impeccable/rules/目录下放自定义规则文件。规则文件是一个 JS 模块，导出一个函数，接收元素的计算样式和令牌对象，返回违规信息或者 null。
我写过一个规则，用来检测“同一页面内相同语义的组件是否用了不同的变体”。比如页面上有两个按钮，一个是 primary，一个是 secondary，但它们的语义角色其实一样，这种不一致会被标记出来。规则代码大概是这样：
module.exports = function checkButtonConsistency(element, tokens, context) { if (element.tagName !== 'BUTTON') return null; const variant = element.dataset.variant; const role = element.dataset.role; if (!role) return null; const siblings = context.querySelectorAll(`button[data-role="${role}"]`); const variants = new Set([...siblings].map(el => el.dataset.variant)); if (variants.size > 1) { return { message: `相同语义角色 "${role}" 的按钮使用了 ${variants.size} 种不同变体`, severity: 'warning' }; } return null; };这个规则帮我们抓出了好几个页面里按钮变体不一致的问题。写自定义规则的门槛不高，只要熟悉 DOM API 和计算样式的基本操作就行。
7.2 在 CI 流程里集成 impeccable check
impeccable check支持--ci参数，输出格式是 JSON，方便 CI 系统解析。我在 GitLab CI 里加了一个 stage：
design-check: stage: test script: - npm install - npx impeccable check --ci --output report.json artifacts: paths: - report.json when: always rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event"这样每次 MR 都会跑设计规范校验，如果有违规，report.json 会作为 artifact 保留，MR 页面里能看到。我们设置的是 warning 级别不阻塞合并，error 级别阻塞。实际跑下来，error 级别的违规很少，大部分是 warning，但即使不阻塞，开发者看到报告也会主动去修。
7.3 跟其他 CLI 工具的配合
impeccable 除了跟 Codex CLI 集成，还可以跟其他工具配合。比如：
- 跟 openspec CLI 配合：openspec 负责生成 API 契约，impeccable 负责生成 UI 契约，两者结合可以做到前后端接口和界面风格的双重约束。
- 跟 minimax CLI 配合：minimax 做代码压缩和优化，impeccable 做设计规范校验，可以在构建流程里串起来。
- 跟 gitlab cli 配合：在 MR 创建时自动跑 impeccable check，把结果作为 MR 评论发出来。
这些配合方式我还在摸索，目前最成熟的是跟 Codex CLI 的集成。其他工具的集成需要写一些胶水代码，但整体思路是一样的：把 impeccable 的校验结果转换成目标工具能理解的格式，注入到它的工作流里。
8. 一些踩坑之后的个人体会
这个项目我从 v0.8 开始用，到现在 v1.2，中间经历了三次比较大的配置重构。最大的体会是：设计约束的价值不在于限制 AI，而在于把团队的隐性设计决策显性化。以前我们说“这个按钮要好看一点”，现在我们会说“这个按钮用 primary 变体，padding 用 spacing.sm 和 spacing.md，圆角用 radius.md”。这种显性化本身就有价值，即使没有 AI，它也让设计评审有了具体的依据。
另一个体会是不要追求一步到位。我见过有人花一周时间写了一份完美的 tokens.json，结果项目需求一变，整个文件作废。我的做法是先用最小可用的配置跑起来，在实际开发中逐步补充。令牌文件应该是活的，跟着项目一起生长。
最后分享一个小技巧：如果你觉得 impeccable 的默认校验太严格，可以在config.json里把severity调成warning，这样违规不会阻塞 agent 的生成，只是提示。等团队适应了之后，再逐步调回error。这个渐进式的策略比一上来就严格模式更容易推行。
这个项目后续还可以往几个方向扩展：比如支持从 Figma 文件自动导入设计令牌，或者支持多主题切换的令牌继承。我目前在自己 fork 的版本里试了 Figma 导入，效果还不错，等稳定了再分享出来。
