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
- Figma variablesCollections
PrimitivesandSemantic; modes Light, Dark and Compact. Aliases link semantic to primitive. - ExportA plugin or the Figma REST API reads the variables, with their modes and aliases.
- Token files
harbour.in the DTCG format, kept in the code repository and reviewed like code.tokens. json - BuildA tool such as Style Dictionary turns one source into each platform's format.
- CSS
- iOS
- Android
- ComponentsCode reads
var(--hb-color-action-primary), never a hex value. Dev Mode shows the same name.
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.mdonly 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
$valueis a token; everything else is a group.color.action.primaryis the path through the groups. $typecan 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
colorSpaceandcomponents, and an optionalhexfallback (DTCG, Color Module 2025.10). The components here are 31, 95 and 174 divided by 255. - Dimensions are a number and a unit,
pxorrem. $descriptionis where the measured contrast from Colour, type and spacing as tokens goes, so it travels with the token.- Files use
.tokensor.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)
- Take three Harbour tokens:
color.blue.600,color.action.primaryandspace.inset.md. - Write each one as it would appear in the DTCG file, in Figma (collection, group, name) and in CSS.
- 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
$typeis 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
- Design Tokens Community Group: designtokens.org · Format Module 2025.10 · Color Module 2025.10 · Resolver Module 2025.10 · W3C announcement (2025)
- Figma: Overview of variables, collections, and modes · Create and manage variables · Variables REST API
- Style Dictionary · its DTCG notes
Books, courses and videos to go deeper
- Guide to variables in FigmaFigma Helpfree, articles and tutorials (external site)
- Design SystemsAlla KholmatovaBook · Smashing Media, 2017 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
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