Marcus Andrey Study
Ler em português Library

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
The token set you'll build: one file of primitives and two independent axes, mode and density. Two modes times two densities give four combinations from five small files, without writing any of the four out by hand. That is the job of the DTCG resolver.Diagram: Marcus Andrey, CC BY 4.0. File layout follows the Design Tokens Community Group format and resolver modules, 2025.10.

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. $type can 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 colorSpace and components from 0 to 1; hex is an optional 6-digit fallback (DTCG, Color Module 2025.10).
  • A dimension value is an object with a number and a unit, px or rem.

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:

  1. A Primitives collection, one mode, with the palette and spacing.
  2. A Mode collection with two modes, Light and Dark, where each semantic variable is an alias to a primitive.
  3. A Density collection with Comfortable and Compact.
  4. Hide the primitives from publishing, so people only pick semantic variables.
  5. 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?

Themes and modes · Token tiers · Naming tokens · Tokens from Figma to code · Multi-brand and multi-product systems · Write a set of motion tokens

Saved only on this device.

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