Figma to code: how to keep design and development in sync at scale
The design is done. The file is handed off. The developer opens it, inspects the components, and starts building. Two weeks later, the product looks close to the design – but not quite. The spacing is slightly off. The button colour doesn’t match. A component state that was designed never made it into production. Nobody made a deliberate decision to diverge. The gap just appeared, the way it always does: gradually, then everywhere.
This is the design-to-code problem. And it’s not a tooling problem, even though most teams try to solve it with tools. It’s a synchronisation problem – across four distinct layers that can each drift independently: tokens, components, tooling, and governance. Fix one without the others and the gap reopens within a sprint.
This article breaks down each layer, what breaks when it’s missing, and what teams who’ve solved it actually do.
Table of contents
Why design and code drift apart – the four failure points
Most teams experience design-to-code drift as a single frustrating problem. In practice, it’s four separate failure modes that compound each other.
Token drift
Colours, spacing, and typography values are hardcoded in CSS rather than referenced from a shared variable system. When a designer updates a token in their design tool, nothing in the codebase changes automatically. The update has to be manually propagated – and it rarely is, consistently.
Component naming divergence
A designer names a component “Card/Featured” in the design file. A developer builds FeaturedCard.tsx in the codebase. These are the same component, but without an explicit mapping between them, neither side knows that. Every component change requires a human to translate between two naming systems.
State gaps
A designer specifies the default and hover states of a component. The developer implements those two states and ships. Three months later, a disabled state is designed and added to the design file. It never makes it into the codebase because there’s no process that flags the gap.
Governance failure
Nobody is explicitly responsible for keeping both environments in sync simultaneously. Designers update the design tool. Developers update the codebase. The two environments drift in parallel, and nobody notices until a design review reveals that production and design have been telling different stories for weeks.
The principle: Design-to-code sync isn’t a handoff problem. It’s a maintenance problem. Handoff is a moment. Sync is a practice.
The token layer – why it’s the foundation of everything else
Design tokens are the only layer of a design system that can be technically synchronised automatically. Every other layer – components, documentation, governance – requires human judgment at some point. Tokens, once structured correctly, can flow from design tool to codebase without manual intervention.
The mechanism is straightforward: design tokens are defined as named variables in your design tool, exported as a JSON file, transformed by a tool like Style Dictionary into CSS custom properties, Sass variables, or platform-specific formats, and then referenced in component code. When a token changes in the design tool, the change propagates through the pipeline automatically – every component that references the token updates without anyone touching component code.
What happens without this pipeline is instructive. Figma’s own design systems team described how, after migrating their colour system from a spreadsheet to Figma Variables, they found over 280 differences – designers had been working on stale information. Figma The spreadsheet had been the source of truth in name only. The actual source of truth was fragmented across wherever the last manual update had landed.
The token pipeline solves this by making your design tool variables the genuine source of truth – not aspirationally, but technically. When the pipeline is working, a designer who updates a colour token triggers a process that ends with a pull request in the codebase. Developers review and merge. The change is traceable, reversible, and doesn’t require anyone to remember to do it.
Pro tip: The W3C Design Tokens specification reached version 1.0 in October 2025, establishing the first official standardised format for design tokens. Figma, Sketch, and Penpot are all implementing the same spec, which means token files can now move between tools without custom transformation scripts.
The component layer – naming conventions that both sides can use
The token layer handles values. The component layer handles structure – and structure is where most design-to-code sync breaks down in practice, because it requires agreement between two disciplines that use different languages.
A designer thinks in visual hierarchies and states. A developer thinks in component APIs and props. Without an explicit convention that maps between the two, every component handoff is a translation exercise – and translations introduce errors.
Three principles make component naming work across both environments:
Use a consistent hierarchy
A naming structure like Category/Component/Variant in your design tool maps cleanly to a file structure like components/category/Component.tsx in code. When the hierarchy matches, designers and developers can find the same component without asking each other. GitHub’s Primer design system separates libraries by function – Primer Primitives for colour, type, and spacing; Primer Web for UI components – with a clear architectural principle: the source of truth is the code, documented on Primer.style. The design tool is secondary to the code, not the other way around.
Make states explicit, not implicit
Every component state that exists in the design tool – default, hover, focus, disabled, loading, error – should have a corresponding variant that is named identically to the prop or class that controls it in code. A state that exists in one environment but not the other is a gap waiting to cause a bug.
Treat naming changes as breaking changes
When a designer renames a component in the design tool, or a developer renames a component in code, the mapping between the two environments breaks silently. Both sides need to treat renaming as a cross-environment operation that requires coordination – the same way a database schema change requires a migration.
The tooling layer – what actually keeps design and code connected
No tool solves the sync problem on its own. But the right combination of tools reduces the manual work to the point where governance becomes feasible. Here is what the current tooling landscape looks like and what each tool actually does.
Token management in your design tool. Token Studio manages design tokens inside Figma. Sketch handles tokens through its native variables system. Penpot supports design tokens natively as part of its open-source infrastructure. All three can export tokens as JSON for use in a token pipeline. The goal is the same regardless of tool: a structured, exportable definition of every visual decision in your product.
Style Dictionary transforms JSON token files into whatever format the codebase uses – CSS custom properties, Sass variables, JavaScript constants, or platform-specific formats for iOS and Android. It sits in the middle of the token pipeline, between the design tool and the component code.
Dev inspection tooling. Figma’s Dev Mode is a developer-focused interface for inspecting designs. It surfaces component properties, token values, spacing measurements, and links to external resources like Storybook and GitHub. It also shows which frames are marked as ready for development. Teams using Sketch or Penpot have equivalent inspection workflows through their own developer handoff features.
Figma Code Connect maps Figma components to actual code components in a repository. When implemented, developers inspecting a component in Dev Mode see real code snippets from the production codebase – not auto-generated CSS. Figma described the problem Code Connect was built to solve directly: “We built a design system, but it’s not being used to its full potential” – developers use parts of the design system but often misuse components in ways that don’t align with the system’s intended guidelines. Figma
Storybook documents and previews coded components in isolation. It’s the code-side equivalent of a design tool component library – a place where developers can see every component, every variant, and every state without running the full application. Linking design tool components to their Storybook stories closes the loop between design and code documentation.
Watch out: These tools handle the mechanics of synchronisation. None of them handle the question of who is responsible for keeping both environments updated when something changes. That’s governance – and it’s the layer most teams skip.
The governance layer – the one most teams skip
Governance is the hardest layer to build because there’s no tool that implements it for you. It’s a set of decisions about ownership, process, and accountability – and the absence of those decisions is what causes the other three layers to drift even when the tooling is in place.
Three governance decisions determine whether design-to-code sync holds at scale:
Who owns the token pipeline. When a designer updates a colour in the design tool, who is responsible for ensuring that change reaches the codebase? In most teams, the answer is “whoever notices” – which means it happens inconsistently. A working governance model assigns explicit ownership: either a designated design systems engineer runs the sync on a defined cadence, or the process is automated to the point where human intervention is only needed at the review stage.
Figma’s own design systems team built a GitHub Action that automatically syncs Figma Variables to CSS tokens. Designers update variables in Figma, the Action creates a pull request, and developers review and merge. Figma This model keeps both sides in their native environment – designers work in the design tool, developers work in GitHub – while eliminating the manual step that most sync processes break down at.
Who approves new components. Every team eventually faces the question of whether a new pattern should be added to the design system or handled as a one-off. Without a defined process for making that decision, engineers build one-off components that never make it into the system, and designers add components to the design tool that never get coded. The governance model needs to answer: who reviews new component requests, what criteria determine whether something belongs in the system, and how quickly can that decision be made.
How changes are versioned. Design systems change. Components get deprecated. Token values get updated. Without versioning, teams can’t communicate change to the people who depend on the system, can’t roll back when a change breaks something, and can’t audit where a visual decision came from. Versioning design system changes – treating them like software releases, with changelogs and semantic versioning – is what separates a maintained system from one that drifts.
The principle: Governance isn’t a process for large teams. It’s the answer to one question: who is the last person who knows what’s in both environments simultaneously? If the answer is “nobody”, the system will drift.
How to audit your current sync – a practical checklist
Before investing in new tooling or process, it’s worth understanding where your current sync is actually breaking. These five questions surface the most common failure points.
1. Can a developer find the CSS variable for any colour in your product in under a minute? If the answer is no – because colours are hardcoded, because the variable names don’t match between design tool and code, or because nobody has documented the mapping – the token layer is broken.
2. Do component names in the design tool match component names in the codebase? Pick five components at random and compare what they’re called in the design file versus in the repository. If the names diverge, there’s no reliable mapping between design and code – and every handoff requires translation.
3. Are all component states in the design tool implemented in code? For each component, check whether every variant and state has a corresponding implementation. Unimplemented states are gaps in the sync that will surface as bugs when those states are needed.
4. When was the last time design tokens were updated in both the design tool and the codebase on the same day? If the answer is “never” or “I don’t know”, the token pipeline doesn’t exist or isn’t being used. The two environments are drifting independently.
5. Who would you ask if you needed to know whether the design tool and production are currently in sync? If there’s no clear answer – or if the answer is “I’d have to check both” – governance is absent. No single person or process owns the sync.
Sync is a practice, not a project
Teams that solve design-to-code sync don’t do it in a single sprint. They build a practice – a set of habits, tools, and responsibilities that make staying in sync the path of least resistance rather than an extra effort on top of regular delivery.
The token layer makes automatic sync possible. The component layer makes the system navigable across disciplines. The tooling layer removes the manual steps that break down under deadline pressure. The governance layer keeps it all honest when no one is looking.
None of these layers is optional. A token pipeline without governance drifts. A component library without naming conventions creates translation overhead. Tooling without tokens to sync has nothing to connect. The four layers work together – or they don’t work at all.
Share this article:
