figma-make-project-converter

Files (1)

• SKILL.md

SKILL.md (first lines)

# Figma Make 项目转换规范

将 Figma Make 导出的 Vite + React 项目转换为本项目页面组件或主题，尽量保持视觉效果、样式 token 和组件结构。

## 核心目标

- 保持页面视觉与层级结构一致
- 移除对 Figma Make 原始 Vite 入口和版本化 alias 的依赖
- 产出可在本项目中继续演化的页面组件或主题

## 使用方式

### 步骤 1：运行预处理脚本

推荐输入来源：

- 优先使用 **Figma 原始导出的 ZIP 工程包**
- 由系统先解压 ZIP，再把解压后的项目目录传给本脚本
- 不建议手工解压后再挑文件、删文件或重组目录，否则容易破坏 Figma 原始项目结构，降低后续导入稳定性

```bash
node scripts/figma-make-converter.mjs <figma-make-project-dir> [output-name]

# 示例
node scripts/figma-make-converter.mjs "temp/my-figma-make-project" my-page
node scripts/figma-make-converter.mjs "temp/my-figma-make-project" brand-theme --target-type themes
```

脚本会自动完成：
- 完整复制 Figma Make 项目到 `src/prototypes/[页面名]/` 或 `src/themes/[theme-key]/`
- 排除 `node_modules`、`.npm-local-cache`、`build`
- 转换 `@/` 为相对路径
- 将源码中的 `package@version` 导入改为裸包名
- 分析组件、页面、依赖、CSS、设计文档
- 生成 AI 工作文档和分析报告

### 步骤 2：按任务清单完成转换

重点查看：
- `.figma-make-tasks.md`
- `.figma-make-analysis.json`
- 主题模式下的 `.figma-make-theme-tasks.md`

## Figma Make 项目特征

典型结构：

```text
figma-make-project/
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── index.css
│   ├── DESIGN_SYSTEM_GUIDE.md
│   ├── TOKEN_REFERENCE.md
│   ├── components/
│   ├── pages/
│   ├── styles/globals.css
│   └── guidelines/
├── index.html
├── package.json
└── vite.config.ts
```

导入时应把这套原始 ZIP 中的目录结构视为权威结构，尤其是：

- `src/App.tsx`
- `src/main.tsx`
- `src/index.css`
- `src/styles/globals.css`
- `src/components/**`
- `src/pages/**`
- `src/guidelines/**`
- `package.json`
- `vite.config.ts`
- `index.html`

说明：

- `Attributions.md`、`guidelines/Guidelines.md`、`README.md`、`TOKEN_REFERENCE.md`、`DESIGN_SYSTEM_GUIDE.md` 这类文件在 Figma 原始导出中是正常组成部分，不应误判为异常垃圾文件
- 转换时的重点不是删掉这些文件，而是识别哪些文件是页面真实依赖，哪些是说明文档

关键判断：
- 这是 **Vite + React** 项目，不是 Next.js
- 不需要处理 `"use client"`
- `vite.config.ts` 里的 `package@version` alias 只是导出兼容层，不应作为最终运行前提

## 保留导出所需的原始文件

如果导入后的目录中已经包含以下 Figma Make 原始资产，后续转换时必须保留，不要删除或覆盖为无关内容：

- `canvas.fig`：Figma Make 的二进制设计数据，用于后续回写源码并导出 `名称.fig`
- `meta.json`：项目元数据，至少保留 `file_name`、`exported_at`、`client_meta`
- `ai_chat.json`：AI 聊天历史，可为空对象 `{}`
- `thumbnail.png`：项目缩略图
- `canvas.code-manifest.json`：`canvas.fig` 中 `CODE_FILE` 的索引清单
- `images/`：设计稿图片资源，通常为 hash 命名，不要随意重命名

如果脚本分析报告里出现 `figmaMakeAssets` 字段，说明这些文件已经被保留在导入目录中，AI 在后续整理页面结构时仍需继续保留它们。

## 页面转换规则

### 固定目录结构

为了兼顾 Axhub 运行时和后续 `.fig` 导出，页面目录默认采用以下固定结构：

```text
<page>/
├── index.tsx          # Axhub runtime adapter only
├── style.css          # root style bridge only
└── src/
    ├── App.tsx        # Figma export shell only
    ├── main.tsx       # Vite mount only
    ├── index.css      # Figma style bridge only
    ├── components/    # shared page implementation
    └── styles/        # shared page styles
```

转换时请遵守：

From fern-ok/prototype-demo, Apache-2.0.

More from fern-ok/prototype-demo