External Brain

Design Tokens

4 min read

Design Tokens

Design tokens are named design decisions that store the small reusable values of an interface.

They turn raw values into shared references that can be used across design files, code, documentation, and Design System components.

Core Idea

A token gives meaning to a value.

Raw valueTokenMeaning
#3E4FC8color-background-primaryprimary background color
16pxspacing-mdmedium spacing value
700font-heading-weightheading font weight
8pxradius-smallsmall corner radius

The value can change, but the decision remains understandable because the name explains the role.

Why Tokens Matter

Design tokens help with:

  • consistency
  • single source of truth
  • developer handoff
  • theme changes
  • accessibility adjustments
  • system maintenance
  • faster updates across many components

Without tokens, the same decision gets copied into many places. With tokens, the decision has one controlled reference.

What Tokens Can Control

Tokens can describe:

  • color
  • typography
  • spacing
  • sizing
  • radius
  • shadow
  • elevation
  • motion
  • opacity
  • border
  • layout
  • breakpoint
  • z-index

They are not limited to colors.

Complete Token System

A complete token system is not only a list of values.

It connects raw values, semantic meaning, component usage, states, themes, and governance.

raw value -> primitive token -> semantic token -> component token -> product UI

The system should answer five questions:

QuestionToken responsibility
What is the raw value?primitive tokens
What does the value mean?semantic tokens
Where is the value used?component tokens
When does the value change?state, mode, and theme tokens
Who can change the value?governance and documentation

Token Levels

LevelQuestionExampleRole
primitive / globalwhat is the value?color-blue-500, font-size-100, spacing-4basic named building block
semantic / aliaswhat does it mean?color-text-primary, font-size-body-md, spacing-content-gapdesign decision with interface meaning
component / specificwhere is it used?button-background-primary, input-border-error, card-padding-defaultcontext-specific component decision

Primitive tokens describe what the value is.

Semantic tokens describe what the value does.

Component tokens describe where the value is used.

State, mode, and theme tokens are dimensions that can modify semantic or component tokens.

Examples:

  • button-background-primary-hover
  • button-background-primary-disabled
  • color-background-primary-light
  • color-background-primary-dark
  • color-text-error

Token Categories

CategoryWhat It DefinesExample Tokens
colorbrand, surface, text, border, feedback, focuscolor-brand-500, color-text-primary, color-border-subtle, color-feedback-error
typographyfont family, size, weight, line-height, letter spacingfont-family-body, font-size-body-md, font-weight-heading, line-height-reading, letter-spacing-label
spacinggaps, padding, margins, stack rhythmspacing-xs, spacing-md, spacing-content-gap, spacing-section
sizingicon size, control height, target size, fixed dimensionssize-icon-sm, size-control-md, size-touch-target
radiuscorner shape and component softnessradius-sm, radius-card, radius-pill
borderborder width, style, and semantic border colorborder-width-default, border-color-focus, border-color-error
shadow / elevationdepth, layering, floating surfacesshadow-card, shadow-popover, elevation-modal
motionduration, easing, delay, transition behaviorduration-fast, duration-standard, easing-enter, easing-exit
opacitydisabled states, overlays, scrims, subtle surfacesopacity-disabled, opacity-overlay, opacity-muted
layoutcontainers, grids, breakpoints, z-indexcontainer-width-lg, grid-gap-default, breakpoint-md, z-index-modal

Typography tokens are especially useful because text decisions are repeated across headings, body copy, labels, buttons, inputs, navigation, and error messages.

Good typography token groups usually include:

  • font family
  • font size
  • font weight
  • line height
  • letter spacing
  • paragraph spacing
  • text case when it is part of the system

Example Of Token Architecture

#3E4FC8
  -> color-blue-500
    -> color-background-primary
      -> button-background-primary
 
16px
  -> font-size-100
    -> font-size-body-md
      -> input-label-font-size

This structure makes change easier.

If the brand blue changes, the primitive value can change. If only the button needs a different color, the component token can change without breaking every other primary background.

If the body text scale changes, the semantic typography token can change. If only input labels need a smaller size, the component token can change without changing body copy everywhere.

Naming Pattern

Useful token names often follow this structure:

object category property modifier

Examples:

  • color-text-primary
  • button-background-secondary-hover
  • font-size-sm
  • radius-small
  • input-border-error

Naming Rules

Good token names should:

  • describe responsibility, not taste
  • avoid vague names like nice-blue
  • avoid raw-value names at semantic levels
  • use only the levels needed
  • keep names understandable
  • separate category and property correctly

For example:

Weak nameBetter nameWhy
blue-buttonbutton-background-primarydescribes use, not only appearance
big-textfont-size-lguses a scale
red-errorcolor-text-errorexplains semantic role

Design Tokens And Accessibility

Tokens are useful for Accessibility because accessible decisions can be built into the system.

Examples:

  • text colors can be paired with background tokens that pass contrast
  • focus-ring tokens can preserve visibility
  • spacing and target-size tokens can support touch accessibility
  • typography tokens can support readable scales

If accessibility is in the token layer, it becomes easier to preserve across the interface.

Design Tokens And Atomic Design

In Atomic Design, tokens sit before atoms.

They shape the smallest visible interface parts, such as buttons, labels, icons, fields, and headings.

Graph View

Backlinks