Design Systems · Step 2 · 6 min read
Colour, type and spacing as tokens
The foundations of a system, turned into tokens: colour roles designed in measured pairs, a type scale in rem that survives zoom, and a spacing scale with names for inside and between. Harbour's real values and contrast ratios, and what to document next to each token.
Foundation tokens are where accessibility is won or lost, once, for every screen. If
color.text.subtlepasses contrast oncolor.surface.default, every screen that uses the pair passes. If it doesn't, every screen fails, and nobody notices because each one "uses the system". So foundation tokens aren't a palette to pick from. They're a set of tested decisions, and the tests are part of the token.
What you'll be able to do after reading:
- Design colour tokens as pairs and document their measured contrast
- Build a type scale as tokens that respects zoom
- Turn the inventory's spacing values into a scale with clear roles
- Know which other foundations become tokens
1. Colour: tokens come in pairs
| Semantic token | Light | Dark | Measured against | Contrast, light / dark |
|---|---|---|---|---|
color. | sand.50 | ink.900 | (the background) | – |
color. | ink.900 | sand.50 | surface.default | 15.6 / 15.6 AAA |
color. | ink.600 | sand.300 | surface.default | 6.7 / 9.8 AA |
color. | blue.600 | blue.400 | surface.default, as a link | 6.0 / 5.3 AA |
color. | sand.50 | ink.900 | action.primary, as a button label | 6.0 / 5.3 AA |
color. | coral.600 | coral.400 | surface.default | 4.9 / 5.5 AA |
| Mistake to avoid | blue.600 | blue.600 kept | surface.default | 6.0 / 2.6 fails |
font.size.300 | 1rem (16 px) | same | body text | – |
space. | space.4 (16 px) | same; compact: space.3 (12 px) | padding inside cards | – |
A colour on its own has no contrast. Contrast belongs to a pair: text on a surface, a label on a button. So Harbour designs semantic colour tokens as pairs and measures every pair in every mode before publishing.
The numbers in the figure were computed with the WCAG relative luminance formula. The targets: 4.5 to 1 for normal text, 3 to 1 for large text (W3C, Understanding 1.4.3), and 3 to 1 for the parts of controls and focus indicators people need to see (W3C, Understanding 1.4.11). For that last one Harbour has color.border.focus, pointing at the same blues as color.action.primary: 6.0 to 1 on the light surface, 5.3 to 1 on the dark one.
Look at the "mistake" row. color.blue.600 on Harbour's dark surface is 2.6 to 1. That's why color.action.primary points at a lighter blue in dark mode, and why the next lesson exists. If you took UX Foundations, Colour and contrast covers the ratios themselves.
Document each pair next to the token: "use on surface.default; 6.0:1 light, 5.3:1 dark". Then anyone using the token knows where it's safe.
2. Type: a scale in rem
Type tokens come in two tiers too.
Primitives are the scale itself. Harbour's font sizes, built on the 16 px body size from the inventory:
| Token | rem | px at default |
|---|---|---|
font.size.100 |
0.75rem | 12 |
font.size.200 |
0.875rem | 14 |
font.size.300 |
1rem | 16 |
font.size.400 |
1.25rem | 20 |
font.size.500 |
1.5rem | 24 |
font.size.600 |
2rem | 32 |
Plus line heights (font.line-height.tight = 1.2, font.line-height.normal = 1.5), weights (font.weight.regular = 400, font.weight.semibold = 600) and the family.
In rem, not px, so text follows the size people set in their browser. WCAG asks that text can be resized to 200% without losing content or function (W3C, Understanding 1.4.4), and that nothing breaks when people raise line height to 1.5 times the font size (W3C, Understanding 1.4.12).
Semantic type tokens bundle those into styles with a job: font.body.md (size 300, line height normal, regular), font.heading.lg (size 600, tight, semibold), font.label.sm (size 200, normal, semibold). The DTCG format has a typography composite type for exactly this (DTCG, Format Module 2025.10). Components then use font.label.sm, never "14 px semibold". For building the scale itself, see Build a type scale and Typography for interfaces.
3. Spacing: a scale with roles
space.14 pxspace.28 pxspace.312 pxspace.416 pxspace.524 pxspace.632 pxspace.748 pxspace.864 px
The inventory found twenty-three spacing values, including 13, 15 and 18 px. Harbour keeps eight, on a 4 px base. The steps grow as they get bigger, because the difference between 4 and 8 px is easy to see, and the difference between 48 and 52 isn't.
Then semantic tokens give the scale roles:
- Inset: space inside a container.
space.inset.sm → space.2,space.inset.md → space.4,space.inset.lg → space.5. - Stack: vertical space between items.
space.stack.sm → space.2,space.stack.md → space.4,space.stack.lg → space.6. - Inline: horizontal space between items in a row.
space.inline.sm → space.2,space.inline.md → space.3.
The roles are what make density possible: the console's compact mode moves space.inset.md from space.4 to space.3 and leaves the scale alone. Layout, grids and spacing covers how a spacing scale fits a grid.
4. The other foundations
The same method applies to every repeated visual decision:
- Radius:
radius.sm = 4px,radius.md = 8px; semanticradius.control → radius.md. - Border width:
border.width.default = 1px,border.width.focus = 2px. - Elevation: a few named shadows,
elevation.raised,elevation.overlay, rather than a new shadow per component. - Motion: durations and easings as tokens. That's a whole lesson in the motion course: Motion tokens.
- Breakpoints and sizes: minimum touch size, container widths.
Start with the ones your inventory found the most variation in. For Tidewater: blues, spacing, then radius.
5. Common mistakes
- Publishing a colour token without its pair and its measured contrast.
- Font sizes in px, so browser text size settings don't reach them.
- A spacing scale with no roles, so people pick "something that looks right" from eight numbers.
- Line heights baked into each component instead of shared tokens.
- Tokenising everything at once, including values used in only one place.
6. Vocabulary
| Term | Meaning |
|---|---|
| Colour pair | A foreground token and the background it's tested on |
| Type scale | The fixed set of font sizes a system allows |
| rem | A CSS unit relative to the root font size, which follows the user's settings |
| Composite token | A token made of several values, like a typography style |
| Inset, stack, inline | Space inside a container, between items vertically, between items in a row |
| Density | How tightly a layout is spaced, such as comfortable or compact |
7. Try it (no tools needed)
- Take a screen you know and list every text colour on it and the background each sits on.
- Write each pair as two token names, like
color.text.subtleoncolor.surface.default. - If you can, check one pair in a contrast checker. If not, mark the pair you'd check first.
Reflection questions: Which pair would fail first in dark mode? Which spacing values on the screen have no clear role?
8. If you already practise
- Generate the contrast table from the tokens, in every mode, and fail the build when a documented pair drops below its target.
- Write "use on" for every semantic colour, and the reverse "never on" where people get it wrong.
- Test the type scale at 200% browser zoom and with 1.5 line height on your densest screen.
Checklist
Learn more
- W3C: Understanding 1.4.3, Contrast (minimum) · 1.4.11, Non-text contrast · 1.4.4, Resize text · 1.4.12, Text spacing
- Design Tokens Community Group: Format Module 2025.10, types · Color Module 2025.10
- IBM Carbon: Color tokens
Books, courses and videos to go deeper
- Design SystemsAlla KholmatovaBook · Smashing Media, 2017 (Amazon)
- Atomic DesignBrad Frost2016, free online (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Token tiers · Themes and modes · Colour and contrast · Build a type scale · Typography for interfaces · Layout, grids and spacing · Motion tokens · Accessible components