---
name: connecting-figma-to-code
description: Maps Figma components to their real code counterparts so agents generate the right import and props from a design, using Code Connect where it exists and an explicit mapping table where it does not. Use when implementing a Figma design in code, when setting up or maintaining Figma Code Connect, when an agent generates markup that looks right but uses the wrong components, or when the user mentions design handoff, design-to-code, Figma MCP, or component mapping. Applies whenever a design file is the input to code generation.
license: CC0-1.0
---

# Connecting Figma to code

This is the weakest joint in the whole design-to-code chain. In a July 2026
census of twenty maintained open-source design systems, only two shipped
Figma Code Connect — Carbon with roughly 86 mapping files and Primer with 52.
Everyone else writes the mapping down in prose and hopes.

Prose mappings are why an agent produces a layout that looks correct and is
built from the wrong components.

## If you have Code Connect

Use it. It is the only mechanism that puts the mapping where the agent looks:
per component, it declares the props mapping, the variant mapping, and an
example. Keep the files next to the components and publish them from CI, not
by hand.

Note the migration: framework-specific parsers stopped receiving updates in
August 2026, and template files are the maintained path now.

## If you do not

Write the mapping table and keep it beside the components, not in a wiki.

| Figma component | Code component | Import | Variant mapping |
|---|---|---|---|
| `{{Button/Primary}}` | `{{Button}}` | `{{import { Button } from '@scope/ds'}}` | `{{Type=Primary maps to variant="primary"}}` |
| `{{Input/Default}}` | `{{TextField}}` | `{{import { TextField } from '@scope/ds'}}` | `{{Label is required in code}}` |

Three columns are load-bearing: the code name, the verbatim import, and the
variant mapping. Figma layer names and code export names diverge constantly,
and the agent has no way to know that `Input/Default` is `TextField`.

## Procedure when implementing a design

1. **Read the frame's structure**, not its pixels. Which components, in which
   nesting, with which variants.
2. **Resolve each one through the mapping.** If a Figma layer has no mapping
   entry, stop and say so — do not guess from the layer name.
3. **Map variants explicitly.** A Figma variant named `Large` may be
   `size="lg"`, `size="large"`, or a different prop entirely.
4. **Take values from variables, not from the rendered pixels.** A measured
   16px gap should become the spacing token that resolves to 16px, not `16px`.
5. **Reconcile what is missing.** Designs routinely contain states the code
   component does not implement, and components the library does not have.
   List them as gaps rather than inventing implementations.

## Do not

- Recreate a component in code because the Figma layer is detached.
- Trust auto-layout numbers over the spacing scale.
- Convert a text style to a font-size literal when a type token exists.
- Assume unmapped means new. Search the codebase first.

## Verification

Every component in the output traces to a mapping row or an explicit gap
note. No layer name appears in the code. No measured pixel value appears
where a token exists.