Setting up design tokens in Figma
Learn

Setting up design tokens in Figma: variables, collections and modes

Author Avatar
Written by
Jun 22, 2026

Figma Variables, launched in 2023, gave designers a native way to work with design tokens directly in their design tool. For the first time, the structure of a token system (primitives, semantic aliases, modes) could be expressed inside Figma rather than maintained separately and imported.

But the fact that you can set up tokens in Figma doesn't mean the setup is obvious. The choices you make early (how many collections, how to handle modes, how to structure multi-brand systems) have downstream consequences for how well the system scales and how cleanly it connects to code. This article covers those foundational decisions.

If you're new to the three-tier token hierarchy (global → alias → component), Article 02 — How design tokens work: types, structure and hierarchy covers that foundation before diving into the Figma-specific implementation here.

How Figma's model maps to the token hierarchy

Figma Variables has three organizational concepts: collections, groups, and variables. Understanding how these map to your token hierarchy is the starting point for a well-structured setup.

Collections are the top-level containers for variables. They're the natural place to express the tiers of your token system: a collection for primitives, a collection for semantic aliases, and optionally a collection for component tokens.

Groups are folders within a collection, created using / in the variable name. color/blue/500 creates a color group containing a blue subgroup containing a variable called 500. Groups are how you organize variables of the same type within a collection. Your primitives collection might have a color group, a spacing group, a radius group, and so on.

Variables are the individual tokens: the named values that components reference.

The resulting structure for a typical system looks like this:

00 Primitives (collection)
  color/
    blue/500, blue/600, blue/700...
    neutral/50, neutral/100...
  space/
    4, 8, 12, 16, 24...
  radius/
    sm, md, lg, full

01 Semantic (collection)
  color/
    action/primary, action/primary-hover...
    surface/default, surface/raised...
    text/primary, text/secondary...
  space/
    component/padding-sm, component/padding-md...

02 Component (collection, optional)
  button/
    background, background-hover...
  input/
    border, border-active...

This naming convention (a numeric prefix on collections, slash-separated groups within them) makes the hierarchy legible at a glance and produces clean JSON output when tokens are exported.

Variable types: what each is for

Figma Variables support four value types. Choosing the right type for each variable matters both for how Figma handles the value internally and for how it exports to code.

Color: For any value that resolves to a color: palette values, semantic color roles, component background and text colors. Figma stores these as hex values with optional opacity.

Number: For numeric values without a unit: spacing steps, font sizes (expressed as raw numbers, with the unit handled downstream), border widths, border radius values, opacity percentages. Most design token values that aren't colors are numbers in Figma.

String: For text values: font family names, font weight names, any token that resolves to a string rather than a numeric or color value. String variables are also useful for non-design values like breakpoint names or animation easing curves.

Boolean: For true/false values. In practice, boolean variables are most useful for controlling visibility in component variants (show/hide an element based on a boolean variable) rather than for design tokens as traditionally defined. They're less common in token-focused setups.

For most token systems, the vast majority of variables will be Color and Number types, with a small set of String variables for typography.

Collection architecture: how many collections?

The question most teams wrestle with first is how to split variables into collections. There are two main approaches.

One collection per token tier

The simplest and most common starting point is one collection per tier: primitives, semantics, and (optionally) components. Within each collection, you use group notation to organize by type:

00 Primitives
  color/blue/500
  color/neutral/100
  space/4
  radius/md

01 Semantic
  color/action/primary → {color/blue/500}
  color/surface/default → {color/neutral/100}
  space/component/padding → {space/4}

This keeps things simple and easy to navigate. It works well for small-to-medium token systems and is the right default for teams getting started.

Multiple collections per tier

For larger systems, some teams split semantic variables into separate collections by type, one for color, one for spacing, one for typography, one for shadows:

01 Color (collection)
01 Spacing (collection)
01 Typography (collection)
01 Shadows (collection)

The benefit is navigability in large systems where a single semantic collection might contain hundreds of variables. The trade-off is operational: every collection is managed separately, and if you're using modes, you'll need to apply them to each collection individually. For most teams, the simpler single-collection-per-tier approach is the right starting point. Splitting by type makes sense when the system is large enough that a single collection becomes genuinely hard to navigate.

One consistent recommendation: keep primitives in a single collection. Splitting primitives across multiple files or collections adds management overhead without meaningful benefit. The primitive layer is the foundation that everything else references, and keeping it consolidated makes that relationship clear.

Setting up modes

Modes are one of Figma Variables' most powerful features, and one of the easiest to misconfigure. A mode is a named variant of a collection (light and dark, for example, or Brand A and Brand B) that lets you switch the resolved values of every variable in the collection with a single toggle.

The key principle for modes: use them for one thing per collection.

Mixing mode purposes inside a single collection (using modes for both light/dark and brand switching simultaneously) produces a combinatorial explosion that's hard to manage and harder to explain to other designers. If you need both color modes and brand modes, define them in separate collections.

A well-configured color mode setup in a semantic collection:

01 Semantic (collection)
  Modes: Light | Dark | High Contrast
  
  color/surface/default
    Light:         {color/neutral/50}   → #FAFAFA
    Dark:          {color/neutral/900}  → #171717
    High Contrast: {color/neutral/0}    → #FFFFFF

The primitive collection doesn't need modes. blue/500 is always #3B82F6 regardless of theme. Modes belong at the semantic tier, where the role of a value changes with context even though the underlying palette stays stable.

Figma plan limits matter here. Non-enterprise plans support a maximum of four modes per collection; enterprise supports up to 40. If your system needs more than four modes in a collection (for example, more than four brand variants) you'll need to restructure, either by splitting brands into separate collections or by upgrading your plan. Know this limit before you design your mode structure, not after.

When applying modes in the canvas, you set the mode at the frame or component level. If your variables are split across multiple collections, you'll need to set the mode for each collection separately, another reason to keep the number of collections manageable.

For a deeper look at how modes work at the token level and how to avoid combinatorial complexity, Article 06 — Token modes: handling variation in your token system covers the underlying principles. Article 16 — Figma variable modes in depth covers the Figma-specific implementation in full.

Multi-brand systems in Figma

If your system needs to support multiple brands, the most practical Figma approach is to keep all brands in a single library file, with brand-specific variables organized into separate collections.

The alternative (a separate Figma file per brand) introduces aliasing complexity: variables in one file can't reference variables in another, which means your semantic aliases won't resolve correctly across files. For completely independent brands with no shared primitives, separate files may be appropriate. For brands that share a foundation (the same grid, the same spacing scale, similar semantic structure) but differ in color and typography, a single file with brand-organized collections is significantly more maintainable.

Within a single file, there are two ways to structure brand differentiation:

Separate collections per brand: Each brand gets its own semantic collection (01 Brand A Color, 01 Brand B Color). This makes brand switching explicit and keeps brand-specific variables clearly separated.

Groups within a shared collection: Brand differences are expressed through groups inside a shared collection (color/brand-a/action/primary, color/brand-b/action/primary). This works for smaller multi-brand systems but becomes unwieldy as the number of brands grows.

For most multi-brand setups, separate collections per brand at the semantic level is the cleaner approach. It's easier to navigate, easier to document, and easier to govern. You know exactly which variables belong to which brand.

Scoping variables

Figma lets you scope variables to specific contexts, restricting which variables appear in which property panels. A color variable scoped to "Fill" won't appear in the text color picker; a number variable scoped to "Gap" won't appear in the font size field.

Scoping serves two purposes. First, it reduces noise: designers working on typography don't see spacing tokens in the font size field, and vice versa. Second, it reduces misuse: a spacing token that shouldn't be used for border radius can be scoped to exclude that property.

For primitive collections, scoping can be loose, since primitives are the raw material and may legitimately be used in multiple contexts. For semantic and component collections, tighter scoping that matches the token's role makes the system easier to use correctly.

Organizing large variable libraries

As the number of variables grows, a few practices keep libraries navigable:

Consistent group depth. Using a consistent number of slash-separated levels within each collection makes the structure predictable. color/action/primary and color/surface/default both follow a two-level structure under color. Mixing flat names with deeply nested ones makes the library harder to scan.

Numeric collection prefixes. Prefixing collection names with numbers (00 Primitives, 01 Semantic) makes the hierarchy clear in the collections panel and ensures they sort in the right order rather than alphabetically.

Documentation in Figma. For larger libraries, cover pages and annotated frames within the library file that explain the collection structure and naming conventions help new contributors understand the system before they start editing. The naming conventions themselves are covered in Article 15 — Naming your design tokens in Figma.

Audit regularly. Figma libraries accumulate unused variables. A quarterly check (which variables are actually in use in components, which are referenced by other variables, which aren't referenced anywhere) keeps the library lean. An unused primitive is harmless; an unused semantic token is a signal that either the role isn't real or the token hasn't been documented well enough to be discovered.

What comes next

Article 15 — Naming your design tokens in Figma: variables, groups and conventions covers the Figma-specific naming decisions in depth: slash notation, group naming, scoping labels, and how to migrate an existing variable library to a cleaner naming structure.

Article 16 — Figma variable modes in depth goes deep on the modes implementation: multi-mode setups, mode inheritance, using modes for brand switching, and how Figma modes map to code-side theme switching.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post