Marcus Andrey Study
Ler em português Library

Design Systems · Step 2 · 8 min read

Tokens from Figma to code

Tokens are only useful if design and code read the same ones. Where the source of truth should live, how Figma variables, DTCG token files and a build tool like Style Dictionary fit together, what a Harbour token file looks like, and what's stable in the standard today.

A token that lives in two places is two tokens, and they will drift. Figma has variables, code has custom properties, and the day someone changes one by hand the other is out of date. The fix isn't discipline. It's a pipeline: one source of truth, one direction of travel, and a machine doing the copying. This lesson is about building that pipeline, small enough that a team of three can run it.

What you'll be able to do after reading:

  • Choose where your tokens' source of truth lives
  • Follow tokens from Figma variables to CSS and native code
  • Read and write a token file in the DTCG format
  • Know what's stable in the standard and what's still moving

1. The pipeline

  1. Figma variablesCollections Primitives and Semantic; modes Light, Dark and Compact. Aliases link semantic to primitive.
  2. ExportA plugin or the Figma REST API reads the variables, with their modes and aliases.
  3. Token filesharbour.tokens.json in the DTCG format, kept in the code repository and reviewed like code.
  4. BuildA tool such as Style Dictionary turns one source into each platform's format.
    • CSS
    • iOS
    • Android
  5. ComponentsCode reads var(--hb-color-action-primary), never a hex value. Dev Mode shows the same name.
One way Harbour's tokens travel from Figma to the products. The order matters less than the rule behind it: one source of truth, one direction, and every step automatic, so nobody copies a hex value by hand.Diagram: Marcus Andrey, CC BY 4.0.

Five steps, and the only manual one is the first: a person decides a value. Everything after that is copying, and copying is what machines are for.

The figure starts in Figma, but that's a choice, not a rule. The key decision is where the source of truth lives:

  • Figma first. Designers edit variables; an export turns them into token files. Good when designers own the decisions and change them often.
  • Code first. Token files live in the repository and are edited in pull requests; a sync pushes them into Figma. Good when you need review, history and releases for every change, which most systems want sooner or later.

Either way, pick one and make the other read-only. Two-way editing is how you get two truths.


2. Figma variables

Figma variables are Harbour's tokens on the design side. A few facts that shape how you set them up (Figma Help, Overview of variables, collections, and modes):

  • There are six types: colour, number, string, boolean, timing and easing.
  • A collection is "a set of variables and modes". Harbour uses one for Primitives, one for Semantic colour (Light and Dark modes) and one for Density (Comfortable and Compact).
  • A variable can reference another of the same type, which Figma notes "is also called aliasing". That's the tier chain from Token tiers.

Two settings matter for the pipeline (Figma Help, Create and manage variables):

  • Scoping limits where a variable can be used, so space.inset.md only appears in padding and gap pickers, and colour primitives can be kept out of fill pickers.
  • Code syntax gives each variable its code name, for up to three platforms. Dev Mode shows it in code snippets, which "are supported in CSS, SwiftUI, and Compose". Set Web to var(--hb-color-action-primary) and the developer sees the real token, not a hex value. This is the token side of Handoff to developers.

3. Getting tokens out of Figma

The variables need to leave Figma as files. Two routes:

  • The REST API. It has "endpoints for querying, creating, updating, and deleting variables", meant to "sync design system source of truth to and from Figma". It needs a Full seat in an Enterprise organisation (Figma Developers, Variables).
  • A plugin. On other plans, a plugin can read and write variables; Figma links to a sample for import and export (Figma Help, Guide to variables).

Whatever exports them should write the DTCG format, so any tool down the line can read the file.


4. The token file

The Design Tokens Community Group published the first stable version of its specification, 2025.10, on 28 October 2025: a Format module, a Color module and a Resolver module for modes (designtokens.org, Technical reports · 2025.10 modules). It's a Community Group report, "not a W3C Standard nor is it on the W3C Standards Track", and it calls itself stable and ready to implement (DTCG, Format Module 2025.10). The announcement lists support or work in progress in tools including Style Dictionary, Tokens Studio, Terrazzo, Penpot, Figma, Sketch, Framer and zeroheight (W3C, DTCG announcement, 2025).

Here's part of Harbour's core file, harbour.tokens.json:

{
  "color": {
    "$type": "color",
    "blue": {
      "600": {
        "$value": { "colorSpace": "srgb", "components": [0.1216, 0.3725, 0.6824], "hex": "#1f5fae" }
      }
    },
    "action": {
      "primary": {
        "$value": "{color.blue.600}",
        "$description": "Main action on a screen. Use on color.surface.default: 6.0:1 light, 5.3:1 dark."
      }
    }
  },
  "space": {
    "$type": "dimension",
    "4": { "$value": { "value": 16, "unit": "px" } },
    "inset": {
      "md": { "$value": "{space.4}" }
    }
  }
}

How to read it, rule by rule from the spec:

  • An object with $value is a token; everything else is a group. color.action.primary is the path through the groups.
  • $type can sit on a group and applies to every token inside. Tools "must not attempt to guess the type" from the value.
  • Aliases use curly braces: "{color.blue.600}".
  • Colours are objects with a colorSpace and components, and an optional hex fallback (DTCG, Color Module 2025.10). The components here are 31, 95 and 174 divided by 255.
  • Dimensions are a number and a unit, px or rem.
  • $description is where the measured contrast from Colour, type and spacing as tokens goes, so it travels with the token.
  • Files use .tokens or .tokens.json.

Dark mode and compact density live in small extra files, mode/dark.tokens.json and density/compact.tokens.json, that only re-point semantic tokens. The Resolver module says how to combine them: a mode modifier with light and dark contexts, a density modifier with comfortable and compact, merged in order (DTCG, Resolver Module 2025.10). That's the CSS from Themes and modes, as data.


5. From the file to every platform

A build tool reads the token file and writes each platform's format. Style Dictionary is the best-known open-source one: it exports "to any platform", including CSS, iOS and Android. Its documentation says that "as of version 4, Style Dictionary has first-class support for the DTCG format", and also, honestly, that 2025.10 "does not have full support yet", with full support "a work in progress in v5" (Style Dictionary, DTCG). Check your tool's notes before you depend on a newer part of the spec, like the resolver.

For Harbour the output is a CSS file with the custom properties you saw in the demo, plus Swift and Kotlin constants for future native apps. Nobody edits those files by hand; they're rebuilt on every change and published as a package with a version number (see Versioning and releases).


6. Common mistakes

  • Two sources of truth, edited in both places.
  • Exporting resolved hex values only, so aliases are lost and dark mode can't be rebuilt.
  • Variables with no code syntax, so Dev Mode shows hex values and developers copy them.
  • Hand-edited generated files, overwritten on the next build.
  • Building the pipeline before there are tokens worth piping. A small, correct token set in one file beats a perfect pipeline for a messy one.

7. Vocabulary

Term Meaning
Source of truth The one place a token is edited; everything else is generated
DTCG format The Design Tokens Community Group's JSON format for tokens, stable since 2025.10
Collection A Figma set of variables that share modes
Scoping Limiting which properties a Figma variable can be applied to
Code syntax The code name of a Figma variable, shown in Dev Mode
Build tool A program, like Style Dictionary, that turns token files into platform code

8. Try it (no tools needed)

  1. Take three Harbour tokens: color.blue.600, color.action.primary and space.inset.md.
  2. Write each one as it would appear in the DTCG file, in Figma (collection, group, name) and in CSS.
  3. Mark which one would change in dark mode, and in which file.

Reflection questions: Who on your team should be allowed to change a token's value? Where would they do it, and who would review it?


9. If you already practise

  • Put the token files in version control with a changelog, and treat a renamed token as a breaking change.
  • Validate token files in CI: every alias resolves, every $type is set, every documented colour pair still passes.
  • Diff Figma against the token files on a schedule and report differences, even if you can't sync automatically yet.
  • Connect components the same way tokens are connected: that's Code Connect and the design-code bridge.

Checklist

Learn more

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Themes and modes · Naming tokens · Token tiers · Handoff to developers · Building a Figma library · Code Connect and the design-code bridge · Versioning and releases · Build a token set with modes

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close