figma-codegen

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

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.