Design Systems · Labs · 4 min read
Build a token set with modes
A guided lab: write a small Harbour token set in the DTCG format, with primitives, semantic tokens for light and dark, a density axis and a resolver file, then check every pair's contrast and mirror it in Figma variables. About two hours, with a text editor and Figma.
Modes are easy to switch and hard to keep honest. Adding dark mode looks like a palette job. In practice it's a naming job: if the tokens describe roles, not colours, the second mode is a list of new values. You'll build a small token set that proves it, in the format tools are converging on, and check that every pair still passes in both modes.
What you'll do:
- Write primitive tokens in the DTCG format
- Write semantic tokens for light and dark that point to them
- Add density as a second, independent axis
- Describe the axes in a resolver file
- Measure every text pair in both modes, and mirror the set in Figma
You'll need: a text editor that checks JSON (VS Code or any code editor), Figma (a plan with variable modes), the WebAIM contrast checker, about two hours.
1. The shape of what you'll build
primitives.tokens.json
The palette and the scales. Same in every mode. Nobody uses these directly.
color.blue. 600 - #1F5FAE
color.blue. 400 - #5B95DB
color.ink.900- #14202B
color.sand.50- #FBF8F2
space.3·space.4- 12 px · 16 px
light / dark.tokens.json
The same semantic names in each file, pointing at different primitives.
color.action. primary - light →
{color.blue. 600}
dark →{color.blue. 400} color.text. default - light →
{color.ink. 900}
dark →{color.sand. 50} color.surface. default - light →
{color.white}
dark →{color.ink. 900}
comfortable / compact.tokens.json
A second, independent axis: density, for the staff console.
space.inset. md - comfortable →
{space.4}16 px
compact →{space.3}12 px size.control. height - comfortable → 44 px
compact → 36 px
Five small files and one resolver. The DTCG Format Module reached its first stable version, 2025.10, in October 2025; it recommends the .tokens.json extension (DTCG, Format Module 2025.10). The rules you need for this lab:
- A token is an object with a
$value.$typecan sit on the token or on its group. - An alias points to another token with curly braces:
"{color.blue.600}". - A colour value is an object with a
colorSpaceandcomponentsfrom 0 to 1;hexis an optional 6-digit fallback (DTCG, Color Module 2025.10). - A dimension value is an object with a number and a unit,
pxorrem.
2. Write the primitives
primitives.tokens.json holds the raw palette and scale. Nobody uses these in a component.
{
"color": {
"$type": "color",
"blue": {
"400": { "$value": { "colorSpace": "srgb", "components": [0.3569, 0.5843, 0.8588], "hex": "#5b95db" } },
"600": { "$value": { "colorSpace": "srgb", "components": [0.1216, 0.3725, 0.6824], "hex": "#1f5fae" } }
},
"ink": {
"900": { "$value": { "colorSpace": "srgb", "components": [0.0784, 0.1255, 0.1686], "hex": "#14202b" } }
},
"sand": {
"50": { "$value": { "colorSpace": "srgb", "components": [0.9843, 0.9725, 0.949], "hex": "#fbf8f2" } }
},
"white": { "$value": { "colorSpace": "srgb", "components": [1, 1, 1], "hex": "#ffffff" } }
},
"space": {
"$type": "dimension",
"3": { "$value": { "value": 12, "unit": "px" } },
"4": { "$value": { "value": 16, "unit": "px" } },
"5": { "$value": { "value": 24, "unit": "px" } }
}
}
Convert a hex value to components by dividing each pair by 255: 1F is 31, and 31 ÷ 255 is 0.1216.
3. Write the semantic tokens, once per mode
mode/light.tokens.json and mode/dark.tokens.json have exactly the same names. Only the aliases differ.
{
"color": {
"$type": "color",
"action": { "primary": { "$value": "{color.blue.600}", "$description": "Main action: one per screen" } },
"text": {
"default": { "$value": "{color.ink.900}" },
"on-action": { "$value": "{color.white}" }
},
"surface": { "default": { "$value": "{color.white}" } }
}
}
And the dark file:
{
"color": {
"$type": "color",
"action": { "primary": { "$value": "{color.blue.400}", "$description": "Main action: one per screen" } },
"text": {
"default": { "$value": "{color.sand.50}" },
"on-action": { "$value": "{color.ink.900}" }
},
"surface": { "default": { "$value": "{color.ink.900}" } }
}
}
Look at text.on-action: white in light, ink in dark. White on blue.400 is only 3.1:1, which fails for text, so the dark mode needs dark text on its button. That's the kind of thing you only find by measuring.
4. Add density as its own axis
density/comfortable.tokens.json and density/compact.tokens.json, for the staff console:
{
"space": {
"$type": "dimension",
"inset": { "md": { "$value": "{space.4}" } }
}
}
In the compact file, space.inset.md points to {space.3}. Density doesn't care about light or dark, so it stays a separate pair of files, not four combined ones.
5. Describe the axes in a resolver
harbour.resolver.json lists the always-on set and the two modifiers. The tool picks one context per modifier (DTCG, Resolver Module 2025.10):
{
"version": "2025.10",
"sets": {
"core": { "sources": [{ "$ref": "primitives.tokens.json" }] }
},
"modifiers": {
"mode": {
"contexts": {
"light": [{ "$ref": "mode/light.tokens.json" }],
"dark": [{ "$ref": "mode/dark.tokens.json" }]
},
"default": "light"
},
"density": {
"contexts": {
"comfortable": [{ "$ref": "density/comfortable.tokens.json" }],
"compact": [{ "$ref": "density/compact.tokens.json" }]
},
"default": "comfortable"
}
},
"resolutionOrder": [
{ "$ref": "#/sets/core" },
{ "$ref": "#/modifiers/mode" },
{ "$ref": "#/modifiers/density" }
]
}
Tool support is still catching up with the stable spec. Style Dictionary has supported the DTCG format since version 4, but says the 2025.10 format isn't fully supported yet (Style Dictionary, DTCG). Check your tool before you rely on the colour objects or the resolver; the structure of your files is right either way.
6. Measure every pair, in both modes
Make a small table and fill it with the contrast checker:
| Pair | Light | Dark |
|---|---|---|
text.default on surface.default |
ink.900 on white: 16.52:1 | sand.50 on ink.900: 15.58:1 |
text.on-action on action.primary |
white on blue.600: 6.35:1 | ink.900 on blue.400: 5.32:1 |
action.primary against surface.default (a control's edge, 3:1 needed) |
6.35:1 | 5.32:1 |
Text needs 4.5:1 and the edge of a control 3:1 (W3C, Understanding 1.4.3, Understanding 1.4.11). Every Harbour pair here passes. If one of yours doesn't, change the alias in that mode's file, not the component.
7. Mirror it in Figma
In Figma, a mode is a list of values for the variables in a collection, one value per variable (Figma, Overview of variables, collections and modes). Build it to match the files:
- A Primitives collection, one mode, with the palette and spacing.
- A Mode collection with two modes, Light and Dark, where each semantic variable is an alias to a primitive.
- A Density collection with Comfortable and Compact.
- Hide the primitives from publishing, so people only pick semantic variables.
- Make a frame with a card and a button, apply the semantic variables, and switch the modes on the frame.
If anything changes colour wrongly when you switch, a layer is bound to a primitive. Fix the binding.
8. Check your work
Reflection questions: Which token did you have to add because of dark mode, like text.on-action? What would a third axis, such as high contrast, add to the files?
Related
Themes and modes · Token tiers · Naming tokens · Tokens from Figma to code · Multi-brand and multi-product systems · Write a set of motion tokens