Chapter 06 — Design Tokens & Systems Thinking

The problem this solves

Imagine you designed an app with 47 screens. Every button uses the same shade of yellow. Then your company rebrands and the yellow changes to orange. Without design tokens, you update 47 screens in Figma and tell a developer to find every instance of #f5e642 in the code and replace it. That's hours of tedious work — and something will get missed. You'll ship the rebrand and find a rogue yellow button hiding on screen 31.

With design tokens, you change one value in one place — and everything updates everywhere. One change in Figma, one change in code. Done. That's not just a nice workflow improvement. It's a completely different way of working.

This is why every mature design system in the world uses tokens. Google Material, Apple HIG, Shopify Polaris, Atlassian Design System — all of them are built on this foundation. It's the industry standard. And it starts with a simple concept: named values.

What is a design token?

A design token is a named value. That's it.

Instead of "that yellow we use for buttons," you have a token named color/action/primary. Instead of "the normal body text size," you have a token named font-size/body. The name is the token. The value behind it can change, but the name stays the same — and everything that references that name updates automatically.

Think of it like a variable in algebra. If x = 5 today and x = 7 tomorrow, every equation that uses x gets the new value automatically. A design token works the same way.

Tokens exist for every design decision that repeats:

Colors — brand colors, neutral scales, semantic colors (error, success, warning)
Typography — font families, sizes, weights, line heights
Spacing — padding and gap values, usually based on a 4px or 8px grid
Border radius — from sharp to fully rounded
Shadows & elevation — depth and layering

CSS variables — tokens in code

In CSS, design tokens are implemented as "custom properties" — more commonly called CSS variables. Here's what they look like:

/* Define your tokens here — once, for the whole page */
:root {
  --color-action-primary: #f5e642;
  --color-bg: #0a0a0a;
  --color-text-primary: #f0f0f0;
  --font-size-body: 17px;
  --space-4: 16px;
  --radius-button: 6px;
}

/* Use them with var(--token-name) */
.button {
  background: var(--color-action-primary);
  color: var(--color-text-primary);
  font-size: var(--font-size-body);
  padding: var(--space-4);
  border-radius: var(--radius-button);
}

/* Now change ONE variable... */
:root {
  --color-action-primary: #ff6b35; /* yellow → orange */
}
/* ...and EVERY button on the page updates instantly */

:root is a special CSS selector that applies to the entire page — it's your global token dictionary. Variables defined there are available everywhere in your CSS. var(--variable-name) is how you use them. Anywhere you'd put a raw value like #f5e642, you write var(--color-action-primary) instead.

Figma Variables — the design side of tokens

In 2023, Figma introduced Variables — the design equivalent of CSS variables. You define named values for colors, spacing, and other properties in Figma, and use those names instead of raw values in your designs.

The goal: your Figma variable named color/action/primary maps directly to your CSS variable --color-action-primary. Same concept, both tools. When someone changes the value in Figma Variables, designers see the update. When someone changes the CSS variable, developers see the update. One concept, two expressions.

Variables require a paid Figma plan. On the free plan, use Color Styles and Text Styles instead — they work the same way conceptually, just with a slightly different UI. The key habit: always name your colors and text styles. Never leave them as raw hex values.

💡 Free plan tip

Use Styles on the free plan

In Figma, select a layer with a color → in the right panel, look for the "Fill" section → click the 4-dot grid icon → "+" → name your color (e.g., "Action / Primary"). Now you have a named color style you can apply anywhere. Change it once, update everywhere — same power as Variables, just one step less automated.

Naming tokens: the rule that changes everything

There's one rule that makes the difference between a token system that works and one that breaks down in 6 months: name tokens by their role, not their value.

/* ❌ BAD — named by value */
--yellow: #f5e642;
--dark-gray: #333333;
--sixteen-pixels: 16px;

/* ✓ GOOD — named by role */
--color-action-primary: #f5e642;
--color-text-muted: #333333;
--space-4: 16px;

Why does this matter? If your brand color changes from yellow to orange, --yellow becomes a lie — it stores orange but the name says yellow. Every developer who reads it is confused. But --color-action-primary is still true — it's still the primary action color, regardless of what the actual color happens to be. The meaning is stable even when the value changes.

You need: VS Code Your index.html from Chapter 02

1

Open your index.html from Chapter 02 in VS Code. Look at the CSS — you'll see raw color values scattered throughout (like #0a0a0a, #ffffff, 16px, etc.).
2

At the very top of your <style> tag, add a :root { ... } block. For each unique color and spacing value you're using, create a named CSS variable with a role-based name.
3

Replace every raw color and spacing value in your CSS with var(--your-token). Where you had color: #f0f0f0, write color: var(--color-text-primary).
4

Save and reload Chrome. Nothing should look different — the tokens have the same values, they're just named now.
5

Now change one variable value in :root — say, change your background color. Save and reload. Watch everything that uses that variable update at once. That feeling is the point.
6

Bonus — dark mode in 10 lines: Add this below your :root block and add data-theme="dark" to your <html> tag to see a dark mode version of your design:
[data-theme="dark"] { --color-bg: #0a0a0a; --color-text-primary: #f0f0f0; }

✦ Own your code

Can you explain every line?

Before moving on: pick any 5 lines from the code above and say out loud what each one does. Not the general idea — the specific line. If Claude ever gives you code like this, hold it to this standard before you use it. If you cannot explain a line, you cannot debug it.

Key takeaways

A design token is a named value — shared vocabulary between design and code
CSS variables (custom properties) in :root are how tokens work in code
Change one variable → everything that uses it updates instantly
Name tokens by their role, not their value: --color-action-primary not --yellow
Figma Styles (free) and Variables (paid) are the design-side equivalent of CSS variables
This is the foundation of every professional design system — you're thinking at that level now