Book a call

WritingAI-ready design systemsPart 8 of 20 in Making your design system AI-ready

Figma to code with AI: preparing your library for the Figma MCP server and Code Connect

Design-to-code agents convert what the Figma file says. Detached instances and raw values become hard-coded divs; variables and Code Connect become your real components and tokens. A six-step setup, with a before-and-after from the same frame.

Diagram: a Figma frame's variables and Code Connect mappings pass through the Figma MCP server to a coding agent, which writes code with real components and tokens.
On this pageThe problem: the agent can only see what the file says
  1. The problem: the agent can only see what the file says
  2. How the Figma MCP server works
  3. Step 1: connect the server
  4. Step 2: make variables match your tokens
  5. Step 3: make component properties mirror code props
  6. Step 4: clean product files where it matters
  7. Step 5: connect components with Code Connect
  8. Step 6: generate a design-system rules file
  9. Before and after: the payslip card
  10. How to prompt from a Figma frame
  11. How to check it works
  12. Common mistakes
  13. The short version
  14. Frequently asked questions
  15. Further reading

The short answer

Figma's MCP server lets coding agents read a Figma frame's structure, variables, component names and screenshots, so they can turn designs into code. What they produce depends on how the file is built. To get code that uses your real design system: use variables for every colour, spacing and radius, named to match your code tokens and with code syntax set; build components with properties that mirror code props (Variant = primary, secondary, danger); write component descriptions; keep instances attached and layouts in auto layout; and connect Figma components to code components with Code Connect, so the agent sees your real import and props instead of a description of rectangles. Then generate a design system rules file and prompt with a link to a specific frame.

  • Without Code Connect, the agent sees what a button looks like. With it, it sees <Button variant="danger">.
  • If a designer used a raw hex instead of a variable, the variable tools have nothing to return.
  • Part 8 of 20 in the series on AI-ready design systems.

The problem: the agent can only see what the file says

So far this series has prepared the code side: tokens (part 3), component metadata (part 4), docs (part 5), rules files (part 6) and an MCP server (part 7). But many UI tasks start in Figma: "build this screen". When an agent reads a Figma frame, it gets layers, properties and values. If the file is messy, the code will be too.

An illustration: the payslip screen

The frame

A designer's payslip screen. Half the buttons are detached instances. The card is a frame called "Frame 4182" with a hard-coded #F6F8FB fill. Spacing is a mix of 14, 16 and 18px. The table is grouped rectangles.

What the agent wrote

A new PayslipCard with inline styles, three hard-coded colours, a hand-built table with <div>s, and buttons styled to look like Harbor's but not actually Harbor's.

Why

The agent faithfully converted what it saw. Detached instances and raw values carry no link to the system, so there was nothing to tell it "this is Harbor's Button" or "this is bg.surface.subtle".

How the Figma MCP server works

Figma offers an official MCP server in two forms: a remote server hosted by Figma at https://mcp.figma.com/mcp, which Figma recommends for most people, and a desktop server that runs through the Figma desktop app for specific organisational needs. With the remote server you give the agent a link to a frame or layer; the desktop server can also work from your current selection.

Figma file
FrameLayers, auto layout, instances
VariablesNames, values, modes, code syntax
Library componentsNames, properties, descriptions
Code ConnectFigma component → code component
Coding agent
CombinesFigma's context + your rules file + your Harbor MCP tools
Code
Real importsimport { Button } from "@kestrel/harbor"
Real tokensvar(--color-bg-surface-subtle)
Figma-to-code-to-agent architecture. Figma's server explains the design; your server and rules explain the code. The agent needs both.

At the time of writing, the server's tools include, among others:

ToolWhat it returnsDepends on in your file
get_design_contextThe main design-to-code context for a layer or selection; defaults to React and Tailwind, adaptable by promptAuto layout, instance names, variables, Code Connect
get_variable_defsThe variables and styles used in a selection (colours, spacing, type)Values bound to variables, not typed in
get_metadataA lightweight outline of the layer tree (names, types, positions)Meaningful layer names
get_screenshotAn image of the selection, so the layout stays accurateNothing; it's always useful
get_code_connect_mapWhich Figma components map to which code componentsCode Connect set up for the library
create_design_system_rulesA rules file to guide agents turning designs into code for your systemA well-structured library
Documented Figma adds and renames tools regularly, and some features depend on your plan and seat type. Check Figma's MCP documentation, or the tool list your client shows, for the current set.
New words

Variable: Figma's name for a stored value (colour, number, string, boolean) that layers can be bound to, with modes such as light and dark: Figma's equivalent of a design token. Code syntax: a setting on a variable that records its name in code, such as var(--color-bg-surface). Code Connect: Figma's way of linking a design component to the real code component and showing a code snippet for it. Detached instance: a copy of a component that's been disconnected from the library, so it no longer updates and no longer identifies as that component.

Step 1: connect the server

Setup takes a few minutes. For Claude Code with the remote server:

claude mcp add --transport http figma https://mcp.figma.com/mcp
# then run /mcp inside Claude Code and sign in to Figma when prompted

Other clients (Cursor, VS Code, Codex) add the same URL in their MCP settings. Figma's docs list the exact steps for each. Commit nothing secret: the sign-in happens per person through OAuth.

Step 2: make variables match your tokens

This is the most important step. When a frame's values are bound to variables whose names match your code tokens, the agent can write var(--color-feedback-info-bg) directly. When they're raw values, it can only copy the hex.

Code token (DTCG)Figma variableCode syntax (Web)
color.bg.surfacecolor/bg/surfacevar(--color-bg-surface)
color.feedback.info.bgcolor/feedback/info/bgvar(--color-feedback-info-bg)
space.inset.mdspace/inset/mdvar(--space-inset-md)
radius.controlradius/controlvar(--radius-control)
One name, three spellings. Slashes in Figma create groups; dots in tokens; hyphens in CSS. The structure is identical, so a tool can convert between them.
  1. Generate Figma variables from the token source

    Keep the DTCG files as the source (part 3) and sync them into Figma with a plugin such as Tokens Studio, or with Figma's Variables REST API (available on Enterprise plans). Hand-maintaining both sides guarantees drift.

  2. Hide primitives from publishing

    Put primitive colours in a separate collection and hide them from publishing, so designers bind layers to semantic variables only, just as product code uses semantic tokens only.

  3. Set code syntax on every semantic variable

    In the variable's settings, add the Web code syntax (var(--color-bg-surface)). Dev Mode then shows the CSS name, and tools working from the file can use it.

  4. Add descriptions

    Variables have a description field. Copy each token's $description into it as part of the sync, so designers see the same "Use for… Not for…" guidance that agents do.

Step 3: make component properties mirror code props

A Figma component's properties should be the same decisions as the code component's props, with the same names and values wherever possible. Then a mapping (step 5) is mechanical, and anyone, person or agent, can move between the two.

BEFORE

Figma organised by appearance

Button
  Type: Filled / Outline / Text / Red
  State: Default / Hover / Disabled
  Has icon: Yes / No
  Size: 32 / 40

"Red" is a colour, not a job; "Outline" doesn't exist in code; sizes are pixel values.

AFTER

Figma organised like the code

Button
  Variant: Primary / Secondary / Ghost / Danger
  Size: Small / Medium
  Disabled: true / false     (boolean)
  Loading: true / false      (boolean)
  Label: "Save changes"      (text)
  Icon start: ⟨instance swap⟩

The same four variants as the variant prop. Hover is shown in the playground, not as a variant to pick.

  • Use text properties for labels, so the agent receives "Remove from payroll" as data, not as a layer named "Label".
  • Use boolean properties for on/off props, and instance-swap properties for slots like icons.
  • Fill in the component description with the same purpose sentence as the code metadata: "Triggers an action on the current page. For navigation use Link."
  • Link the description to the docs page using the component's documentation link field.

More on library organisation in organising a Figma library.

Step 4: clean product files where it matters

The library can be perfect and a product file can still confuse an agent. You don't need to clean every file. Focus on frames that will be handed to agents, and ask designers to follow four habits:

HabitWhy it matters to the agent
Use library instances; don't detachAn attached instance says "this is Harbor's Button, variant Danger". A detached one is anonymous rectangles.
Use auto layoutAuto layout converts naturally into flex and grid layouts with gaps from spacing variables. Absolute positioning turns into brittle coordinates.
Name meaningful frames"Payslip summary" and "Deductions table" become component and section names. "Frame 4182" becomes Frame4182.
Bind every value to a variableNo variable, no token. Library analytics and linting plugins can find raw values.
Tip

Make a "ready for build" checklist part of design handoff: instances attached, auto layout, variables bound, frames named. It's the same checklist good engineering handoff always needed. Agents just make the cost of skipping it visible immediately.

Step 5: connect components with Code Connect

Code Connect links each Figma component to its code component, including how Figma properties map to props. Once it's set up, the Figma MCP server can give the agent your actual component and props instead of a description of what the design looks like. It's available on Figma's Organization and Enterprise plans.

There are two ways to set it up: Code Connect UI, mapping components inside Figma without code, and the Code Connect CLI, which keeps mappings as files in your repo. The CLI version is more precise and is reviewed like code, so it's what we recommend for design system teams.

// packages/harbor/src/Button/Button.figma.tsx
import figma from "@figma/code-connect";
import { Button } from "./Button";

figma.connect(Button, "https://www.figma.com/design/AbC123/Harbor?node-id=12-345", {
  props: {
    label: figma.string("Label"),
    variant: figma.enum("Variant", {
      Primary: "primary",
      Secondary: "secondary",
      Ghost: "ghost",
      Danger: "danger",
    }),
    size: figma.enum("Size", { Small: "sm", Medium: "md" }),
    disabled: figma.boolean("Disabled"),
    loading: figma.boolean("Loading"),
  },
  example: ({ label, variant, size, disabled, loading }) => (
    <Button variant={variant} size={size} disabled={disabled} loading={loading}>
      {label}
    </Button>
  ),
});
// figma.config.json at the package root
{ "codeConnect": { "include": ["src/**/*.figma.tsx"] } }
npm install --save-dev @figma/code-connect
npx figma connect publish     # needs a Figma access token with Code Connect write access

Publish from CI on each release, so the mappings always match the version in the library. Start with your 10 most-used components; they cover most of any screen.

Step 6: generate a design-system rules file

Figma's server includes a tool, create_design_system_rules, that drafts a rules file describing how designs in your files should become code in your project. Run it once, then edit it and merge it into the AGENTS.md from part 6, so there's one set of rules rather than two that disagree.

<!-- AGENTS.md: added section -->
## Implementing Figma designs
- Use the Figma MCP server for design context and a screenshot of the linked frame.
- When Code Connect returns a component, use exactly that component and its props.
- When it doesn't, call harbor.search_components before writing anything new.
- Map Figma variables to CSS variables by name (color/bg/surface → var(--color-bg-surface)).
- Never copy hex values or pixel sizes from Figma output. If a value has no variable,
  call harbor.search_tokens and mention the unbound value in your reply.
- Don't add Tailwind defaults or new components to match a design.

Before and after: the payslip card

FROM A MESSY FRAME
export function Frame4182() {
  return (
    <div style={{ background: "#F6F8FB",
      padding: 18, borderRadius: 10 }}>
      <div style={{ fontSize: 15,
        color: "#5A6270" }}>Net pay</div>
      <div style={{ fontSize: 28 }}>
        ₹84,250</div>
      <button className="bg-blue-600
        text-white rounded-lg px-4">
        Download payslip</button>
    </div>
  );
}
FROM A READY FRAME
import { StatCard, Button } from
  "@kestrel/harbor";
import { formatMoney } from
  "@kestrel/harbor/format";

export function PayslipSummary({ payslip }) {
  return (
    <StatCard
      title="Net pay"
      stats={[{ label: "This month",
        value: formatMoney(payslip.net,
          "INR") }]}
      action={<Button variant="secondary">
        Download payslip</Button>}
    />
  );
}

Same design, same agent. The second result came from attached instances with Code Connect, bound variables, a named frame, and the rules above.

How to prompt from a Figma frame

Even with a clean file, the prompt matters. Link to a specific frame, not a whole page, and say what to reuse.

A good promptImplement this frame as PayslipSummary in src/features/payslips: https://www.figma.com/design/AbC123/Payroll?node-id=210-88. Use Code Connect components where available, Harbor's tokens for every value, and existing helpers for money and dates. Don't create new components; if something doesn't map, list it.
Tool call · figma.get_design_context{ "nodeId": "210:88", … }
Tool call · figma.get_screenshot{ "nodeId": "210:88" }
Result (abridged)StatCard (Code Connect: @kestrel/harbor) · Button variant="secondary" (Code Connect) · fill: color/bg/surface/subtle …
AgentBuilt PayslipSummary with StatCard and Button from Harbor. All values use tokens. One unmapped item: the "Tax regime" badge uses a detached instance with a custom colour. I used Badge tone="neutral"; please confirm.
Illustration The final line is what you want: the agent flags what it couldn't map instead of inventing a colour.

How to check it works

  1. Pick five representative frames

    A form, a table, a dashboard card, a dialog, an empty state, from real product files.

  2. Generate code for each and score it

    Count non-Harbor components, raw values and invented helpers, as in the part 2 audit. Note which came from library problems and which from product file problems.

  3. Check Code Connect coverage

    What share of instances in those frames have a mapping? Prioritise mapping the components that appear most.

  4. Watch detach rates

    Figma's library analytics show how often components are detached. High detach rates point to components that don't meet designers' needs, which is useful feedback for the system team as well as for agents.

Common mistakes

MISTAKE

Different names in Figma and code

"Info/Background" in Figma, feedback.info.bg in code. The agent can't connect them, and neither can a new hire.

MISTAKE

Visual states as variants

Hover and pressed as variants make the property list longer than the props. Keep variants for decisions people make.

MISTAKE

Linking whole pages

A link to a page with 40 frames floods the context. Link the frame you want built.

MISTAKE

Trusting generated code because it looks right

A pixel-perfect result can still be off-system or inaccessible. Lint, type checks and tests in part 9 apply to design-to-code output too.

The short version

  • The Figma MCP server gives agents a frame's structure, variables, screenshot and Code Connect mappings.
  • Variables named like your tokens, with code syntax set, turn into real CSS variables.
  • Component properties should mirror code props; Code Connect links them for the agent.
  • Attached instances, auto layout, named frames and bound values make product files usable.
  • Generate a rules file with Figma's tool, merge it into AGENTS.md, and prompt with a specific frame.

Next: Guardrails for AI-generated UI, the checks that catch whatever still slips through, and how to measure improvement.

Frequently asked questions

What is the Figma MCP server?

Figma's official Model Context Protocol server. It lets AI coding agents read design context from Figma files (layer structure, variables, component names, screenshots and Code Connect mappings) so they can implement designs in code. It's available as a remote server hosted by Figma and as a desktop server.

What is Figma Code Connect?

A Figma feature that links design components to the real code components, including how Figma properties map to props. Dev Mode and the Figma MCP server can then show your actual component code instead of generated approximations. It's available on Organization and Enterprise plans.

Why does Figma-to-code AI ignore my design system?

Usually because the file doesn't identify the system: detached instances, raw values instead of variables, components without Code Connect, and properties that don't match code props. The agent converts what it sees.

Should Figma variable names match design token names?

Yes. Use the same structure (color/bg/surface in Figma, color.bg.surface in tokens, --color-bg-surface in CSS), set code syntax on each variable, and generate variables from the token source so they can't drift.

Do I need to clean up every Figma file for AI?

No. Get the library right first, then apply a short "ready for build" checklist to frames that will be implemented: attached instances, auto layout, bound variables and meaningful frame names.

Further reading