Playbook

Chapter 02 · 5 min read

Design tokens and theming

Tokens are the shared language between design decisions and code. A good model makes change predictable; a poor one merely gives every value a longer name.

Design tokens are a shared contract

A token is a named, reusable design decision. Tokens turn colour, type, spacing, radius, elevation and motion into a system that can be discussed, reviewed and changed without searching through individual screens or stylesheets.

The presentations set the right goals for icare: improve consistency, align Figma with code, reduce accumulated design and technical debt, and give designers and engineers a precise way to describe the target state. The value is not the token file itself. The value is the agreement it creates.

01

Global tokens

Raw scales and foundations with broad reach. They describe what exists, not where it is used.

icare-red-100
02

Alias tokens

Semantic decisions that describe intent and can map to different values by theme.

icare-colour-background-interactive
03

Component tokens

Focused contracts for a component when a shared alias is not specific enough.

icare-button-background-primary

Make inheritance easy to trace

Every component decision should be traceable back to a foundation. The chain below moves from a literal value stored by a global token, to an alias that references that global token, then to an optional component contract. Reach decreases as specificity increases.

  1. Value#fce8e6

    The literal colour value.

  2. Globalicare-red-100

    Stores the reusable palette value.

  3. Aliasicare-colour-background-interactive

    References icare-red-100 in the default theme.

  4. Componenticare-button-background-primary

    Optionally references the shared alias.

Give each tier its own grammar

The namespace is only the ownership prefix: icare-. The token name that follows has its own grammar and should reveal the token's level and purpose. In CSS, --icare-colour-background-interactive combines the required custom-property syntax --, the namespace icare-, and the token name colour-background-interactive.

Agree both the stable namespace and the separate token-name grammar before publishing the library, then apply them consistently in Figma and code.

Globalicare-red-100

Token name: family · scale

Aliasicare-colour-background-interactive-hover

Token name: category · role · context · state

Componenticare-button-background-primary-hover

Token name: component · property · variant · state

Theme the aliases, not the components

Themes should change the value assigned to a stable semantic name. Components continue to ask for icare-colour-background-interactive; the default and dark themes decide which global colour fulfils that role. This keeps component APIs stable and avoids relabelling the library for every brand or mode.

Semantic aliasDefaultDark
icare-colour-background-primaryicare-neutral-000icare-charcoal-700
icare-colour-text-primaryicare-charcoal-700icare-neutral-025
icare-colour-background-interactiveicare-red-100icare-red-300

Lesson learned

Translate the model into code

A production token architecture can turn Sass maps into stable CSS custom properties for text, icons, borders, backgrounds, surfaces and elevation. Global tokens store the palette values. Theme classes map stable aliases to those global tokens, while components consume aliases instead of palette values.

Its button implementation adds one useful refinement: local component variables accept a public override, then fall back to a semantic token. That provides flexibility without disconnecting the component from the system.

:root {
  --icare-red-100: #fce8e6;
  --icare-red-300: #f28b82;
}

.icare-default {
  --icare-colour-background-interactive:
    var(--icare-red-100);
}

.icare-dark {
  --icare-colour-background-interactive:
    var(--icare-red-300);
}

.icare-button {
  --_background: var(
    --icare-button-background-primary,
    var(--icare-colour-background-interactive)
  );
  background: var(--_background);
}

Keep Figma and code deliberately aligned

Figma and code are separate environments, so identical-looking libraries can still drift. Treat SCSS as the production source of truth and use a read-only comparison tool to report differences in scales, colour ramps and semantic mappings. Figma can contain extra ramps or experimental themes, but those explorations should be clearly excluded from production.

  • Choose one production source of truth and document the decision.
  • Use the same icare- namespace and the same token-name grammar in Figma and code.
  • Include the token path, state and theme in engineering specifications, not only the resolved hex value.
  • Automate drift reporting, but keep reconciliation as a human design and engineering decision.
  • Publish token changes with migration guidance and test them across every supported theme.

Use component tokens deliberately

The presentations show component tokens as the most specific tier, but the codebase demonstrates why they should be introduced carefully. Prefer semantic aliases for shared intent. Add a component token only when the component needs a durable override point or a decision that should not affect other components.

Avoid mirroring every CSS property in the token model. Deep inheritance creates names that are hard to remember, obscures where values come from and makes change more expensive. Publish fewer choices, and make each one earn its place.

A token is a promise between design and code. Keep the chain traceable, the names intentional and the themes interchangeable.
Next chapter03 · Documentation practicesWrite for the person copying a component at 4pm on a Friday.