AI 驱动的组件代码生成：从设计规范到可复用组件的智能推导

一、设计到代码的鸿沟：为什么"像素级还原"仍是手工活

前端开发中，将设计稿转化为可复用组件是最耗时的环节之一。设计师在 Figma 中定义了按钮的 6 种状态（默认、悬停、按下、聚焦、禁用、加载），但开发者需要手动将这些视觉规范翻译为 CSS 变量、状态样式和交互逻辑。一个中等复杂度的组件库通常包含 50-100 个组件，每个组件的状态组合可能达到 10+ 种，手工还原的工作量巨大。

更深层的问题是"设计-代码漂移"——设计稿更新后，代码中的样式可能未同步修改，导致视觉回归。传统方案依赖人工比对和视觉回归测试，效率低下且覆盖不全。

二、AI 组件生成架构：从设计 Token 到组件代码的推导链路

AI 驱动的组件生成核心思路是：从设计文件中提取结构化 Token（颜色、间距、字体、圆角等），结合组件语义（按钮、输入框、卡片等），推导出可运行的组件代码。

flowchart TD
    A[Figma 设计稿] --> B[设计 Token 提取<br/>颜色/间距/字体/圆角]
    B --> C[组件结构识别<br/>层级/嵌套/变体]
    C --> D[语义标注<br/>按钮/输入框/卡片]
    D --> E[LLM 代码生成]
    E --> F[组件代码<br/>HTML + CSS + JS]
    F --> G[代码质量校验<br/>ESLint / Stylelint]
    G --> H[视觉回归测试<br/>Chromatic / Percy]
    H --> I[可复用组件]

关键设计决策在于 Token 提取的精度和语义标注的准确性。Token 提取依赖 Figma API，但设计稿中的样式命名不规范（如"Rectangle 42"）会干扰语义识别。LLM 可以补全语义信息，但需要提供足够的上下文。

三、工程实现：Token 提取、代码生成与质量校验

3.1 设计 Token 提取

interface DesignToken {
  name: string;
  type: 'color' | 'spacing' | 'typography' | 'border' | 'shadow';
  value: string;
  description?: string;
}

class FigmaTokenExtractor {
  private figmaClient: FigmaClient;

  async extractTokens(fileKey: string): Promise<DesignToken[]> {
    const file = await this.figmaClient.getFile(fileKey);
    const tokens: DesignToken[] = [];

    // 遍历所有页面和画板
    for (const page of file.document.children) {
      if ('children' in page) {
        for (const node of page.children) {
          this.extractNodeTokens(node, tokens);
        }
      }
    }

    // 去重并规范化命名
    return this.deduplicateAndNormalize(tokens);
  }

  private extractNodeTokens(
    node: FigmaNode,
    tokens: DesignToken[]
  ): void {
    // 提取颜色 Token
    if ('fills' in node) {
      for (const fill of node.fills as Paint[]) {
        if (fill.type === 'SOLID' && fill.visible !== false) {
          tokens.push({
            name: this.inferTokenName(node.name, 'color'),
            type: 'color',
            value: this.rgbToHex(fill.color),
          });
        }
      }
    }

    // 提取间距 Token
    if ('paddingLeft' in node) {
      const paddings = [
        node.paddingLeft, node.paddingRight,
        node.paddingTop, node.paddingBottom
      ].filter(v => v > 0);
      if (paddings.length > 0) {
        tokens.push({
          name: this.inferTokenName(node.name, 'spacing'),
          type: 'spacing',
          value: `${Math.min(...paddings)}px`,
        });
      }
    }

    // 递归处理子节点
    if ('children' in node) {
      for (const child of node.children) {
        this.extractNodeTokens(child, tokens);
      }
    }
  }

  private inferTokenName(
    nodeName: string,
    tokenType: string
  ): string {
    // 从节点名称推断语义化 Token 名
    // "Primary Button" → "color-primary-button"
    const sanitized = nodeName
      .toLowerCase()
      .replace(/[^a-z0-9]+/g, '-');
    return `${tokenType}-${sanitized}`;
  }
}

3.2 LLM 组件代码生成

interface ComponentSpec {
  name: string;
  category: string;  // button / input / card / modal
  variants: Variant[];
  tokens: DesignToken[];
  accessibility: A11ySpec;
}

class ComponentCodeGenerator {
  private llmClient: LLMClient;

  async generate(spec: ComponentSpec): Promise<ComponentCode> {
    const prompt = this.buildPrompt(spec);
    const response = await this.llmClient.chat(prompt);

    // 解析 LLM 返回的代码
    return this.parseComponentCode(response);
  }

  private buildPrompt(spec: ComponentSpec): string {
    return `根据以下设计规范生成 React + TypeScript 组件代码。

组件名称：${spec.name}
组件类别：${spec.category}
变体列表：${JSON.stringify(spec.variants, null, 2)}
设计 Token：${JSON.stringify(spec.tokens, null, 2)}
无障碍规范：${JSON.stringify(spec.accessibility, null, 2)}

要求：
1. 使用 CSS Variables 引用设计 Token
2. 支持所有变体（通过 props 切换）
3. 包含完整的 TypeScript 类型定义
4. 实现键盘导航和 ARIA 属性
5. 使用 forwardRef 支持 ref 传递
6. 导出组件和所有相关类型

请生成以下文件内容：
- Component.tsx（组件实现）
- component.css（样式文件）
- types.ts（类型定义）`;
  }
}

3.3 代码质量校验

class ComponentQualityChecker {
  async check(code: ComponentCode): Promise<QualityReport> {
    const issues: QualityIssue[] = [];

    // 1. TypeScript 类型检查
    const typeErrors = await this.runTypeCheck(code.tsx);
    issues.push(...typeErrors.map(e => ({
      severity: 'error' as const,
      category: 'type',
      message: e.message,
      line: e.line,
    })));

    // 2. 无障碍检查
    const a11yIssues = this.checkAccessibility(code.tsx);
    issues.push(...a11yIssues);

    // 3. CSS 变量引用检查
    const cssVarIssues = this.checkCSSVariableUsage(
      code.css, code.tsx
    );
    issues.push(...cssVarIssues);

    // 4. 变体覆盖率检查
    const variantCoverage = this.checkVariantCoverage(code);
    if (variantCoverage < 1.0) {
      issues.push({
        severity: 'warning',
        category: 'coverage',
        message: `变体覆盖率 ${variantCoverage * 100}%，`
                 + `部分变体未实现`,
      });
    }

    return {
      passed: !issues.some(i => i.severity === 'error'),
      issues,
      variantCoverage,
    };
  }
}

四、AI 组件生成的精度边界与工程权衡

Token 提取的语义歧义：设计稿中的样式命名不规范是最大障碍。"Rectangle 42"无法推断出语义，需要设计师配合使用规范的命名（如"Button/Primary/Background"）。LLM 可以基于上下文补全语义，但准确率约 70%-80%，仍需人工审核。

生成代码的可维护性：LLM 生成的代码可能不符合团队的编码规范（如 hooks 使用顺序、状态管理模式）。需要通过 ESLint 和自定义规则做后处理，但后处理可能引入新的错误。建议将 LLM 输出视为"初稿"，由开发者审核和调整。

变体组合爆炸：一个按钮组件可能有 3 种尺寸 × 4 种颜色 × 2 种圆角 = 24 种组合。LLM 难以一次性生成所有组合的样式，需要分批生成或使用 CSS 变量 + 条件类的组合策略。

设计变更的同步成本：设计稿更新后，需要重新提取 Token 并对比变更。增量更新比全量重新生成更高效，但增量更新的 diff 算法需要处理 Token 重命名、合并和删除等复杂场景。

五、总结

AI 驱动组件生成的本质是将"手工翻译设计稿"转化为"Token 提取 + 语义推导 + 代码生成"的自动化管线。本文方案的核心链路为：Figma Token 提取 → 组件语义标注 → LLM 代码生成 → 质量校验与修正。落地时需重点关注三个参数：Token 命名规范覆盖率（建议 90% 以上）、变体实现覆盖率（建议 100%）、生成代码的类型检查通过率（建议 100%）。建议从简单组件（按钮、标签、徽章）开始验证，逐步扩展到复杂组件（表格、表单、对话框），并建立设计-代码同步的自动化流程。