React To Figma Make

React 导出到 Figma Make

概述

本技能将帮助你把 React 组件或应用经过兼容改造后，转换为符合 Figma Make 项目规范的标准结构。转换完成后，项目将具备：

• Figma Make 可编辑性：可在 Figma Make 平台中打开、编辑和迭代
• .fig 导出能力：生成可下载的 .fig 文件
• 双入口架构：同时支持独立运行和 Figma Make 导出
• 设计 Token 保留：保持原始设计系统的 CSS 变量和主题定义
• 资产完整性：包含 meta.json、ai_chat.json、images/ 等 Figma Make 要求的元文件

本技能产出一个完整的 Figma Make 兼容项目目录，并默认把可被宿主工具消费的产物写入通用 artifact 目录：

.axhub/make/artifacts/figma/<resource-id>/
├── canvas.fig
├── meta.json
├── ai_chat.json
├── canvas.code-manifest.json
├── manifest.json
├── images/
└── thumbnail.png            # 可选

如果目标项目使用 .axhub/make/project.json 描述资源，需要在对应 resources.prototypes[].artifacts.figma 中登记这些路径，便于 make-server 或其他宿主直接导出 .fig。

核心原则与当前能力边界

canvas-fig-sync.mjs pack 是模板节点同步器，不是通用的文件系统导入器。

• pack 只更新 canvas.fig 中已经存在的 CODE_FILE.logicalPath。
• 磁盘上新增但模板中不存在的路径不会自动变成新的 CODE_FILE。
• 使用 --prune-missing 时，模板中存在、磁盘上不存在的路径会被删除。
• 使用 --sanitize-for-export 时，聊天历史和代码快照会被清空；如果源码映射错误，无法依赖清理后的 .fig 恢复源码。
• inspect 命令退出成功只证明二进制可解析，不证明源码完整或能够运行。

因此，首次生成前必须先 inspect 模板，并让导出源码路径与模板已有逻辑路径对齐。路径由实际 template manifest 决定，不是 Figma Make 的固定文件名。当前 bundled empty-canvas.fig 中可以确认的通用入口和可选路径包括：

当前模板中的 components/Dashboard.tsx 只是一个历史示例槽位，不是通用规范，也不代表目标页面必须是 Dashboard。只有当本次转换明确选择该现有槽位时才能使用它。如果原页面依赖多个模板未覆盖的本地模块，优先使用项目现有构建工具把业务代码机械打包到 src/App.tsx，或打包到本次从 manifest 中明确选定的已有槽位。不要把业务逻辑手工重写成另一套实现；保留原页面入口，把导出壳作为可重复生成、可持续同步的独立适配层。

何时使用

• 你有一个现成的 React 项目，希望导入 Figma Make 进行可视化编辑
• 你需要从 React 代码生成 .fig 文件用于设计交付
• 你希望在 Figma Make 和代码编辑器之间双向协作
• 你有一个 V0 / AI Studio / 自建 React 项目，想把它纳入 Figma Make 生态

环境要求

本技能分为两部分：

1. 项目结构转换（通用）：将 React 项目改造为 Figma Make 目录规范 — 任何环境均可执行
2. canvas.fig 生成与验证：本技能内置了相关的操作脚本，位于技能自身的目录下：
   • scripts/canvas-fig-sync.mjs：canvas.fig 回写与检查工具
   • assets/empty-canvas.fig：空白 canvas 模板
   • 脚本运行依赖 pako 和 kiwi-schema。先直接运行一次；如果出现 ERR_MODULE_NOT_FOUND，在脚本所属包中按宿主项目规定的包管理器安装依赖，不要向目标原型的运行时依赖中添加这两个包。

如果有额外的页面渲染验收脚本，也可以在此阶段执行。

引用文件

本技能附带以下参考文件，在转换特定技术领域时按需查阅：

• references/project-structure.md：Figma Make 项目的完整目录结构和文件职责说明
• references/meta-json-spec.md：meta.json 的完整字段定义和示例
• references/style-migration.md：从各种 CSS 方案迁移到 Figma Make 样式体系的指南

转换工作流程

第 1 步：分析源项目

分析目标 React 项目的以下方面：

1. 框架识别：

   • 纯 React（Vite / CRA / 自定义）
   • Next.js（需要移除 SSR、"use client"、next/image 等）
   • AI Studio（Import Map + CDN 模式）
   • 其他元框架

2. 入口结构：

   • 主应用组件在哪里（通常是 App.tsx 或 page.tsx）
   • 挂载入口在哪里（main.tsx / index.tsx）
   • 是否有路由（多路由需收敛为单入口）

3. 样式方案：

   • Tailwind CSS（CDN / PostCSS / v4）
   • CSS Modules
   • Styled Components / Emotion
   • 纯 CSS / SCSS
   • CSS 变量 / 设计 Token

4. 依赖分析：

   • 核心依赖（React、ReactDOM — 外部化，不打包）
   • UI 框架（Ant Design、shadcn/ui、Radix 等 — 保留）
   • 图表库、动画库等 — 保留并确认兼容性
   • 框架特定依赖（Next.js、Vercel — 移除）

5. 静态资源盘点（对大型项目尤其重要）：

   • 图片：格式、数量、总大小、引用方式（import / public / CDN）
   • 字体：本地文件 vs CDN 引用
   • 视频/音频等其他媒体
   • SVG：是否作为 React 组件使用

输出一份转换清单，列出需要处理的各项转换任务。

第 2 步：创建 Figma Make 项目结构

在目标目录 <output-dir>/<page-name>/ 下创建以下固定结构；最终可消费产物同步到 .axhub/make/artifacts/figma/<resource-id>/：

<page-name>/
├── index.tsx              # 项目主入口
├── style.css              # 根入口样式（桥接层）
├── canvas.fig             # Figma 二进制设计数据（第 5 步生成）
├── meta.json              # 项目元数据
├── ai_chat.json           # AI 聊天历史（可为空 {}）
├── canvas.code-manifest.json  # CODE_FILE 索引清单（第 5 步生成）
├── package.json           # Vite 项目依赖声明
├── vite.config.ts         # Vite 构建配置
├── index.html             # Vite HTML 入口
├── images/                # 设计稿图片资源
└── src/
    ├── App.tsx            # Figma Make 导出薄壳（导出入口）
    ├── main.tsx           # Vite 挂载层
    ├── index.css          # Figma Make 入口样式
    ├── components/        # 可选；仅使用 template manifest 已存在的路径
    ├── pages/             # 多页面（如需要）
    └── styles/
        └── globals.css    # 全局样式 / 设计 Token

.axhub/make/project.json 中的资源元数据示例：

{
  "artifacts": {
    "figma": {
      "resourceId": "home",
      "canvasFigPath": ".axhub/make/artifacts/figma/home/canvas.fig",
      "metaPath": ".axhub/make/artifacts/figma/home/meta.json",
      "aiChatPath": ".axhub/make/artifacts/figma/home/ai_chat.json",
      "codeManifestPath": ".axhub/make/artifacts/figma/home/canvas.code-manifest.json",
      "imagesDir": ".axhub/make/artifacts/figma/home/images",
      "manifestPath": ".axhub/make/artifacts/figma/home/manifest.json"
    }
  }
}

职责分层约束（这是验收约束，不是建议）：

第 3 步：迁移和改造源代码

3.1 收敛入口

将源项目的所有页面逻辑收敛为两个薄入口 + 一套共享组件。

根目录 index.tsx（项目主入口）：

/**
 * 项目主入口
 */
import './style.css';
import React from 'react';
import App from './src/App';

export default function PageName() {
  return <App />;
}

src/App.tsx（Figma Make 导出壳）：

/**
 * Figma Make 导出薄壳
 * 将根入口及其本地依赖机械同步到这个入口，
 * 或同步到 template manifest 中明确存在的其他逻辑路径。
 */
import React from 'react';
import './styles/globals.css';

export default function App() {
  return <main>{/* 机械同步或打包后的页面主体 */}</main>;
}

src/main.tsx（Vite 挂载层）：

/**
 * Vite 开发挂载层
 * 仅用于 Figma Make 独立开发预览
 */
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

关键原则：

• 两个入口（index.tsx 和 src/App.tsx）必须渲染相同的页面内容
• 页面主体可以直接机械打包到 src/App.tsx，也可以拆分到 template manifest 已存在的逻辑路径
• 不要硬编码 Dashboard.tsx、AppContent.tsx 或其他项目语义文件名；先检查模板再选择路径
• 不要创建模板中不存在的路径后假设 pack 会自动加入
• 若源项目有多页路由，收敛为单页面或选择核心页面

3.2 处理框架特定代码

根据源项目的框架类型，进行针对性清理：

Next.js 项目：

// ❌ 移除
"use client"
import { useRouter } from 'next/navigation'
import Image from 'next/image'
import Link from 'next/link'
import type { Metadata } from 'next'

// ✅ 替换
// 删除 "use client"
// 删除 useRouter，改用 useState 管理页面状态
<img> 替代 <Image>
<a> 替代 <Link>

AI Studio 项目：

// ❌ 移除
// Import Map 依赖（CDN URL）
// index.html 中的 <script type="importmap">

// ✅ 替换
// CDN 导入改为 npm 包导入
// process.env.* 改为 import.meta.env.VITE_*

通用清理：

// ❌ 移除
import { Analytics } from '@vercel/analytics/next'
// 所有 SSR 相关代码

// ✅ 保留
// React Hooks
// 第三方 UI 组件
// 样式文件导入

3.3 处理路径别名

将所有非标准路径别名转换为相对路径：

// 源代码中的 @/ 别名
import { Button } from '@/components/ui/button'

// 转换为相对路径（基于文件位置）
import { Button } from './components/ui/button'   // 从 src/App.tsx
import { Button } from '../components/ui/button'  // 从 src/pages/xxx.tsx

如果源项目使用 package@version 格式的导入（Figma Make 导出特征），改为裸包名：

// ❌
import { motion } from 'framer-motion@11.0.0'

// ✅
import { motion } from 'framer-motion'

3.4 处理大型静态资源

React 项目通常包含大量图片、字体和其他二进制文件。转换时需要妥善处理这些资源：

图片资源迁移：

images/ 目录规则：

• Figma Make 的 images/ 目录存放设计稿关联图片，通常以 hash 命名（如 a3f2c1d.png）
• 源项目的业务图片优先保留在 src/assets/，不必强制移到 images/
• 只有从 Figma Make 导入时自带的 images/ 内容才需要保留原始 hash 名

字体文件：

• 本地字体文件放入 src/assets/fonts/
• 在 src/styles/globals.css 中用 @font-face 引用
• Google Fonts 等 CDN 字体直接保留 @import url(...) 链接

大文件注意事项：

• canvas.fig 是二进制文件（通常几百 KB 到几 MB），不能手动编辑，只能通过工具生成
• 不要把源项目的 node_modules/、build/、.next/ 等目录复制到产物中
• 如果源项目的图片总量超过 50 张或 10 MB，考虑精简为核心页面所需的子集

3.5 迁移样式

目标：根入口 style.css 和导出入口 src/index.css 使用同一套样式来源。

style.css（根入口样式）：

@import "tailwindcss";

/* 如果有 globals.css，通过 import 引入 */
@import "./src/styles/globals.css";

src/index.css（Figma 导出样式）：

@import "tailwindcss";

/* 保持与 style.css 一致的样式来源 */
@import "./styles/globals.css";

src/styles/globals.css（主样式文件）：

将源项目中的以下内容迁移到此文件：

• CSS 变量 / 设计 Token
• @theme 定义（Tailwind v4）
• 全局基础样式
• 自定义字体引用
• 自定义动画定义

样式迁移策略（详细指南见 references/style-migration.md）：

大型样式文件注意事项：

• Figma Make 导出的 src/index.css 有时是 Tailwind 的完整编译产物（可达数万行），不要直接使用它作为最终样式
• 应以 src/styles/globals.css 为主样式源，src/index.css 仅做样式桥接

第 4 步：创建 Figma Make 元文件

4.1 meta.json

{
  "client_meta": {
    "background_color": { "r": 0.96, "g": 0.96, "b": 0.96, "a": 1 },
    "thumbnail_size": { "width": 400, "height": 300 },
    "render_coordinates": { "x": 0, "y": 0, "width": 1280, "height": 960 }
  },
  "file_name": "<项目显示名称>",
  "developer_related_links": [],
  "exported_at": "<ISO 8601 时间>"
}

• file_name：最终导出的 .fig 文件显示名称
• render_coordinates：页面视口尺寸，根据实际页面调整 width 和 height（详见 references/meta-json-spec.md）
• exported_at：使用当前 ISO 8601 时间（new Date().toISOString()）

4.2 ai_chat.json

{}

新建项目时为空对象即可。

4.3 package.json

{
  "name": "<page-name>",
  "private": true,
  "version": "0.0.1",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
  },
  "devDependencies": {
    "vite": "^6.0.0",
    "@vitejs/plugin-react": "^4.0.0",
    "typescript": "^5.0.0"
  }
}

依赖规则：

• 排除：react、react-dom、next、next-*、@vercel/*、next-themes
• 保留：所有其他运行时依赖（UI 库、工具库、图标库等）
• 使用项目所用的包管理器安装依赖（npm / yarn / pnpm 均可）

4.4 vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src'
    }
  }
});

4.5 index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title><项目名称></title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

4.6 images/ 目录

创建空的 images/ 目录。此目录用于存放 Figma Make 设计稿关联的图片资源。

• 如果是从 Figma Make 导入的项目，保留 images/ 下已有的 hash 命名图片
• 源项目的业务图片建议保留在 src/assets/ 中，不必移入 images/