Marcus Andrey Study
Ler em português Library

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.subtle passes contrast on color.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 tokenLightDarkMeasured againstContrast, light / dark
color.surface.default sand.50 ink.900(the background)–
color.text.default ink.900 sand.50surface.default15.6 / 15.6 AAA
color.text.subtle ink.600 sand.300surface.default6.7 / 9.8 AA
color.action.primary blue.600 blue.400surface.default, as a link6.0 / 5.3 AA
color.text.on-action sand.50 ink.900action.primary, as a button label6.0 / 5.3 AA
color.feedback.danger coral.600 coral.400surface.default4.9 / 5.5 AA
Mistake to avoid blue.600 blue.600 keptsurface.default6.0 / 2.6 fails
font.size.3001rem (16 px)samebody text–
space.inset.mdspace.4 (16 px)same; compact: space.3 (12 px)padding inside cards–
Harbour's foundation tokens with their measured contrast. Every colour pair was checked in both modes before the token was published, and the numbers live in the token's documentation. The "mistake" row is what happens if dark mode keeps the light blue: 2.6 to 1, well under the 4.5 to 1 WCAG asks for text.Ratios computed with the WCAG 2.2 relative luminance formula. Table: Marcus Andrey, CC BY 4.0.

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

  1. space.14 px
  2. space.28 px
  3. space.312 px
  4. space.416 px
  5. space.524 px
  6. space.632 px
  7. space.748 px
  8. space.864 px
Harbour’s spacing scale: eight steps on a 4 px base, growing faster as they get bigger. Twenty-three spacing values found in the inventory became these eight. Small steps separate things inside a component; big steps separate sections.Diagram: Marcus Andrey, CC BY 4.0.

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; semantic radius.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)

  1. Take a screen you know and list every text colour on it and the background each sits on.
  2. Write each pair as two token names, like color.text.subtle on color.surface.default.
  3. 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

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.

Token tiers · Themes and modes · Colour and contrast · Build a type scale · Typography for interfaces · Layout, grids and spacing · Motion tokens · Accessible components

Saved only on this device.

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