Marcus Andrey Study
Ler em português Library

Design Systems · Step 5 · 7 min read

Code Connect and the design-code bridge

A Figma component and a code component are two things that are meant to be one. How to keep them together: shared names, a written mapping from Figma properties to code props, and Figma's Code Connect, which shows the real code in Dev Mode. What it needs, which plans have it, and where it stops.

Every design system has two copies of every component, and the system is the promise that they're the same. The Button in Figma and the Button in code were built by different people, in different tools, at different times. Left alone, they drift: a new variant here, a renamed prop there. The bridge between them isn't a tool. It's a mapping someone owns, and a tool that makes the mapping visible where developers look.

What you'll be able to do after reading:

  • Explain why design and code components drift, and where
  • Write a property mapping between a Figma component and a code component
  • Describe what Figma's Code Connect does, and what it needs
  • Decide what to connect first, and who keeps it up to date

1. Where the two copies drift

Drift starts small. A designer adds a Tertiary variant to Figma for one screen. A developer adds loading to the code Button and never tells design. Six months later the Figma Button has eleven variants, the code has seven props, and a handoff turns into a negotiation. Handoff to developers covers what to specify for one screen; here the question is how to stop the system itself from splitting in two.

Three things keep the copies together:

  1. The same names, where possible. Same component name, same property names, same option names.
  2. A written mapping for every place where the names can't be the same.
  3. A place where the developer sees the mapping at the moment they build, so they don't have to remember it.

2. The mapping, written down

Figma property → code prop
  • Variant variant: Primary · Secondary · Dangervariant 'primary' · 'secondary' · 'danger'
  • Density variant: Comfortable · Compactsize 'default' · 'compact'
  • Label text propertychildren string
  • Disabled boolean propertydisabled true · false
  • Show icon boolean propertyno prop of its own: in code the icon shows when one is passed (not in this file)
Button.figma.ts
// url=https://www.figma.com/design/FILE/Harbour-Components?node-id=12-34
// source=src/components/Button.tsx
// component=Button
import figma from 'figma'

const instance = figma.selectedInstance
const label = instance.getString('Label')
const disabled = instance.getBoolean('Disabled')
const variant = instance.getEnum('Variant', {
  Primary: 'primary',
  Secondary: 'secondary',
  Danger: 'danger',
})
const size = instance.getEnum('Density', {
  Comfortable: 'default',
  Compact: 'compact',
})

export default {
  example: figma.code`<Button variant="${variant}" size="${size}" disabled={${disabled}}>${label}</Button>`,
  imports: ['import { Button } from "@tidewater/harbour"'],
  id: 'harbour-button',
}
One Harbour Button, two vocabularies, joined by a Code Connect template file. The property map is the agreement; the file is that agreement written down. Each getter reads one Figma property and returns the code value, so when a designer picks Danger and Compact, Dev Mode shows variant="danger" size="compact". The names don't have to match. The mapping does.Template syntax from Figma, Writing template files.

Start with a table before any tool. For each Harbour component, list every Figma property, its type, and the code prop it becomes. The rules are simple:

  • Variant properties become enums. Variant: Primary → variant="primary". Same options, same order.
  • Text properties become strings or children. Label → the button's text.
  • Booleans become booleans, unless they only show or hide a layer, like an icon. Then the code may have no prop at all: it shows the icon when one is passed.
  • Instance swaps become nested components. The icon is its own component, mapped once.
  • Some properties exist only on one side. loading might be code-only; a Figma property for "show example text" is design-only. Write those down too, so nobody thinks they're missing.

A mapping with no gaps is the sign of a healthy component. A mapping full of "design only" and "code only" is a component that needs a conversation, and probably a change to one side.


3. What Code Connect does

Figma's Code Connect is "a bridge between your codebase and Figma's Dev Mode": it connects components in a repository to components in design files, so Dev Mode shows "the true-to-production code snippets from your design system instead of autogenerated code examples" (Figma developer docs, Code Connect). When a developer inspects a Harbour Button that a designer set to Danger and Compact, Dev Mode shows <Button variant="danger" size="compact">, with the import, not a pile of CSS.

There are two ways to set it up (Figma developer docs, Code Connect):

  • Code Connect UI, inside Figma, linking components to code with a GitHub integration. It can map one design component to implementations in several frameworks.
  • Code Connect CLI, in the repository. You write template files (Button.figma.ts), and publish them with npx figma connect publish (Figma, Writing template files). Figma now calls template files "the only actively maintained way of using Code Connect"; the older framework-specific parsers (React, SwiftUI, Compose, the Storybook integration) are marked legacy (Figma, Connecting React components).

Connections made in the CLI show up in the UI but "can only be edited in the CLI". The figure's template is written in that format: each getEnum, getBoolean and getString reads one Figma property, and figma.code builds the snippet.

Plan and seat: Code Connect is "available on a Dev or Full seat on the Professional, Organization, and Enterprise plans". Professional plans "can have one active library and one active framework"; Organization and Enterprise "can have multiple active frameworks" (Figma developer docs, Code Connect). Dev Mode itself is a paid feature too (see Handoff to developers).


4. The bridge also feeds AI tools

Figma says the connections "enhance the Figma MCP server's ability to guide AI agents with more precise implementation details" (Figma developer docs, Code Connect). In plain words: when a developer asks an AI coding tool to build a screen from a Figma frame, a connected Harbour Button comes back as Harbour's <Button>, not as a new button invented from the pixels. An unconnected component is exactly where the AI will guess. That's a new reason to connect your most-used components first.


5. What to connect first, and who owns it

  • Start with the ten most-used components. Library analytics (Organization and Enterprise, see Measuring adoption) or a look at the last few projects will tell you which.
  • The template file lives with the code, next to the component, and changes in the same pull request as the component. A Button change that doesn't update Button.figma.ts isn't done.
  • Review it from the design side. A designer checks that every Figma property is in the mapping, and that option names match.
  • Variables need the same care. Set code syntax on each variable (see Building a Figma library), so the colours in Dev Mode say var(--hb-color-action-primary) and not #1F5FAE.

6. Common mistakes

  • Expecting the tool to fix names that don't match. It only displays the mapping you wrote.
  • Connecting every component on day one, then maintaining none of them.
  • Template files that nobody updates when the component changes.
  • Starting new work on the legacy parsers instead of template files.
  • Forgetting the plan and seat: setting it up in a file whose viewers have no Dev Mode access.
  • Treating design-only and code-only properties as bugs without asking why they exist.

7. Vocabulary

Term Meaning
Drift The Figma and code versions of a component slowly becoming different
Property mapping The table that says which Figma property becomes which code prop
Code Connect Figma's way of showing real design-system code for a component in Dev Mode
Template file A .figma.ts file that defines the code snippet for one Figma component
Dev Mode Figma's workspace for developers to inspect designs
MCP server The interface through which AI coding tools read Figma files

8. Try it (no tools needed)

  1. Pick one component your team uses every day.
  2. Write its Figma properties in one column and, after asking a developer, its code props in another.
  3. Draw a line between the ones that match. Circle the ones with no partner.

Reflection questions: Which circled property would you remove, and which would you add to the other side? Who on your team would update the mapping when the component changes?


9. If you already practise

  • Add the mapping table to every component's doc page (see Component docs people use).
  • Make "template file updated" a line in the component's definition of done.
  • Check your most-used components in Dev Mode: does each show real code, or generated CSS?
  • Try an AI coding tool on a screen with connected and unconnected components, and compare what comes back.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Building a Figma library · Tokens from Figma to code · Anatomy and API of a component · Handoff to developers · Storybook and living documentation

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close