/figma-codegen

name: figma-codegen
description: Generate framework-aware code from a Figma design. Reads the project's stack profile and emits code matching the existing framework (React/Vue/Svelte/Next/etc.) and styling (Tailwind/CSS/CSS-in-JS), reusing existing components and design tokens instead of regenerating from scratch. Triggers whenever the user wants a Figma design turned into code — e.g. 'code this design', 'implement this frame', 'build this screen/component', 'turn this Figma into React/Vue', 'convert this design to code' — or whenever a Figma URL or the current Figma selection appears alongside a coding request. Works for full screens, single sections, or one component.

figma-codegen

Turn a Figma selection into code that looks like the rest of the project: reuse the components and tokens that already exist, only build what's genuinely missing. The grounded tools do the heavy lifting so you are not guessing from a screenshot. This file is the router; deep detail lives in [`references/`](./references) — load a reference when its step is in play.

When to use

• The user pastes a Figma URL/selection and asks for code ("code this", "build this component").
• The user wants to extend an existing component to match a Figma frame.

More than one Figma file open

Every tool result says so when it applies, so you do not have to check up front: with two or more files connected and none claimed, results carry a `MORE THAN ONE FIGMA FILE IS OPEN` block naming them. It matters because calls otherwise follow whichever file the user last touched, which changes when they switch tabs — so a task can read one file and write to another and report success.

When you see it, claim the file before doing anything else: `list_files` names every connected file, `use_file({ fileName })` claims one for this session (`use_file({ sessionId })` when two open files share a name — Figma allows that, and `x (Copy)` is how it happens). Every later call then reaches that file whatever is in front, including while its tab sits in the background. If the user has not said which file, ask — do not guess from the names.

Workflow

Run the grounded tools against the selection, then generate — **trust them over the rendered image.**

1. **`get_design_context`** (detail `full`, `dedupeComponents: true`) → the structural tree with tokens resolved to names (`Primary/500`, `spacing/4`), styles deduped into `globalVars`, and each instance's `mainComponent` / `componentProperties`. This is the layout + binding source of truth. Keep `dedupeComponents: true` and don't depth-limit a subtree you'll build from. → **How to read the tree, the per-node fidelity catalog (effects, per-side borders, stroke align, per-corner radius, blend, masks, gradients, image-fit, auto-layout/grid, aspect-ratio, scroll/sticky, stack & stroke-space), Dev Mode annotations as ground truth, and grounding a page too big for one call: [`references/grounding.md`](./references/grounding.md).**

2. **`component_map`** → every Figma component grouped to a local code component with a `status` (high / medium / low / unmapped), `candidate.filePath`, and `matchedProps`.

• `high` / `medium`: **reuse that component** (import from `candidate.filePath`), don't regenerate.

Never invent a component name `component_map` didn't report.

• `candidate.ambiguousWith` (a capped list of `{ name, filePath }`): the Figma name matched two or

more code components nearly equally and the join couldn't confidently pick — a **verify-me** pick, not a confident reuse (the analogue of `token_map`'s `ambiguousWith`). Check which of the winning `candidate` + these runner-ups is the right component for _this_ context before importing (a wrong reuse is a silent visual bug), then record the confirmed one in the map file so the next run is certain. Absent when the pick was unambiguous.

• Wire each entry's `instances[].props` (resolved variant / boolean / text values) onto the reused

component — one element per instance, with its own props.

• `candidate.unmatchedProps`: Figma axes the component has no prop for (a leading icon, a `required`

flag, an active state) → surface as component-extension TODOs, never fake them with ad-hoc markup.

• `unmapped`: build it new in the project's style. For a **repeated** unmapped component

(`instanceCount > 1`), build from its **first instance's** subtree; if that came back `deduped`/`truncated`, drill `get_design_context` on `instances[0].nodeId` once — don't rebuild a repeated component by eye.

• When you're emitting a component's **own definition** (its prop types, not just rendering it),

`get_component_api` on the component/instance returns the full property API — every VARIANT option and each BOOLEAN/TEXT/INSTANCE_SWAP prop with its default — so the prop space is grounded, not inferred from the instances you happened to see.

3. **`token_map`** → every Figma variable joined to a project token with `status` + `ref` + `matchedBy`. A document's shared paint styles (single solid color styles — the token mechanism of pre-variables files) join the same way, marked `source: 'style'`.

• mapped: reference `candidate.ref` (`bg-primary-500`, `var(--color-primary-500)`) — never the raw

hex/px `get_design_context` resolved. `matchedBy: ['name']` on a colour (value drifted): use it but flag the mismatch.

• `candidate.ambiguousWith` (several project tokens share that exact value and the name couldn't

split them): a capped, verify-me pick — choose the semantically right sibling for the context (or keep the value and flag the gap), never treat it as a confirmed reuse.

• On a document with few or no variables (most real-world files), `get_design_context`'s own

`projectTokens` map is the fallback: any raw color in the payload that exactly equals a project token's value is annotated there (`{ "#6266F0": { ref,