8 min
Dec 10, 2025·Systems

Design Tokens Are Not Variables

Tokens encode decisions. Variables just store values.

Design Tokens Are Not Variables

Most teams treat design tokens like CSS variables.

That’s the fastest way to strip them of meaning.

Variables Store Values

\`--color-primary: #000\`

That’s a value. It has no intent.

Tokens Encode Decisions

A token answers *why*:

  • Why this color?
  • Why this spacing?
  • Why this motion curve?

    • Tokens represent:

  • Brand decisions
  • Accessibility constraints
  • Interaction principles

    • The Cost of Confusion

    When tokens are treated as variables:

  • Teams bypass them
  • Consistency erodes
  • Systems fragment

    • The token layer becomes optional. That’s failure.

    Proper Token Design

    Good tokens:

  • Are semantic, not visual
  • Resist overrides
  • Map to use-cases, not values

    • Example: \`color.surface.primary\` not \`gray-900\`

    The Outcome

    Tokens scale design. Variables scale chaos.

    Know the difference.