impeccable：AI coding agent如何实现前端设计稿到代码的自动化还原

1. 项目缘起：为什么我们需要一个叫“impeccable”的前端设计辅助工具

第一次看到“impeccable”这个词，是在一个前端技术群里。有人甩了一张截图，说“这玩意儿把设计稿还原度拉到了95%以上，关键是它跑在命令行里”。我当时的第一反应是：又一个噱头。毕竟“AI coding agents”这个概念从2024年火到2025年，市面上打着“智能生成前端代码”旗号的工具没有一百也有八十，真正能打的屈指可数。但当我花了一个周末把impeccable的CLI装到本地，接上自己的项目跑了几轮之后，我承认我之前的判断过于武断了。

impeccable本质上是一个面向前端设计还原场景的AI coding agent，它同时提供了CLI和browser extension两种交互形态。CLI负责在终端里完成项目初始化、设计规范解析、代码生成与校验；browser extension则负责在浏览器里实时抓取页面结构、样式信息和交互状态，把“设计稿到代码”的最后一公里打通。它解决的核心问题是：前端工程师在拿到设计稿之后，需要花费大量时间在像素级还原、响应式适配、组件拆分和样式命名上，而这些工作中有相当一部分是重复且机械的。impeccable试图用AI agent的方式，把这部分工作自动化，同时保留工程师对最终代码的完全控制权。

这个项目适合谁？如果你是一个前端工程师，每天跟Figma、Sketch或者即时设计打交道，经常因为“设计稿上明明是8px的间距，实现出来变成了7.5px”而跟设计师扯皮，那impeccable值得你花时间研究。如果你是一个全栈开发者，前端只是你工作的一部分，你希望用更少的时间把界面搭出来，那impeccable的CLI模式会让你很舒服。甚至如果你是一个独立开发者，没有专职设计师，只能自己对着参考图一点点抠样式，impeccable的browser extension可以帮你从现有页面里提取设计token，反向生成一套可复用的样式系统。

我在这篇文章里会从整体设计思路、核心细节解析、实操过程、常见问题排查四个维度，把impeccable的用法和背后的逻辑拆开讲清楚。所有内容基于我自己的实操记录和踩坑经验，不保证覆盖官方文档的每一个角落，但保证每一条都是能直接抄作业的干货。

2. 整体设计与思路拆解：impeccable为什么选择CLI+浏览器扩展的双形态

2.1 从“设计稿到代码”的链路痛点说起

在聊impeccable的设计思路之前，先得把前端设计还原这件事的链路拆开看。一个典型的前端还原流程是这样的：设计师在Figma里完成设计稿，标注好间距、字号、颜色、圆角、阴影等参数；前端工程师打开设计稿，一边看标注一边写CSS，遇到复杂的布局还要切图、量距离、调层级；写完静态样式之后，再补交互状态、响应式断点和动画过渡；最后在浏览器里跟设计稿做像素级对比，反复微调直到视觉一致。

这个链路里有三个明显的效率瓶颈。第一个是信息传递损耗：设计稿里的参数是结构化的，但工程师在手动转录到代码的过程中，很容易出现偏差，比如把letter-spacing: 0.5px写成letter-spacing: 0.05em，或者把box-shadow的模糊半径搞错。第二个是重复劳动：同一个设计系统里的按钮、输入框、卡片，在不同页面里反复出现，每次都要重新写一遍样式，哪怕用了组件库，也经常需要覆写。第三个是上下文切换成本：工程师需要在设计工具、代码编辑器、浏览器之间来回切换，每次切换都会打断心流。

impeccable的设计思路就是围绕这三个瓶颈展开的。它没有选择做一个“一键生成整个页面”的黑盒工具，而是把能力拆成两块：CLI负责结构化的代码生成与校验，browser extension负责运行时的样式提取与比对。这个拆分逻辑很清晰：设计稿里的静态信息适合在CLI里处理，因为CLI可以读取本地文件、调用AI模型、输出代码文件；而页面上的动态信息和实际渲染效果适合在浏览器里处理，因为browser extension可以直接访问DOM和Computed Style。

2.2 为什么是CLI而不是GUI或者IDE插件

市面上大多数AI代码生成工具都选择做IDE插件，比如VS Code的Copilot、Cursor的内置Agent，或者做Web端的可视化编辑器。impeccable偏偏选了CLI作为主要交互形态，这个决策背后有几个考量。

第一，CLI的自动化能力更强。前端项目通常有一套自己的构建流程，比如Vite、Webpack、Turbopack，CLI可以直接嵌入到package.json的scripts里，跟现有的构建、测试、部署流程无缝衔接。你可以在CI/CD里加一步impeccable check，自动校验新提交的代码是否符合设计规范。GUI工具很难做到这一点。

第二，CLI对AI agent更友好。现在的AI coding agents，比如Codex CLI、Claude Code、Zcode CLI，本质上都是在终端里运行的。impeccable把自己做成CLI，意味着它可以跟这些agent协同工作。你可以让Codex CLI调用impeccable的命令，先解析设计稿生成基础代码，再用Codex CLI做逻辑补全。这种组合玩法在GUI工具里很难实现。

第三，CLI的输入输出更可控。GUI工具通常会把生成结果直接插入到编辑器里，工程师很难控制生成的范围和粒度。CLI工具可以让你指定输入文件、输出目录、生成模式，甚至可以把生成结果先输出到stdout，让你确认之后再写入文件。这种“先看后写”的机制在实操中非常重要，后面讲实操的时候会详细说。

当然，CLI也有它的短板。比如它没法直接访问浏览器里的渲染结果，没法看到页面在不同设备上的实际表现。这就是browser extension存在的意义。extension负责在浏览器里采集真实的样式数据，把“设计稿参数”和“实际渲染参数”做比对，找出偏差。CLI和extension之间通过一个本地服务或者共享的配置文件来通信，形成一个闭环。

2.3 核心架构：Agent、Parser、Generator、Checker四层结构

impeccable的内部架构可以拆成四层。最上面是Agent层，负责理解用户的自然语言指令，比如“把这个Figma链接里的设计稿转成React组件”。Agent层会调用底层的Parser和Generator来完成具体任务。第二层是Parser层，负责解析设计稿文件、CSS文件、HTML文件，提取出结构化的设计token和布局信息。第三层是Generator层，负责根据解析结果和用户配置，生成目标格式的代码，比如React组件、Vue组件、纯CSS、Tailwind类名等。最下面是Checker层，负责校验生成的代码是否符合预设的设计规范，比如间距是否在4px的倍数上、颜色是否在调色板里、字号是否在类型系统里。

这个四层结构的优势在于职责分离。Parser只负责提取信息，不关心生成什么代码；Generator只负责生成代码，不关心信息从哪来；Checker只负责校验，不关心代码怎么生成。这种分离让每一层都可以独立替换和扩展。比如你可以把Parser从Figma换成Sketch，只要输出格式一致，Generator和Checker完全不用改。你也可以把Generator从React换成Vue，只要输入格式一致，Parser和Checker也不用改。

在实际使用中，这个架构带来的最大好处是可调试性。当生成结果不符合预期时，你可以逐层排查：是Parser提取的参数错了，还是Generator的模板有问题，还是Checker的规则太严格。这种可调试性在AI工具里非常难得，因为大多数AI工具都是端到端的黑盒，出了问题只能重新生成，没法定位原因。

2.4 与同类工具的差异化定位

把impeccable跟市面上几个同类工具做个对比，能更清楚地看出它的定位。跟Codex CLI相比，impeccable更专注于前端设计还原这个垂直场景，Codex CLI是通用的代码生成agent，什么都能干但什么都不精。跟v0.dev相比，impeccable是本地优先的，代码生成在本地完成，不依赖云端服务，对代码隐私要求高的团队更友好。跟Locofy相比，impeccable的browser extension可以反向从现有页面提取设计token，而Locofy主要是从设计稿正向生成代码。

还有一个很重要的差异点是对设计系统的支持。impeccable允许你定义一个design-tokens.json文件，里面包含颜色、间距、字号、圆角、阴影等所有设计变量。Generator在生成代码时会优先使用这些变量，而不是硬编码具体的数值。Checker会校验生成的代码里有没有硬编码的数值，如果有就报warning。这个机制让impeccable特别适合已经有一套设计系统的团队，可以把设计系统的约束直接写进工具配置里，让AI生成的代码天然符合规范。

3. 核心细节解析与实操要点：从安装到第一次生成

3.1 环境准备与安装：避开Node版本和包管理器的坑

impeccable的CLI是通过npm分发的，安装命令很简单：

npm install -g impeccable-cli

但这里有几个坑要注意。第一，Node版本要求。impeccable依赖了Node 20以上的某些API，如果你本地是Node 18，安装过程可能不会报错，但运行时会抛出TypeError: Cannot read properties of undefined。我建议在安装之前先跑一下node -v确认版本，如果低于20，用nvm或者fnm切一下。第二，包管理器选择。官方推荐用npm，但如果你习惯用pnpm或者yarn，也可以装，只是要注意全局安装的路径可能不在PATH里。我实测下来，pnpm的全局bin目录默认是~/.local/share/pnpm，需要手动加到PATH里。

安装完成之后，跑一下impeccable --version确认安装成功。如果输出了版本号，说明CLI已经就绪。接下来需要初始化一个项目：

impeccable init

这个命令会在当前目录下创建一个.impeccable文件夹，里面包含默认的配置文件config.json和设计token文件design-tokens.json。config.json里可以配置AI模型的API key、生成代码的目标框架、输出目录等。design-tokens.json里是默认的设计变量，你可以根据自己的设计系统修改。

注意：impeccable init默认不会覆盖已有的.impeccable文件夹，如果你之前初始化过，想重新来一遍，需要先手动删除这个文件夹。

3.2 设计Token的定义：让AI生成的代码天然符合规范

设计token是impeccable的核心概念之一。它本质上是一个JSON文件，里面定义了所有可复用的设计变量。一个典型的design-tokens.json长这样：

{ "color": { "primary": "#2563EB", "primary-hover": "#1D4ED8", "background": "#FFFFFF", "surface": "#F8FAFC", "text-primary": "#0F172A", "text-secondary": "#64748B", "border": "#E2E8F0" }, "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px", "2xl": "48px" }, "fontSize": { "xs": "12px", "sm": "14px", "base": "16px", "lg": "18px", "xl": "20px", "2xl": "24px", "3xl": "30px" }, "borderRadius": { "sm": "4px", "md": "8px", "lg": "12px", "full": "9999px" }, "boxShadow": { "sm": "0 1px 2px rgba(0,0,0,0.05)", "md": "0 4px 6px rgba(0,0,0,0.07)", "lg": "0 10px 15px rgba(0,0,0,0.1)" } }

这个文件定义好之后，Generator在生成代码时会优先引用这些变量。比如生成一个按钮的样式，它不会写padding: 12px 24px，而是写padding: var(--spacing-sm) var(--spacing-lg)。Checker在校验时会检查代码里有没有出现不在token列表里的数值，如果有就报warning。

这里有个实操心得：token的粒度不要太细，也不要太粗。太细的话，比如给每个颜色都定义一个token，维护成本很高，而且AI在生成时容易选错。太粗的话，比如只定义primary和secondary两个颜色，AI在生成时没有足够的约束，还是会硬编码。我建议按照“语义化+层级化”的原则来定义，比如颜色按primary、surface、text、border分四组，每组下面再分具体的变体。间距按xs到2xl分六档，基本能覆盖大多数场景。

3.3 从设计稿到代码：Parser的工作流程

impeccable的Parser支持多种输入格式，包括Figma的API链接、Sketch文件、以及本地的HTML/CSS文件。我主要用的是Figma链接和本地HTML两种方式，下面分别说一下。

Figma链接方式需要在config.json里配置Figma的Personal Access Token。配置好之后，运行：

impeccable parse --figma "https://www.figma.com/file/xxxxx/Design-System" --node "123:456"

这个命令会调用Figma的API，拉取指定节点的设计数据，然后解析成结构化的JSON。解析结果会输出到.impeccable/parsed/目录下，包含布局信息、样式信息、文本内容等。你可以打开这个JSON文件检查解析结果，确认没有遗漏或者错误。

本地HTML方式更适合从现有页面反向提取设计token。运行：

impeccable parse --html "./src/pages/index.html" --css "./src/styles/main.css"

Parser会读取HTML和CSS文件，提取出所有用到的颜色、间距、字号、圆角等数值，然后跟design-tokens.json做比对，找出不在token列表里的数值。这个功能特别适合接手一个老项目时，快速了解项目的设计规范现状。

实操心得：Figma的API有速率限制，免费版账号每分钟只能调几次。如果你要解析的设计稿节点比较多，建议分批解析，每次间隔几秒。另外，Figma的API返回的数据结构比较复杂，Parser在解析时可能会遇到一些边缘情况，比如自动布局的嵌套、约束条件的冲突等。遇到解析结果不对的时候，先检查Figma里的图层结构是否规范，尽量用Auto Layout和Component，少用绝对定位。

3.4 Generator的模板系统：如何生成可维护的代码

Generator是impeccable里最核心的模块，它决定了生成的代码长什么样。impeccable内置了几套模板，分别对应React、Vue、Svelte和纯HTML/CSS。你也可以自定义模板，模板文件放在.impeccable/templates/目录下，用Handlebars语法编写。

以React模板为例，生成一个按钮组件的命令是：

impeccable generate --type button --framework react --output ./src/components/

生成的代码大概长这样：

import React from 'react'; import './Button.css'; export const Button = ({ variant = 'primary', size = 'md', children, ...props }) => { return ( <button className={`btn btn--${variant} btn--${size}`} {...props} > {children} </button> ); };

对应的CSS文件：

.btn { display: inline-flex; align-items: center; justify-content: center; border-radius: var(--border-radius-md); font-size: var(--font-size-base); font-weight: 500; cursor: pointer; transition: background-color 0.2s ease, box-shadow 0.2s ease; } .btn--primary { background-color: var(--color-primary); color: #FFFFFF; padding: var(--spacing-sm) var(--spacing-lg); } .btn--primary:hover { background-color: var(--color-primary-hover); } .btn--secondary { background-color: var(--color-surface); color: var(--color-text-primary); border: 1px solid var(--color-border); padding: var(--spacing-sm) var(--spacing-lg); }

这个生成结果有几个值得注意的地方。第一，样式和逻辑分离，CSS单独放在一个文件里，方便后续维护。第二，使用CSS变量，所有颜色、间距、字号都引用了design-tokens.json里定义的变量，没有硬编码。第三，变体通过修饰类实现，btn--primary和btn--secondary分别对应不同的视觉风格，符合BEM命名规范。

如果你用的是Tailwind，Generator也可以生成Tailwind类名：

export const Button = ({ variant = 'primary', size = 'md', children, ...props }) => { const baseClasses = 'inline-flex items-center justify-center rounded-md font-medium transition-colors'; const variantClasses = { primary: 'bg-blue-600 text-white hover:bg-blue-700 px-6 py-2', secondary: 'bg-slate-50 text-slate-900 border border-slate-200 hover:bg-slate-100 px-6 py-2', }; return ( <button className={`${baseClasses} ${variantClasses[variant]}`} {...props}> {children} </button> ); };

注意：Tailwind模式下，Generator会尽量使用Tailwind的预设类名，但如果设计token里的数值不在Tailwind的默认刻度上，它会生成自定义的[]语法，比如p-[12px]。这种情况下，Checker会报warning，建议你调整设计token或者扩展Tailwind的配置。

3.5 Browser Extension的安装与使用：实时比对设计稿与实现

Browser extension是impeccable的另一半能力。它目前支持Chrome和Edge，安装方式是从Chrome Web Store搜索“impeccable”然后添加到浏览器。安装完成之后，在任意页面上点击扩展图标，会弹出一个面板，显示当前页面的设计token提取结果和样式偏差报告。

Extension的核心功能有三个。第一是提取当前页面的设计token，它会扫描页面上的所有元素，统计用到的颜色、间距、字号、圆角等数值，然后跟design-tokens.json做比对，列出不在token列表里的数值。第二是比对设计稿和实现，如果你在CLI里已经解析了Figma设计稿，extension可以加载解析结果，然后在页面上高亮显示哪些元素的样式跟设计稿不一致。第三是生成样式修复建议，对于不一致的元素，extension会给出具体的CSS修改建议，比如“把margin-top: 12px改成margin-top: var(--spacing-md)”。

我实测下来，extension的提取功能在大多数页面上都能正常工作，但在一些用了Shadow DOM或者iframe的页面上会有遗漏。另外，如果页面用了CSS-in-JS方案，比如styled-components或者emotion，extension提取到的可能是编译后的类名，而不是原始的样式定义。这种情况下，建议先用CLI的parse --html命令从源码层面提取，再用extension做运行时校验。

实操心得：extension的面板里有一个“Diff模式”开关，打开之后会在页面上用红色边框标出所有样式偏差超过阈值的元素。这个功能在调试响应式布局时特别好用，你可以拖动浏览器窗口改变宽度，实时看到哪些元素在不同断点下出现了偏差。

4. 实操过程与核心环节实现：一个完整的设计还原案例

4.1 案例背景：一个卡片列表页面的还原需求

为了把上面的知识点串起来，我拿一个真实的案例来演示。需求是这样的：设计师给了一个Figma链接，里面是一个卡片列表页面，包含一个标题栏、一个搜索框、一个卡片网格，每个卡片有图片、标题、描述和操作按钮。设计稿有桌面端和移动端两个断点，桌面端卡片一行三个，移动端一行一个。要求用React+CSS Modules实现，样式必须使用设计token，不能硬编码。

这个案例覆盖了impeccable的主要功能：Figma解析、组件生成、样式校验、响应式适配。下面我按步骤拆解。

4.2 第一步：解析Figma设计稿并提取设计token

首先在config.json里配置Figma的Access Token：

{ "figma": { "accessToken": "figd_xxxxxxxxxxxxxxxxxxxx" }, "framework": "react", "styling": "css-modules", "outputDir": "./src/components" }

然后运行解析命令：

impeccable parse --figma "https://www.figma.com/file/abc123/Card-List" --node "0:1"

解析完成后，.impeccable/parsed/目录下会生成一个card-list.json文件。打开这个文件，可以看到解析出的结构信息，包括每个图层的名称、类型、位置、尺寸、样式等。我检查了一下，发现设计师在Figma里用了Auto Layout，所以解析出的布局信息很规整，没有绝对定位的混乱情况。

接下来提取设计token：

impeccable tokens --from-parsed .impeccable/parsed/card-list.json --output .impeccable/design-tokens.json

这个命令会从解析结果里提取所有用到的颜色、间距、字号、圆角等数值，生成一个初始的design-tokens.json。我打开看了一下，提取出了12个颜色、8个间距值、6个字号、4个圆角值。其中有几个间距值是奇数，比如6px和10px，这不符合4px网格的规范。我手动把它们调整成了8px和12px，然后在Figma里同步修改了设计稿，保持设计稿和token的一致性。

实操心得：从Figma提取的token往往会有一些“脏数据”，比如设计师随手拖出来的13px间距，或者用了非标准色值的颜色。建议在提取之后花几分钟做一次清洗，把数值对齐到设计系统的刻度上。这个清洗过程虽然手动，但一次性的投入能换来后续生成的代码质量大幅提升。

4.3 第二步：生成卡片组件和列表布局

有了设计token之后，就可以生成组件了。先生成卡片组件：

impeccable generate --type card --framework react --styling css-modules --output ./src/components/Card

生成的Card.jsx：

import React from 'react'; import styles from './Card.module.css'; export const Card = ({ image, title, description, actions }) => { return ( <div className={styles.card}> <div className={styles.imageWrapper}> <img src={image} alt={title} className={styles.image} /> </div> <div className={styles.content}> <h3 className={styles.title}>{title}</h3> <p className={styles.description}>{description}</p> <div className={styles.actions}>{actions}</div> </div> </div> ); };

生成的Card.module.css：

.card { background-color: var(--color-background); border: 1px solid var(--color-border); border-radius: var(--border-radius-lg); overflow: hidden; transition: box-shadow 0.2s ease; } .card:hover { box-shadow: var(--box-shadow-md); } .imageWrapper { aspect-ratio: 16 / 9; overflow: hidden; } .image { width: 100%; height: 100%; object-fit: cover; } .content { padding: var(--spacing-md); } .title { font-size: var(--font-size-lg); font-weight: 600; color: var(--color-text-primary); margin-bottom: var(--spacing-xs); } .description { font-size: var(--font-size-sm); color: var(--color-text-secondary); line-height: 1.5; margin-bottom: var(--spacing-md); } .actions { display: flex; gap: var(--spacing-sm); }

然后生成列表布局：

impeccable generate --type grid --framework react --styling css-modules --columns 3 --gap var(--spacing-lg) --output ./src/components/CardList

生成的CardList.module.css：

.grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: var(--spacing-lg); padding: var(--spacing-xl); } @media (max-width: 768px) { .grid { grid-template-columns: 1fr; padding: var(--spacing-md); } }

这两个组件生成之后，我手动检查了一遍，发现几个需要调整的地方。第一，卡片的aspect-ratio在移动端可能需要改成4 / 3，因为移动端屏幕更窄，16:9的图片会显得太扁。第二，grid的断点设置在768px，但设计稿里移动端的断点是640px，需要改一下。第三，actions区域的按钮间距用的是var(--spacing-sm)，但设计稿里是var(--spacing-md)，需要修正。

这些调整说明了一个问题：AI生成的代码是起点，不是终点。impeccable的价值在于帮你把80%的重复劳动干掉，剩下的20%需要你根据具体业务场景做微调。这个比例比纯手写代码要高效得多，但你不能指望它一键生成完美代码。

4.4 第三步：用Checker校验样式规范

组件生成之后，跑一下Checker：

impeccable check --dir ./src/components --tokens .impeccable/design-tokens.json

Checker会扫描指定目录下的所有CSS和JSX文件，检查有没有硬编码的样式数值。输出结果大概是这样：

./src/components/Card/Card.module.css Line 12: box-shadow: 0 4px 6px rgba(0,0,0,0.07) -> 建议使用 var(--box-shadow-md) Line 28: margin-bottom: 6px -> 建议使用 var(--spacing-xs) 或 var(--spacing-sm) ./src/components/CardList/CardList.module.css Line 8: padding: 32px -> 建议使用 var(--spacing-xl) Line 14: gap: 24px -> 建议使用 var(--spacing-lg)

Checker的规则是可以配置的。在config.json里可以设置checker.severity为error、warning或info。我一般把硬编码颜色设为error，硬编码间距设为warning，硬编码字号设为info。这样在CI里跑的时候，颜色问题会直接导致构建失败，间距和字号问题只是提示，不会阻塞流程。

注意：Checker目前对CSS-in-JS的支持还不完善，如果你用的是styled-components或者emotion，Checker可能无法正确解析模板字符串里的样式。这种情况下，建议先用CLI的parse --html从编译后的CSS里提取，或者等官方后续版本的支持。

4.5 第四步：用Browser Extension做运行时校验

代码写完之后，在浏览器里打开页面，点击impeccable的扩展图标，加载之前解析的Figma数据，然后点击“Compare”按钮。Extension会在页面上高亮显示所有跟设计稿不一致的元素。我实测下来，发现两个问题：一是卡片的圆角在移动端变成了8px，但设计稿里是12px；二是搜索框的placeholder颜色跟设计稿不一致。

第一个问题的原因是CSS Modules的媒体查询里覆盖了圆角变量，但覆盖的值写错了。第二个问题的原因是placeholder的样式没有用设计token，而是用了浏览器默认样式。这两个问题都是手动写代码时容易忽略的细节，extension的比对功能帮我快速定位到了。

修复之后，再跑一次extension的比对，所有元素都显示绿色，说明还原度达标了。整个过程从解析设计稿到最终校验通过，大概花了40分钟，其中大部分时间花在手动微调上。如果纯手写代码，这个页面至少需要2到3个小时。效率提升是实实在在的。

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

5.1 安装与配置阶段的典型问题

问题一：impeccable init报错“Cannot find module 'impeccable-core'”

这个问题的原因是npm的全局安装路径没有正确配置，导致CLI找不到依赖的核心模块。解决方法是在config.json里手动指定corePath：

{ "corePath": "/usr/local/lib/node_modules/impeccable-cli/node_modules/impeccable-core" }

路径根据你的实际安装位置调整。用npm root -g可以查看全局模块的根目录。

问题二：Figma解析时返回“Invalid node ID”

Figma的节点ID格式是123:456，但如果你从浏览器地址栏复制链接，有时候会带上node-id=123%3A456这样的URL编码。Parser在解析时需要的是解码后的ID。解决方法是在命令里手动把%3A替换成:，或者用--node "123:456"的格式直接指定。

问题三：生成的代码里CSS变量没有定义

这个问题的原因是design-tokens.json里的变量名跟Generator模板里的变量名不一致。impeccable默认的变量命名规范是--color-primary、--spacing-md这样的kebab-case格式。如果你在token文件里用了camelCase，比如colorPrimary，Generator在生成时会找不到对应的变量。解决方法是统一用kebab-case命名，或者在config.json里配置tokenCase: "camelCase"让Generator自动转换。

5.2 代码生成阶段的常见异常

问题四：生成的React组件缺少TypeScript类型定义

impeccable默认生成的是JavaScript代码，如果你需要TypeScript，需要在config.json里设置language: "typescript"。设置之后，Generator会生成.tsx文件和对应的类型定义。但要注意，TypeScript模式下，Generator对props的类型推断可能不够准确，比如actions这个prop会被推断成any，你需要手动改成React.ReactNode。

问题五：生成的CSS在Safari上显示异常

这个问题通常是因为Generator生成的CSS里用了某些Safari不支持的特性，比如aspect-ratio在Safari 14以下不支持，gap在Flexbox布局里Safari 14.1以下不支持。解决方法是配置config.json里的browserTarget字段：

{ "browserTarget": { "safari": "14.1", "chrome": "90", "firefox": "88" } }

Generator会根据目标浏览器版本自动添加fallback样式，比如用padding-top的百分比来模拟aspect-ratio。

问题六：生成的组件样式被全局样式覆盖

这个问题在用了CSS Modules的项目里比较常见。原因是CSS Modules生成的类名虽然做了哈希处理，但如果你在全局样式里写了button { ... }这样的元素选择器，还是会影响到组件内部的按钮。解决方法是配置config.json里的cssModulesMode: "pure"，让Generator在生成样式时只使用类选择器，不使用元素选择器。另外，在全局样式里尽量避免直接写元素选择器，用类选择器代替。

5.3 运行时校验阶段的排查思路

问题七：Browser Extension无法加载Figma解析数据

Extension加载解析数据时，需要读取.impeccable/parsed/目录下的JSON文件。如果Extension提示“No parsed data found”，先检查文件路径是否正确。Extension默认读取的是项目根目录下的.impeccable/parsed/，如果你的项目结构比较特殊，比如monorepo里子项目的根目录不是仓库根目录，需要在Extension的设置里手动指定路径。

问题八：Extension比对结果里出现大量误报

误报通常有两个原因。一是设计稿里的某些元素在实现时用了不同的HTML结构，比如设计稿里是一个div，实现时用了section，Extension在比对时会认为结构不一致。这种情况下，可以在Extension的设置里开启“Ignore structure”选项，只比对样式。二是设计稿里的某些样式是动态的，比如hover状态、focus状态，Extension在静态页面上比对时会认为样式缺失。这种情况下，可以在Extension里手动触发对应的交互状态，再重新比对。

问题九：Checker报了大量warning但不知道从哪改起

Checker的输出是按文件分组的，每个warning会显示行号和具体的修改建议。如果warning太多，建议先按严重程度过滤，只处理error级别的。error级别的warning通常是硬编码颜色，这个必须改，因为颜色不一致会直接影响品牌一致性。warning级别的间距问题可以批量处理，用编辑器的查找替换功能，把硬编码的padding: 16px替换成padding: var(--spacing-md)。info级别的字号问题可以暂时忽略，等后续迭代时再逐步替换。

5.4 常见问题速查表

最后再分享一个小技巧：impeccable的CLI支持--dry-run参数，加上这个参数之后，Generator不会真正写入文件，而是把生成结果输出到stdout。这个功能在调试模板时特别有用，你可以快速预览生成结果，确认没问题之后再去掉--dry-run正式生成。我一般在修改了design-tokens.json或者自定义模板之后，都会先跑一次--dry-run，避免生成一堆需要回滚的文件。

这个工具我用了大概两个月，最大的体会是它把前端设计还原这件事从“手工作业”变成了“半自动化流水线”。你仍然需要理解设计系统、理解CSS、理解组件化，但那些重复的、机械的、容易出错的转录工作，可以交给它来做。它不是银弹，但确实是一个能让你少加几天班的实用工具。后续我打算把它的Checker集成到团队的CI流程里，每次PR都自动跑一遍样式规范校验，从源头上保证代码质量的一致性。