react-to-figma-make

Files (7)

• SKILL.md
• empty-canvas.fig · assets/
• meta-json-spec.md · references/
• project-structure.md · references/
• style-migration.md · references/
• canvas-fig-sync.mjs · scripts/
• package.json · scripts/

SKILL.md (first lines)

# 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 目录：

```text
.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` 中可以确认的通用入口和可选路径包括：

| 磁盘路径（相对 `--from`） | `CODE_FILE.logicalPath` | 职责 |
|---|---|---|
| `src/App.tsx` | `App.tsx` | 当前模板的 Figma Make 入口，必须保留 |
| `src/styles/globals.css` | `styles/globals.css` | 当前模板已有的可选样式节点 |
| `src/<manifest 中已有路径>` | 对应 `logicalPath` | 可选业务模块或其他资源 |

当前模板中的 `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>/`：

```text
<page-name>/
├── index.tsx              # 项目主入口

From lintendo/Axhub-Skills, MIT.

More from lintendo/Axhub-Skills