Brand Tokens

The atomic values that define a design system.

Design tokens are the single source of truth for visual decisions—named entities that store colors, typography, spacing, and other values. Rather than hardcoding #0052A5 throughout a codebase, teams reference color-brand-primary. Tokens enable consistency, theming, and efficient global updates.

What Tokens Represent

Color Tokens

All color values in the system:

color-brand-primary: #0052A5
color-brand-secondary: #4A90D9
color-text-primary: #1A1A1A
color-text-secondary: #666666
color-background-default: #FFFFFF
color-background-surface: #F5F5F5
color-border-default: #E0E0E0
color-status-success: #28A745
color-status-error: #DC3545
color-status-warning: #FFC107

Typography Tokens

Font decisions:

font-family-primary: 'Inter', sans-serif
font-family-secondary: 'Playfair Display', serif
font-family-mono: 'JetBrains Mono', monospace

font-size-xs: 12px
font-size-sm: 14px
font-size-md: 16px
font-size-lg: 20px
font-size-xl: 24px
font-size-2xl: 32px

font-weight-regular: 400
font-weight-medium: 500
font-weight-bold: 700

line-height-tight: 1.25
line-height-normal: 1.5
line-height-relaxed: 1.75

Spacing Tokens

Consistent intervals:

spacing-xs: 4px
spacing-sm: 8px
spacing-md: 16px
spacing-lg: 24px
spacing-xl: 32px
spacing-2xl: 48px
spacing-3xl: 64px

Other Tokens

Additional visual properties:

// Border radius
radius-sm: 2px
radius-md: 4px
radius-lg: 8px
radius-full: 9999px

// Shadows
shadow-sm: 0 1px 2px rgba(0,0,0,0.05)
shadow-md: 0 4px 6px rgba(0,0,0,0.1)
shadow-lg: 0 10px 15px rgba(0,0,0,0.1)

// Animation
duration-fast: 150ms
duration-normal: 300ms
duration-slow: 500ms
easing-default: cubic-bezier(0.4, 0, 0.2, 1)

// Z-index
z-dropdown: 100
z-modal: 200
z-tooltip: 300

Token Architecture

Primitive Tokens (Global)

Raw values without semantic meaning:

Primary Scale

50
100
200
300
400
500
600
700
800
900
50100200300400500600700800900

Neutral Scale

50
100
200
300
400
500
600
700
800
900
50100200300400500600700800900
blue-500: #0052A5
blue-600: #003D7A
gray-100: #F5F5F5
gray-900: #1A1A1A

These are the palette—the complete set of available values.

Semantic Tokens (Alias)

Meaningful names referencing primitives:

color-brand-primary: {blue-500}
color-text-primary: {gray-900}
color-background-surface: {gray-100}

Semantic tokens add meaning. "Primary brand color" is clearer than "blue-500."

Component Tokens (Specific)

Component-level decisions:

button-primary-background: {color-brand-primary}
button-primary-text: {color-text-inverse}
button-border-radius: {radius-md}
button-padding-horizontal: {spacing-md}

Component tokens enable per-component theming and overrides.

The Hierarchy

Primitive → Semantic → Component

blue-500 → color-brand-primary → button-primary-background

Changes at primitive level cascade through semantic and component tokens. Changes at semantic level affect all components using that token. Component tokens allow targeted adjustments.

Token Naming

Naming Patterns

Category-Property-Variant-State:

color-text-primary
color-background-surface-hover
spacing-padding-large

Component-Property-Variant-State:

button-background-primary
button-background-primary-hover
input-border-error

Naming Principles

Semantic over visual:

  • Good: color-text-primary
  • Avoid: color-dark-gray

Consistent structure:

  • All tokens follow same pattern
  • Predictable from naming alone

Clear hierarchy:

  • More specific = longer name
  • Base tokens are short

Avoid abbreviations:

  • background not bg
  • primary not pri
  • Clarity over brevity

Token Formats

JSON

Human-readable, widely supported:

{
  "color": {
    "brand": {
      "primary": {
        "value": "#0052A5",
        "type": "color"
      }
    }
  }
}

YAML

More readable for large files:

color:
  brand:
    primary:
      value: "#0052A5"
      type: color

Design Tool Formats

Native formats for Figma, Sketch, etc.

Output Formats

Transformed for consumption:

CSS Custom Properties:

:root {
  --color-brand-primary: #0052A5;
  --spacing-md: 16px;
}

SCSS Variables:

$color-brand-primary: #0052A5;
$spacing-md: 16px;

JavaScript/TypeScript:

export const colorBrandPrimary = '#0052A5';
export const spacingMd = '16px';

iOS/Android: Platform-specific formats for native apps.

Token Tools

Style Dictionary

Industry-standard token transformer:

  • Define tokens once in JSON/YAML
  • Output to multiple formats
  • Custom transforms and templates
  • Platform-specific builds

Tokens Studio (Figma)

Figma plugin for token management:

  • Visual token editing
  • Sync with JSON files
  • GitHub integration
  • Theme switching

Custom Solutions

Build-your-own approaches:

  • Node.js scripts
  • Build tool plugins
  • CI/CD integration

Theming with Tokens

Theme Structure

Multiple themes sharing token names:

// Light theme
{
  "color-background-default": "#FFFFFF",
  "color-text-primary": "#1A1A1A"
}

// Dark theme
{
  "color-background-default": "#1A1A1A",
  "color-text-primary": "#FFFFFF"
}

Same semantic names, different values.

Theme Switching

CSS approach:

:root {
  --color-background: #FFFFFF;
  --color-text: #1A1A1A;
}

[data-theme="dark"] {
  --color-background: #1A1A1A;
  --color-text: #FFFFFF;
}

Toggle by changing data-theme attribute.

Multi-Brand Theming

Same component library, different brand expressions:

// Brand A
{
  "color-brand-primary": "#0052A5",
  "font-family-primary": "Inter"
}

// Brand B
{
  "color-brand-primary": "#E63946",
  "font-family-primary": "Poppins"
}

Components built with tokens automatically adapt.

Token Governance

Source of Truth

Define where tokens live:

  • Single JSON/YAML file
  • Figma with Tokens Studio
  • Dedicated token management tool
  • Database with API

Avoid duplicate definitions.

Change Process

How tokens are updated:

  1. Proposal (what and why)
  2. Review (design + engineering)
  3. Testing (impact assessment)
  4. Release (versioned update)
  5. Communication (changelog)

Versioning

Token packages follow semantic versioning:

  • Major: Breaking changes (renamed or removed tokens)
  • Minor: New tokens, backwards compatible
  • Patch: Value adjustments

Documentation

Token documentation includes:

  • Complete token list with values
  • Visual examples
  • Usage guidelines
  • Theme variations
  • Migration guides for breaking changes

Common Patterns

Color Token Set

// Brand
color-brand-primary
color-brand-secondary
color-brand-accent

// Text
color-text-primary
color-text-secondary
color-text-disabled
color-text-inverse
color-text-link

// Background
color-background-default
color-background-surface
color-background-elevated
color-background-overlay

// Border
color-border-default
color-border-strong
color-border-focus

// Status
color-status-success
color-status-warning
color-status-error
color-status-info

Spacing Scale

Common approach—base unit with multipliers:

Base: 4px

spacing-1: 4px   (1×)
spacing-2: 8px   (2×)
spacing-3: 12px  (3×)
spacing-4: 16px  (4×)
spacing-5: 20px  (5×)
spacing-6: 24px  (6×)
spacing-8: 32px  (8×)
spacing-10: 40px (10×)
spacing-12: 48px (12×)
spacing-16: 64px (16×)

Related