Why Figma Variables and Design Tokens Belong Together

If you've ever updated a brand colour across 47 screens manually, or watched a developer implement slightly different spacing values than your mockups, you already understand the problem design tokens solve. Figma Variables — first introduced in 2023 and significantly expanded through 2024 and 2025 — are now the closest thing to a native design token system inside Figma itself.

Used correctly, Variables let you define a single source of truth for colour, spacing, typography, border radius, and more, then propagate changes instantly across your entire design file. This tutorial walks you through setting up Figma Variables as a practical design token system, including multi-mode theming (light/dark), token naming conventions, and exporting tokens to code.

This is the workflow the team at Lenka Studio uses when building scalable design systems for product teams across Australia, Singapore, Canada, and the US — and it saves dozens of hours on every project.

What You'll Need

  • Figma Professional, Organisation, or Enterprise plan (Variables require a paid plan for multi-mode support)
  • A component library file or a fresh design system file
  • Basic familiarity with Figma components and Auto Layout
  • Optional: the Tokens Studio for Figma plugin for advanced token export
  • Optional: a front-end codebase using CSS custom properties, Tailwind CSS, or a design token pipeline (Style Dictionary)

Step 1: Plan Your Token Architecture Before You Open Figma

The biggest mistake designers make is jumping straight into creating variables without a naming structure. Spend 20 minutes planning first — you'll save hours of renaming later.

Use a Three-Tier Token Model

Industry best practice in 2026 follows a three-tier hierarchy:

  • Primitive tokens — raw values: color/blue/500, spacing/4, radius/full
  • Semantic tokens — purpose-driven aliases: color/background/primary, space/component/padding-md
  • Component tokens — scoped to a specific component: button/background/default

Primitives never appear directly on components. Components reference semantic tokens, and semantic tokens reference primitives. This chain is what makes theming and rebranding effortless.

Decide Your Modes Up Front

Plan every mode (also called themes or contexts) before you create a single variable. Common modes include: Light / Dark, Brand A / Brand B (for white-label products), and Compact / Comfortable (for density scaling).

Pro tip: Keep modes within a single Variable Collection. Figma allows multiple modes per collection on paid plans — use this rather than creating separate files per theme.

Step 2: Create Your Primitive Variable Collection

Open your design system file in Figma. Go to Local Variables (the grid icon in the right panel, or via the menu: Assets → Local Variables).

  1. Click + Add collection and name it Primitives.
  2. For this collection, you only need one mode — primitives are raw values with no theming.
  3. Add variable groups using the slash naming convention. Click + to add a variable, name it color/blue/100, set its type to Color, and enter your hex value.

Build out your full colour ramp (100–900 for each hue), your spacing scale (using a base-4 or base-8 system), border radius values, and any numeric primitives like font sizes or line heights.

Recommended Primitive Groups to Create

  • color/neutral/ — 9 steps from 50 to 950
  • color/brand/ — your primary palette
  • color/semantic/ — success, warning, error, info
  • spacing/ — 0, 2, 4, 8, 12, 16, 24, 32, 48, 64, 96, 128 (in px, stored as numbers)
  • radius/ — none, sm, md, lg, full

Common pitfall: Don't store opacity variants (e.g. blue at 10% opacity) as separate primitive colours. Instead, apply opacity at the semantic or component level so you maintain flexibility.

Step 3: Build Your Semantic Variable Collection

Create a second collection named Semantic. This is where theming happens.

  1. Add your modes: click the Mode dropdown at the top of the collection and add Light and Dark.
  2. Create variable groups that describe purpose, not appearance. For example: color/background/page, color/background/surface, color/text/primary, color/text/secondary, color/border/default.
  3. For each variable, set its value by clicking the swatch and selecting Library → your Primitives collection. For color/background/page in Light mode, you might reference color/neutral/50. In Dark mode, reference color/neutral/950.

Repeat for spacing and radius semantic tokens if your design system uses density modes.

Naming Conventions That Scale

Follow this pattern: category/element/variant/state. Examples:

  • color/text/primary
  • color/text/primary/disabled
  • color/border/input/focus
  • space/inset/md

Keep names technology-agnostic. Avoid names like color/tailwind-blue or color/css-primary. Your tokens should work in any codebase.

Step 4: Apply Variables to Your Components

Now that your token architecture exists, connect it to your UI components.

  1. Select any element on your canvas — for example, a Button component's background fill.
  2. In the Fill panel, click the style icon and switch from the hex picker to Libraries. You'll now see your Variable collections listed.
  3. Choose the appropriate semantic token: color/background/primary for your primary button background.
  4. For spacing, select an Auto Layout frame, then click the spacing value fields. A variable icon appears — click it and bind to space/inset/md.

Pro tip: Apply variables to all four spacing values (top, right, bottom, left) independently where needed. Don't shortcut by eyeballing values — consistency here is what makes your system trustworthy for developers.

Testing Your Theme Modes

Select any frame that uses your semantic variables. In the right panel under Layer, find the Variables section. You can switch the frame between Light and Dark mode instantly. If your tokens are wired correctly, every colour flips without touching a single fill manually.

Step 5: Export Your Tokens for Developers

A design token system is only half useful if it lives in Figma alone. Export your variables into a format developers can consume.

Option A — Tokens Studio Plugin (Recommended)

  1. Install Tokens Studio for Figma.
  2. Open the plugin and sync your Figma Variables into the Tokens Studio format.
  3. Export as a tokens.json file, which follows the W3C Design Tokens Community Group specification (DTCG format, finalised in 2025).
  4. Hand this JSON to your developers. They can pipe it through Style Dictionary to generate CSS custom properties, Tailwind config values, Swift UI tokens, Jetpack Compose tokens, or any other output format.

Option B — Figma REST API

For teams with a dedicated design engineering function, the Figma REST API endpoint GET /v1/files/:file_key/variables/local returns all variables programmatically. You can build a CI/CD step that pulls token values and regenerates your CSS or Tailwind config on every design file publish.

A basic output in CSS custom properties looks like this:

:root {
  --color-background-page: #f9fafb;
  --color-text-primary: #111827;
  --space-inset-md: 16px;
}

[data-theme="dark"] {
  --color-background-page: #111827;
  --color-text-primary: #f9fafb;
}

Common pitfall: Don't export primitives directly to CSS. Only semantic tokens should be exported as custom properties — primitives are internal reference values and don't belong in production stylesheets.

Step 6: Document Your Token System for Your Team

An undocumented token system is an abandoned one. Set up a simple documentation page inside your Figma file.

  • Create a Token Reference page with a colour palette frame, spacing scale frame, and typography scale frame — all using live variable references, not hardcoded values.
  • Add a short annotation next to each semantic token group explaining its intended use case.
  • Include a "How to add a new token" section so junior designers and new team members can contribute without breaking the structure.

If you're building this for a client handoff or a product team, consider pairing your Figma token system with a branded style guide. Running a brand health score assessment beforehand helps identify whether your colour palette, typography, and visual language are consistent enough to systematise in the first place.

Common Pitfalls to Avoid

  • Skipping the primitive layer — If semantic tokens point directly to hex values, you lose the ability to globally update your palette in one place.
  • Too many modes too early — Start with Light and Dark. Add brand variants only when there's a real product requirement, not speculatively.
  • Inconsistent naming across design and code — Agree on the naming convention with your developer before you create your first variable. Rename pain later is real.
  • Treating component tokens as optional — For large systems (50+ components), component-scoped tokens make override patterns much cleaner.

Next Steps

Once your Figma Variables system is live and connected to your codebase, you have the foundation for true single-source-of-truth design. From here, you can explore automated token diffing in pull requests, per-tenant theming for SaaS products, and accessibility contrast checks baked directly into your semantic token definitions.

If you're setting up a design system for a product with real users and real engineering constraints, the architecture decisions you make at this stage matter enormously. The team at Lenka Studio has helped product teams across Australia, Singapore, and North America build token-driven systems that developers actually adopt — not just Figma files that look good in handoff and get ignored in code.

If you'd like a second pair of eyes on your token architecture, or you're ready to build a proper design system from the ground up, get in touch with us — we're happy to help you get it right the first time.