How to Structure Figma Variables and Tokens for Faster Dev Handoff

When design teams update a colour or spacing value in Figma, developers often have to search through dozens of code files to apply the same change manually. This gap between design files and production code causes visual inconsistencies, slower deployment cycles, and bloated QA checks.

Figma variables solve this by establishing design tokens—standardised values for colours, typography, spacing, and border radii that sync directly with your codebase. When structured correctly, design tokens create a single source of truth for both designers and developers.

Here is how to set up Figma variables and design tokens to streamline your development handoff.

Understanding the 3-Tier Token Hierarchy

The biggest mistake teams make when setting up Figma variables is linking UI elements directly to raw values like hex codes or pixel numbers. If your primary brand colour changes from #0055FF to #0A44E0, you shouldn't have to reassign that colour across every button, link, and banner in your design file.

A scalable token architecture uses three distinct layers:

[ Primitive Layer ]  -->  [ Semantic Layer ]  -->  [ Component Layer ]
 (e.g., Blue-500)          (e.g., Color-Brand)     (e.g., Button-Bg-Primary)

1. Primitive Tokens (Global Values)

Primitives represent your raw design choices. They hold hard values and do not carry functional context.

• color-blue-500: #0055FF
• space-16: 16px
• radius-md: 8px

Developers and designers rarely assign primitive tokens directly to UI elements. They sit at the base of your system as reference values.

2. Semantic Tokens (Contextual Alias)

Semantic tokens define what a value means in the context of your interface. They point to primitive tokens rather than fixed hex codes or pixel values.

• color-surface-primary: points to color-white
• color-text-primary: points to color-neutral-900
• color-brand-primary: points to color-blue-500
• space-padding-screen: points to space-16

If your brand updates its visual identity, you simply point color-brand-primary to a new primitive (e.g., color-indigo-600). Every component referencing that semantic token updates automatically across Figma and code.

3. Component-Specific Tokens

Component tokens restrict a value to a specific component state. These are optional for smaller projects but essential for enterprise web applications.

• button-primary-bg-default: points to color-brand-primary
• button-primary-bg-hover: points to color-brand-hover
• input-border-error: points to color-red-500

Naming Conventions That Map Directly to Code

For design tokens to speed up handoff, variable names in Figma must follow the exact structure your developers use in code (such as CSS custom properties or Tailwind configs).

Use a clear, hyphenated or dot-separated taxonomy:

[category]-[context]-[variant]-[state]

Examples:

• Design Token Name: color-button-primary-hover
• CSS Variable Output: --color-button-primary-hover: #0A44E0;
• Tailwind Extension: colors.button.primary.hover

When variable names match standard CSS variables, developers do not need to inspect visual elements to guess pixel counts or hex values. They simply inspect the token name in Figma Dev Mode and reference the matching variable in their code editor.

Using Variable Collections and Modes for Dark Mode and Multi-Brand

Figma collections allow you to group related variables together, while variable modes let you define multiple sets of values for the same token key.

To manage light and dark themes efficiently:

1. Create a collection called Semantic Tokens.
2. Add a variable called color-background-page.
3. Add two modes to the collection: Light and Dark.
4. In the Light mode column, point the value to color-neutral-50.
5. In the Dark mode column, point the value to color-neutral-950.

When a designer switches a canvas section from Light mode to Dark mode in Figma, the designs adjust instantly. On the frontend, developers map these Figma modes directly to CSS classes like .theme-light and .theme-dark.

Real-World Example: Updating Brand Colours Across Design and Code

Consider a SaaS marketing site with 40 distinct page layouts and 150 components built in React and Tailwind CSS.

Without Tokens:

The marketing team decides to adjust the main call-to-action button color for accessibility compliance.

• A designer opens Figma and manually selects 40 CTA components to update their color fill.
• The developer opens the pull request and searches through 18 different CSS files to replace hardcoded hex values.
• QA spends three hours verifying that secondary screens were not missed.

With Structured Tokens:

• In Figma, the designer updates the single alias token color-brand-primary from blue-500 to blue-600.
• Using a token sync plugin (or the Figma API), the updated token exports automatically to a shared tokens.json file in the GitHub repository.
• The build tool compiles tokens.json into CSS variables.
• Total time spent: under five minutes, with zero visual bugs or missed components.

How Developers Consume Figma Tokens

To eliminate manual copy-pasting during handoff, connect Figma variables to your codebase using automated token workflows:

• Style Dictionary: An open-source tool by Amazon that transforms token JSON files into platform-specific code (CSS, SCSS, Swift, Android XML, or JavaScript).
• Token Studio / Figma API: Plugins and native integrations that sync Figma variables directly to GitHub repositories whenever changes are published.

This approach ensures that developers never write raw values in custom CSS files. If a design choice does not exist as a token, it does not get built.

To apply this in your organisation, start by auditing your current Figma files and codebase to isolate your core brand primitives—colours, spacing scales, and border radii. Group these into a single Figma variable collection, name them using a clear hyphenated taxonomy that your frontend developers agree on, and restrict component styles to use those variables exclusively before starting your next dev sprint.