/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.

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, name, matchedBy: ["value"] } }`). Before hardcoding a hex, look it up and emit the `ref` when it fits the context semantically. `matchedBy: ["value"]` marks the entry as name-blind value-equality evidence — a hypothesis to verify, not a resolved binding: an entry with `candidates` lists same-value tokens to choose between by meaning, a semantically wrong token is **worse** than the raw value (keep the raw value and note the gap instead), and a bound Figma variable always outranks a raw-value match.

• `framework-builtin` (Tailwind built-in scale step, e.g. `spacing/4`, `line-height/7`,

`weight/Bold`): carries `builtin: { scale, step }` — compose the utility (`p-4`/`gap-4`, `leading-7`, `font-bold`), **not** an arbitrary `p-[16px]`. This is **not** a gap.

• `unmapped`: use the value but call out the gap (offer to add it to th