figma-make-project-converter

Figma Make Project Conversion Specification

Convert a Vite + React project exported from Figma Make into a page component or theme for this project, preserving the visual effect, style tokens, and component structure as much as possible.

Core Goals

• Keep the page visuals and hierarchy consistent
• Remove dependence on Figma Make's original Vite entry and versioned aliases
• Produce page components or themes that can continue to evolve in this project

How to Use

Step 1: Run the preprocessing script

Recommended input source:

• Prefer to use the Figma original exported ZIP project package
• The system first unzips the ZIP, then passes the unzipped project directory to this script
• It is not recommended to manually unzip and then pick files, delete files, or reorganize directories, as this easily damages the original Figma project structure and reduces the stability of subsequent imports

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

The script will automatically complete:

• Fully copy the Figma Make project to src/prototypes/[页面名]/ or src/themes/[theme-key]/
• Exclude node_modules、.npm-local-cache、build
• Convert @/ to a relative path
• Change the package@version imports in the source code to bare package names
• Analyze components, pages, dependencies, CSS, and design documents
• Generate AI work documents and analysis reports

Step 2: Complete the conversion according to the task checklist

Focus on checking:

• .figma-make-tasks.md
• .figma-make-analysis.json
• In theme mode, the .figma-make-theme-tasks.md

Figma Make Project Characteristics

Typical structure:

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

When importing, the directory structure in this original ZIP should be treated as the authoritative structure, especially:

• 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

Note:

• Attributions.md、guidelines/Guidelines.md、README.md、TOKEN_REFERENCE.md、DESIGN_SYSTEM_GUIDE.md Files such as these are normal components in the original Figma export and should not be mistakenly judged as abnormal junk files
• The focus during conversion is not to delete these files, but to identify which files are real dependencies of the page and which are documentation

Key judgment:

• This is a Vite + React project, not Next.js
• No need to handle "use client"
• vite.config.ts in package@version aliases are only an export compatibility layer and should not be used as a final runtime prerequisite

Keep the original files required for export

If the imported directory already contains the following Figma Make original assets, they must be kept during subsequent conversion; do not delete them or overwrite them with unrelated content:

• canvas.fig: Figma Make's binary design data, used for subsequently writing back the source code and exporting 名称.fig
• meta.json: Project metadata, keep at least file_name、exported_at、client_meta
• ai_chat.json: AI chat history, can be an empty object {}
• thumbnail.png: Project thumbnail
• canvas.code-manifest.json：canvas.fig in CODE_FILE index manifest
• images/: Design draft image assets, usually hash-named, do not rename them arbitrarily

If the figmaMakeAssets field appears in the script analysis report, it means these files have already been kept in the import directory, and AI still needs to keep them when subsequently organizing the page structure.

Page Conversion Rules

Fixed Directory Structure

To accommodate both the Axhub runtime and subsequent .fig exports, the page directory uses the following fixed structure by default:

<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

When converting, please comply with:

• The real visuals and interactive main body of the page should be deposited first into src/components/**
• root directory index.tsx Only responsible for Axhub runtime data, events, and variable adaptation
• src/App.tsx Only responsible for mounting the shared page body
• style.css / src/index.css Try to only do style bridging, do not repeatedly pile up business styles
• In index.tsx、src/App.tsx、src/main.tsx write responsibility comments at the top to remind future maintainers not to let the entry point drift

The final project after executing this skill must conform to this fixed structure; if the current output still has two entry points each maintaining its own set of page logic, it is considered an incomplete conversion.

Page component specification

By default, first convert to a normal React page component. Only when there is a clear need to integrate Axhub / Axure runtime capabilities should you additionally introduce forwardRef and axure-types。

Recommended format:

import './style.css';
import React from 'react';

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

Entry point convergence

• Prefer to converge from src/App.tsx to this project's index.tsx
• src/main.tsx is only used as a reference for the original mount entry point, and is not retained as the final runtime entry point
• If src/pages/ + there are many routes, the final result must still converge to this project's single-entry page component
• If the page will later need to be re-exported as a Figma asset, be sure to maintain in reverse an export shell index.tsx synchronized with the root directory src/App.tsx
• The safest way is to keep src/App.tsx as thin as possible, only doing wrapping or directly reusing the current page component, to avoid two sets of page logic drifting apart over time

Paths and alias

• @/ uniformly treated as ./src
• If the source code still contains package@version imports, continue changing them to bare package names
• vite.config.ts can be kept for reference, but the final component must not depend on its alias to run

Style handling rules

Figma Make's src/index.css is often a Tailwind v4 build artifact, and by default should not be directly carried over as the final style.css。

style.css generation strategy

The final page's style.css uses:

@import "tailwindcss";

Then continue organizing with src/styles/globals.css as the main style source.

Rules:

• src/styles/globals.css is the main style source
• src/index.css is only used as a visual regression reference
• If globals.css is missing, then fill it in based on the component's existing styles
• If the page will later need to be re-exported as .fig, you need to also ensure that the src/index.css used by the export shell stays consistent with the final style.css , at least not obviously drifting

Dependency handling

Keep the runtime dependencies that are needed, and by default exclude:

• react
• react-dom
• next-themes

If the analysis report contains dependencies other than these packages, execute as needed:

pnpm add <依赖名>

Theme import rules

When the target is themes , prefer to extract tokens from the following sources:

• DESIGN_SYSTEM_GUIDE.md
• TOKEN_REFERENCE.md
• src/styles/globals.css
• CSS variables and design semantics in the component

Expected output:

• src/themes/<theme-key>/globals.css or designToken.json
• src/themes/<theme-key>/DESIGN-SPEC.md
• src/themes/<theme-key>/index.tsx

At the same time, supplement as needed:

• src/docs/
• src/database/

Acceptance criteria

Page mode:

node scripts/check-app-ready.mjs /prototypes/<page-name>

Acceptance requirements:

• The page renders normally
• No console errors
• The main visuals are basically consistent with the original project
• No longer depends on the original Vite alias to run

Theme mode:

• The token file exists and its structure is complete
• DESIGN-SPEC.md The description is clear
• The theme demo entry point can reflect the core token effects

Common points to note

• Do not treat src/index.css directly as the final style.css
• Do not continue to retain runtime dependence on the package@version alias
• Do not stuff the complete multi-page routing shell into the final page component unchanged
• Prioritize extracting the theme from design documents and CSS variables rather than only looking at visual screenshots
• If the directory already contains canvas.fig、meta.json、images/ and other original assets, do not delete them during conversion
• If the directory already contains src/App.tsx / src/index.css as a Figma export shell, after modifying the root directory pages you must update them synchronously, otherwise the subsequently exported .fig will be inconsistent with the current pages
• After the conversion is complete, clean up src/prototypes/ the extra directories or files generated by this import