# figma-to-react-mcp

An MCP server that helps Claude (or any MCP client) turn a whole **Figma file into a React project** using **Ant Design v5**, **AG Grid** (for all tables), **ApexCharts** (for all charts), and **Tailwind CSS** (for layout/styling) — and optionally export the **mobile-only screens as a React Native (Expo) app**.

> **Whole-file conversion:** `convert_figma_to_react` now takes a whole Figma **file** and generates one page per top-level screen across every page/canvas — not one frame at a time. When it finds mobile-only screens (width ≤ 480px) it **asks whether to also export them as a React Native app**.

It does the heavy lifting the model can't do well on its own:
- pulls the design from the Figma API and **simplifies** the giant node tree into a compact, token-efficient structure — **collapsing repeated rows/cards, pruning pass-through wrappers, truncating large tables** to a few sample rows, and **stripping chart nodes down to their text** (legend/axis labels) since the plotted vectors are useless to the model,
- returns that tree as a **compact outline** (~half the tokens of pretty JSON) instead of a giant JSON dump,
- attaches a **semantic role** and **suggested Tailwind classes** to each node,
- **generates ready-to-use `.tsx`** — antd components by role, Tailwind for layout, AG Grid (with `columnDefs` derived from table headers) for tables, ApexCharts (`<ReactApexChart>` with the chart type guessed from the layer name and labels/categories lifted from the design's text) for charts, repeated rows expanded to `.map()`,
- **scaffolds and writes a whole Vite project to disk** (package.json, tailwind config, CSS vars, antd `ConfigProvider` theme, a shared ApexCharts palette from the design's colors) so boilerplate never enters the model's context,
- extracts **design tokens**, exports **icons/images**,
- ships a **conversion guide** (as a tool, prompt, and resource) so generated code follows the antd + AG Grid + ApexCharts + Tailwind conventions consistently.

## Tools

| Tool | What it does |
|---|---|
| `convert_figma_to_react` | **Whole file, one-shot.** Fetch → tokens → enumerate **every screen** across all pages → scaffold project → generate **one page per screen**, all **written to `outDir`**. Detects mobile-only screens (≤480px) and **asks whether to also export them as a React Native (Expo) app** (written to `<outDir>-mobile`). Returns a short summary only. |
| `get_figma_design` | Fetch a file/frame → **compact outline** (or minified JSON) with roles + Tailwind hints, repeats collapsed. **Call first** for manual flows. |
| `scaffold_react_project` | Generate the full Vite + antd + AG Grid + ApexCharts + Tailwind skeleton with tokens wired in, written to disk. |
| `generate_component` | Turn one frame into a ready-to-use `.tsx` (antd + Tailwind + AG Grid + ApexCharts). Writes to disk or returns the code. |
| `extract_design_tokens` | Colors, type, spacing, radii, shadows → tailwind config + CSS vars + antd theme. |
| `download_figma_images` | Render node ids to svg/png/jpg URLs; optionally save to disk. |
| `get_conversion_guide` | The mapping rules (also a prompt `figma_to_react` and resource `guide://figma-to-react`). |

### Why this uses fewer tokens
- The design comes back as an **indented outline** with repeated siblings collapsed (`x40`) and big tables truncated to a header + a few sample rows — not the full node tree as pretty JSON.
- **Generated code and project boilerplate are written to disk**, so they never pass through the model's context. `convert_figma_to_react` returns only a summary (files written, primary color).
- The model's job shrinks from *writing every component from a huge tree* to *refining a working scaffold*.

## Setup

1. **Get a Figma token:** figma.com → Settings → *Personal access tokens*. Copy `.env.example` to `.env` and paste it in (or pass it via the client config below).
2. **Install & build:**
   ```bash
   npm install
   npm run build
   ```
3. **Point your MCP client at it** (examples below), using an absolute path to `dist/index.js`.

### Claude Desktop / Cursor (`mcpServers` JSON)
```json
{
  "mcpServers": {
    "figma-to-react": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/figma-to-react-mcp/dist/index.js"],
      "env": { "FIGMA_ACCESS_TOKEN": "figd_your_token_here" }
    }
  }
}
```

### Claude Code (CLI)
```bash
claude mcp add figma-to-react \
  --env FIGMA_ACCESS_TOKEN=figd_your_token_here \
  -- node /ABSOLUTE/PATH/figma-to-react-mcp/dist/index.js
```

Restart the client, then try: *"Use figma_to_react on `<your Figma frame URL>`."*

## Typical flow the model follows

**Fast path (server does the lifting):**
1. `convert_figma_to_react` with `{ figmaUrl, outDir }` (pass a whole file URL or bare file key) → fetches, tokenizes, enumerates every top-level screen, scaffolds the project, and generates one page per screen to disk. Returns a short summary.
2. If the file has mobile-only screens (≤480px), the tool **asks** whether to also export them as an Expo React Native app. Clients that support MCP *elicitation* show this prompt inline; otherwise pass `exportMobileToReactNative: true` (or `false`) explicitly. The Expo app is written to `<outDir>-mobile` (override with `reactNativeOutDir`).
3. `download_figma_images` → pull any icons/images.
4. Open the generated files and refine: wire real data into AG Grid `rowData` and ApexCharts `series`, fix any roles the heuristics missed, snap arbitrary Tailwind values (`p-[16px]`) to the token scale (`p-4`).

Tune mobile detection with `mobileMaxWidth` (default `480`). The web project builds the desktop screens; if the file is entirely mobile it builds all of them so the web app isn't empty.

**Finer control:**
1. `get_conversion_guide` → learn the rules.
2. `get_figma_design` → compact outline of the design.
3. `scaffold_react_project` → project skeleton + tokens on disk.
4. `generate_component` per frame → `.tsx` scaffolds.
5. `download_figma_images` → icons/images.

Either way: **every table becomes AG Grid**, **every chart becomes ApexCharts** (typed `ApexOptions`, palette from `src/charts/chart-theme.ts`), everything else maps to antd where a role matches, Tailwind handles layout.

## Notes & limitations
- Uses Figma's REST API (read-only). It reads designs; it never edits them.
- Tailwind suggestions use **arbitrary values** (`p-[16px]`); after tokens exist, snap them to scale (`p-4`). The guide tells the model to do this.
- `colorPrimary` in the antd theme is a best-effort guess (most vivid non-neutral color) — sanity-check it.
- For huge files, pass `depth` to `get_figma_design`/`extract_design_tokens` to keep responses small, or target a specific frame with `?node-id=` in the URL.
- Alternative: Figma's official **Dev Mode MCP** exposes design context too; this server differs by simplifying output and encoding the antd/AG Grid/Tailwind conventions specifically.

## Dev
```bash
npm run dev   # run from source with tsx
npm run build # compile to dist/
```