# Figma → MIDL (design import)

Turn a Figma design into a real MIDL site. The structure becomes semantic `ui:*` frames and the design's tokens become a **generated theme** — so the import is a re-themeable MIDL page, not a pixel-dump. The look comes from the generated pack/theme, never from inline styling (MIDL strips literal styling by design).

There are two ways in; both share one deterministic core (`@wisepunk/core`'s `figma*` functions).

## Path A — BYO-agent skill (recommended today)

Use a coding agent (Claude Code) that has the **Figma MCP server** connected. The skill `figma-to-midl` drives it end to end: pull design context (`get_metadata`, `get_design_context`, `get_variable_defs`, `get_screenshot`), map to MIDL, then run the deterministic finalize → theme → fidelity loop and save.

- Install the Figma MCP: `claude mcp add --transport http figma https://mcp.figma.com/mcp`, then authenticate. Requires a Figma **Dev or Full seat** (View/Collab get ~6 calls/month).
- Install the skill: it lives at `skills/figma-to-midl/SKILL.md`.
- Then: *"Make this Figma frame into a MIDL site: <link>"*.

The deterministic transform is exposed as a CLI:

```bash
# raw Figma node JSON (e.g. from the REST API) → full deterministic baseline
pnpm import:figma -- /abs/figma-nodes.json --out /abs/out

# an LLM-authored doc + harvested tokens → finalize + theme + fidelity report
pnpm import:figma -- /abs/authored.json --midl --out /abs/out --visual-diff 0.85
```

It writes `midl.json`, `DESIGN.md`, `theme.css`, and `fidelity.json` (a 0–100 `score` plus contrast / type-scale / per-warning detail).

## Path B — Studio importer (coming)

Paste a Figma frame URL in Studio; the server calls the Figma **REST API** (`GET /v1/files/:key/nodes` + image render + Variables), runs the same core mapper plus an optional AI semantic-refine pass, previews the result with its fidelity report, and saves. (In progress — see the project's G3 milestone.)

## How the mapping works

| Figma | MIDL |
| --- | --- |
| auto-layout `VERTICAL` / `HORIZONTAL` | `ui:Stack` (`direction: column` / `row`) |
| auto-layout `GRID` | `ui:Grid` |
| top frame's bands | `ui:Section` |
| large/title `TEXT` | `ui:Heading` (`level` from the type scale) |
| body `TEXT` | `ui:Text` |
| small rounded filled box + 1 label | `ui:Button` |
| filled, rounded/shadowed box + children | `ui:Card` |
| image fill | `ui:Image` |
| named horizontal link row | `ui:Nav` / `ui:NavItem` |
| Figma Variables / styles | a generated `DESIGN.md` + contrast-safe theme |

Anything that can't be reproduced 1:1 (absolute positioning, vector art, overlaps) is mapped best-effort and **flagged in the fidelity report** — finish those by hand.

## Get the cleanest import

Figma's own "structure your file" guidance maps directly to import quality:
1. **Use components** for anything repeated (buttons, cards, nav items).
2. **Use Auto Layout** — it's the structural signal; absolute positioning degrades.
3. **Use semantic layer names** (`CardContainer`, `CTA_Button`, not `Frame 1268`).
4. **Use Figma Variables** for color/spacing/radius/type — they become the theme.
5. Keep frames reasonably sized; import large screens section-by-section.