Code-Connected Figma: Keeping Design and shadcn in Sync

Figma Code Connect lets you attach a snippet of real source code to any Figma component, so when a developer opens Dev Mode and inspects that component, they see the actual shadcn/ui JSX and props your codebase uses instead of Figma's auto-generated best guess. Setting it up means installing the Code Connect CLI, writing a small `.figma.tsx` config file per component that maps Figma variants to component props, and publishing that mapping to your Figma file. Once it is in place, design and code drift apart far less often, because the "source of truth" a developer copies from is your own component, not a reverse-engineered approximation of it.

This guide is a practical, no-fluff walkthrough of that setup: what Code Connect actually does, how to wire it to a shadcn/ui component library, how to keep Figma variants and component variants honest with each other over time, and where this fits if you are building a design-to-code pipeline that also involves design tokens, Tailwind, or AI codegen tools. It assumes you already have a Figma file with reasonably well-structured components and a React codebase using shadcn/ui (or a similar headless-plus-Tailwind component approach).

What Code Connect Actually Solves

Figma's Dev Mode has always been able to show CSS-ish inspection output — spacing values, colors, font sizes — read directly off the layer. What it could never do on its own is show you idiomatic component code, because Figma has no idea that the button on your canvas corresponds to a `<Button variant="outline" size="sm">` in your actual repository. Without Code Connect, a developer inspecting a button either falls back to raw CSS (useless once you have a component library) or to Figma's auto-generated code suggestion, which infers structure from the layer tree and is very often wrong for anything non-trivial: it does not know your prop names, your variant enum values, or which visual states map to which boolean flags.

Code Connect closes that gap by letting you explicitly declare the mapping. You tell Figma: "this component, in this variant state, corresponds to this exact code, with these props filled in from these Figma properties." The result is that Dev Mode's code panel stops being a suggestion and starts being documentation — copy-pasteable, accurate, and versioned alongside your actual source.

This matters more as teams lean on AI coding assistants to turn designs into pull requests. An assistant (or a human) that is handed accurate, Code-Connected snippets can generate correct component usage on the first pass. An assistant handed Figma's raw layer-tree guess is often generating code that looks plausible but does not compile against your actual component API — variant names differ, required props are missing, and the fix costs more time than writing it by hand would have.

Prerequisites Before You Start

• A Figma file with components (not just static frames) — Code Connect attaches to component nodes and their variant properties, so main components with a variant matrix (e.g. Variant, Size, State) work far better than one-off duplicated frames.
• A shadcn/ui-based component library in your repo, ideally with each component's variants driven by class-variance-authority (CVA) — this makes the Figma-variant-to-prop mapping close to 1:1.
• Node.js and access to run the Figma Code Connect CLI (`npx figma connect` or `@figma/code-connect` as a dev dependency).
• A Figma personal access token with Code Connect write scope, and either a Dev Mode-enabled seat or an Organization/Enterprise plan — Code Connect publishing requires Dev Mode access on the file.
• Editor discipline: whoever owns the Figma library and whoever owns the component code need to agree on naming conventions before you start, or the mapping files will need constant rework.

Step 1: Install and Initialize the CLI

Add the Code Connect package to your frontend project (the one that actually contains your shadcn/ui components) rather than to a separate design-tooling repo — the config files need to sit next to the real components so imports resolve correctly:

• Install with your package manager: `pnpm add -D @figma/code-connect`.
• Run `npx figma connect --version` to confirm the CLI resolves.
• Create a `figma.config.json` at the project root (or reuse an existing one) declaring your React parser and the source directory Code Connect should scan, e.g. `codeConnect.include` pointing at `components/ui/**`.
• Set a `FIGMA_ACCESS_TOKEN` environment variable locally (and as a CI secret later) rather than hardcoding it — publishing requires this token on every push.

Step 2: Get the Figma Node ID for Each Component

Every Code Connect file needs to know which Figma node it documents. Open the component in Figma, right-click the main component (not an instance), and choose "Copy link to selection." The resulting URL contains a `node-id` query parameter — that is what goes into your config file's `figma.connect(...)` call. Do this for every component variant set you plan to connect: Button, Input, Select, Card, Dialog, and so on. It is tedious the first time through a library and fast after that, since most teams only maintain a Code Connect file per top-level component, not per variant.

Step 3: Write the Mapping File

A Code Connect config file for a CVA-driven shadcn/ui Button looks roughly like this in prose: import `figma` from the Code Connect package, import your real `Button` component, then call `figma.connect(Button, "<node-id-url>", { ... })`. Inside that call, a `props` object maps each Figma variant property to a code value using helpers like `figma.enum("Variant", { Primary: "default", Secondary: "secondary", Ghost: "ghost" })` for enum-style variants, `figma.boolean("Disabled")` for boolean toggles, and `figma.string("Label")` for text content bound to a layer. The `example` function then returns JSX using those mapped props, exactly as a developer would write it by hand.

The discipline that pays off here is naming your Figma variant properties identically to (or as an obvious 1:1 transform of) your CVA variant keys. If your component code has a `variant` prop with values `default | secondary | destructive | outline | ghost | link`, name the Figma property `Variant` with matching option names, not a looser label like "Style" with values "Blue" or "Gray." The mapping function can absorb small renames, but it cannot absorb a taxonomy that has drifted — if Figma has four button styles and code has six variants, someone has to reconcile that gap before Code Connect can express it cleanly, and that reconciliation is genuinely valuable design-system work, not busywork.

Step 4: Publish and Verify in Dev Mode

1. Run `npx figma connect publish` from the project root. The CLI parses your config files, validates that referenced components and props exist, and uploads the mapping to Figma.
2. Open the connected file in Figma, switch to Dev Mode, and select an instance of the component.
3. Confirm the code panel now shows your real JSX with the correct props filled in for that instance's current variant selection.
4. Toggle a variant (swap Primary to Ghost, toggle Disabled on) and confirm the generated snippet updates correctly — this is the fastest way to catch a mismapped enum before a developer does.
5. Run `figma connect publish --dry-run` (or the equivalent unpublish/reconnect cycle) whenever you rename a component or prop, so stale mappings do not linger and mislead the next person to open Dev Mode.

Wiring This Into a Token Pipeline

Code Connect documents component structure and props — it does not by itself keep colors, spacing, or typography values in sync. That is a separate, complementary job usually handled by design tokens: values defined once (often as Figma Variables or a tool like Style Dictionary) and exported into both your Tailwind config and your Figma library. If your shadcn/ui theme is driven by CSS custom properties mapped to Tailwind's `@theme` tokens, and your Figma Variables mirror those same names, then Code Connect's job gets simpler: the mapping file only has to express structure and variant logic, because the actual color and spacing values are already shared truth rather than something a developer has to eyeball off a design and hand-copy into a hex code.

Teams that skip token alignment and only do Code Connect often find the win is smaller than expected — the JSX is right, but the developer still has to guess at an exact spacing or color value because nothing enforces that the Figma Variable and the Tailwind token actually match. If you are building this pipeline from scratch, sequence it as tokens first, Code Connect second: get Figma Variables and your Tailwind theme provably in sync before you invest heavily in mapping component variants, since a token mismatch will silently undercut the accuracy of every Code Connect snippet downstream.

Where This Fits With AI Design-to-Code Tools

Code Connect is also the highest-leverage thing you can do to make AI-assisted design-to-code work reliably. Tools that read a Figma frame and propose a component tree — whether through Figma's own AI features, a Model Context Protocol (MCP) server that exposes Figma data to an agent, or a custom pipeline — perform dramatically better when they can resolve a component reference to a real, Code-Connected mapping instead of inferring structure from raw layer names and auto-layout properties. A well-maintained Code Connect library effectively gives any downstream tool, human or AI, a lookup table instead of a guessing game.

This is one reason the design-to-code conversation has shifted from "can an AI turn a screenshot into HTML" (it always somewhat could) to "can an AI produce code that actually matches this team's component library, naming conventions, and variant system" — which is a much harder and more valuable problem, and one that structured mappings like Code Connect are specifically built to help solve. If you are evaluating headless commerce or Next.js storefront work and expect AI tooling to touch the design-to-code boundary, getting Code Connect (or an equivalent structured mapping) in place early pays compounding dividends as that tooling improves.

Keeping the Mapping From Rotting

The single biggest failure mode for Code Connect adoption is not the initial setup — it is drift. A developer renames a prop, a designer adds a new Figma variant, and nobody updates the mapping file, so Dev Mode quietly starts showing stale or subtly wrong code. A few habits keep this from happening:

• Treat `*.figma.tsx` config files as part of the component's public API — review changes to them in the same pull request as any prop rename or new variant, not as an afterthought weeks later.
• Add a CI step that runs Code Connect's parse/validate step (without publishing) on every PR touching `components/ui`, so a broken mapping fails the build instead of silently going stale in Figma.
• Publish from CI on merge to your main branch, using a service-account Figma token, rather than relying on individual developers to remember to run `figma connect publish` locally.
• Assign ownership — a design-system owner or a rotating "component librarian" who is responsible for reconciling Figma variant names with code variant names whenever the two start to diverge.
• Periodically spot-check Dev Mode on a handful of components against the actual rendered app, especially after a larger refactor of your CVA variant definitions.

A Note on Where Polo Themes Fits Today

Polo Themes currently ships design assets as Figma UI kits and Shopify OS 2.0 themes — our Figma kits are built with the same component-and-variant discipline this guide describes, which is precisely what makes a library Code-Connect-ready in the first place: named variant properties, consistent option sets, and structure that maps cleanly onto real code. We do not currently sell a Next.js starter, a component registry, or MCP-based agent templates, though headless and AI-native tooling is a direction we are actively exploring. If you are assembling a design-to-code pipeline around shadcn/ui today, a well-structured Figma kit is the piece that makes every step after it — tokens, Code Connect, AI codegen — meaningfully easier.

Frequently Asked Questions

Does Code Connect require a paid Figma plan?

Yes — publishing and viewing Code Connect mappings relies on Dev Mode, which requires an Organization or Enterprise plan (or a Dev Mode-enabled seat, depending on Figma's current packaging). Confirm your plan's Dev Mode access before investing time in writing mapping files.

Does Code Connect work with frameworks other than React?

Figma's Code Connect supports multiple platforms, including React, SwiftUI, and Jetpack Compose parsers, with community and first-party support expanding over time. This guide focuses on the React plus shadcn/ui path since that is the most common stack for headless commerce and Next.js storefronts.

Is Code Connect the same thing as design tokens?

No. Design tokens (colors, spacing, typography values shared between Figma Variables and your Tailwind theme) keep raw values in sync. Code Connect keeps component structure and prop usage in sync. They are complementary — most mature pipelines use both, with tokens as the foundation.

What happens if a Figma variant does not exist in code, or vice versa?

Code Connect cannot map what does not exist on both sides. Treat a mismatch as a signal to reconcile the design system itself — either add the missing code variant, remove the orphaned Figma option, or explicitly decide one side is intentionally broader than the other — before writing the mapping file.

Can Code Connect help onboard new developers faster?

Yes, and this is often the most immediately visible benefit. A new developer who does not yet know a component library's prop names can inspect any component in Dev Mode and get accurate, copy-pasteable code, cutting down significantly on Slack questions and trial-and-error prop guessing during the first few weeks on a project.