Design Systems & Tokens Guide

Introduction

A design system is a collection of reusable components, guided by clear standards, that can be assembled to build applications. Design tokens are the foundational building blocks—the visual design atoms like colors, spacing, and typography that power your design system.

Why Design Systems Matter:

Ensure consistency across products and platforms
Speed up design and development workflows
Create a shared language between design and engineering
Make updates and rebranding easier
Scale design across teams and products

What Are Design Tokens?

Design tokens are named entities that store visual design attributes. They're platform-agnostic—the same token can generate CSS variables, iOS Swift code, Android XML, and more.

// Token definition (JSON)
{
  "color": {
    "brand": {
      "primary": {
        "value": "#0066ff",
        "type": "color",
        "description": "Primary brand color"
      }
    }
  }
}

/* Generated CSS */
:root {
  --color-brand-primary: #0066ff;
}

/* Usage */
.button {
  background: var(--color-brand-primary);
}

// Generated Swift (iOS)
struct ColorTokens {
  static let colorBrandPrimary = UIColor(hex: "0066ff")
}

Token Categories

Design tokens are typically organized into categories based on their purpose.

Core Token Categories

Category	Purpose	Examples
Color	Brand colors, UI colors, semantic colors	primary, secondary, success, error, background
Spacing	Margins, padding, gaps	xs, sm, md, lg, xl (0.5rem, 1rem, 2rem, etc.)
Typography	Font families, sizes, weights, line heights	font-family-sans, font-size-body, font-weight-bold
Sizing	Width, height, icon sizes	icon-sm, icon-md, button-height
Border	Border widths, styles, radius	border-width-thin, border-radius-sm
Shadow	Box shadows, elevation	shadow-sm, shadow-md, shadow-lg
Motion	Animation durations, easing	duration-fast, duration-normal, easing-standard
Z-index	Layering order	z-dropdown, z-modal, z-tooltip

Naming Conventions

Consistent naming is critical for scalability. Use clear, descriptive names that convey meaning and hierarchy.

Common Naming Patterns

✓ Recommended

Category-Based Naming

/* Pattern: category-property-variant-state */
--color-background-primary
--color-background-secondary
--color-text-primary
--color-text-secondary
--spacing-sm
--spacing-md
--font-size-body
--font-size-heading

✓ Recommended

Scale-Based Naming

/* Numeric or t-shirt scales */
--space-1, --space-2, --space-3
--space-xs, --space-sm, --space-md, --space-lg, --space-xl

/* Color scales */
--gray-50, --gray-100, --gray-200, ... --gray-900
--blue-50, --blue-100, ... --blue-900

✓ Recommended

Semantic Naming

/* Purpose-driven names */
--color-primary
--color-success
--color-warning
--color-error
--button-primary-background
--button-primary-text
--input-border-default
--input-border-focus

✗ Avoid

Non-Descriptive Names

/* Too vague or specific */
--blue         /* Which blue? */
--color1       /* Meaningless */
--big-spacing  /* Imprecise */
--the-blue-on-homepage  /* Too specific */

Naming Best Practices:

Use consistent casing (kebab-case for CSS, camelCase for JavaScript)
Start with the category for better grouping
Use meaningful, not literal names (semantic vs. presentational)
Include variants and states when applicable
Avoid platform-specific or implementation details

Token Hierarchy

Design tokens typically exist in a three-tier hierarchy: Global → Alias → Component.

Level 1: Global Tokens (Primitives)

Raw values with no context. These are your palette.

--blue-50: #eff6ff --blue-500: #3b82f6 --blue-900: #1e3a8a --space-1: 0.25rem --space-4: 1rem

Level 2: Alias Tokens (Semantic)

Context-aware names that reference global tokens.

--color-primary: var(--blue-500) --color-text: var(--blue-900) --spacing-default: var(--space-4)

Level 3: Component Tokens

Component-specific tokens that reference alias or global tokens.

--button-bg: var(--color-primary) --button-text: white --button-padding: var(--spacing-default)

/* Token hierarchy in practice */

/* Level 1: Global/Primitive tokens */
:root {
  --blue-50: #eff6ff;
  --blue-500: #3b82f6;
  --blue-900: #1e3a8a;
  --space-2: 0.5rem;
  --space-4: 1rem;
}

/* Level 2: Alias/Semantic tokens */
:root {
  --color-primary: var(--blue-500);
  --color-text-primary: var(--blue-900);
  --spacing-sm: var(--space-2);
  --spacing-md: var(--space-4);
}

/* Level 3: Component tokens */
.button {
  --button-bg: var(--color-primary);
  --button-text: white;
  --button-padding: var(--spacing-sm) var(--spacing-md);
  
  background: var(--button-bg);
  color: var(--button-text);
  padding: var(--button-padding);
}

/* This creates a maintainable cascade:
   component → semantic → primitive */

Why Use This Hierarchy?

Flexibility: Change a semantic token and all components update
Clarity: Each level has a clear purpose
Maintainability: Updates happen at the right level
Theming: Easy to create theme variants by swapping semantic tokens

Color Tokens

Color tokens are the most common design tokens. Organize them by palette, semantic meaning, and component usage.

Color Scales

Create color scales with consistent steps for flexibility and theming.

blue-50

#eff6ff

blue-100

#dbeafe

blue-200

#bfdbfe

blue-300

#93c5fd

blue-400

#60a5fa

blue-500

#3b82f6

blue-600

#2563eb

blue-700

#1d4ed8

/* Color scale tokens */
:root {
  /* Gray scale */
  --gray-50: #f9fafb;
  --gray-100: #f3f4f6;
  --gray-200: #e5e7eb;
  --gray-300: #d1d5db;
  --gray-400: #9ca3af;
  --gray-500: #6b7280;
  --gray-600: #4b5563;
  --gray-700: #374151;
  --gray-800: #1f2937;
  --gray-900: #111827;
  
  /* Brand color scales */
  --blue-500: #3b82f6;
  --green-500: #10b981;
  --red-500: #ef4444;
  --yellow-500: #f59e0b;
}

Semantic Color Tokens

/* Map scales to semantic meanings */
:root {
  /* Brand colors */
  --color-primary: var(--blue-500);
  --color-primary-hover: var(--blue-600);
  --color-primary-light: var(--blue-100);
  
  /* UI colors */
  --color-background: var(--gray-50);
  --color-surface: white;
  --color-border: var(--gray-200);
  
  /* Text colors */
  --color-text-primary: var(--gray-900);
  --color-text-secondary: var(--gray-600);
  --color-text-tertiary: var(--gray-400);
  
  /* Status colors */
  --color-success: var(--green-500);
  --color-warning: var(--yellow-500);
  --color-error: var(--red-500);
  --color-info: var(--blue-500);
}

Dark Mode Color Tokens

/* Light theme (default) */
:root {
  --color-background: white;
  --color-text: var(--gray-900);
  --color-border: var(--gray-200);
}

/* Dark theme */
:root[data-theme="dark"],
.dark-mode {
  --color-background: var(--gray-900);
  --color-text: var(--gray-50);
  --color-border: var(--gray-700);
}

/* Components automatically adapt */
.card {
  background: var(--color-background);
  color: var(--color-text);
  border: 1px solid var(--color-border);
}

Spacing Tokens

Spacing tokens create rhythm and consistency in your layouts. Use a consistent scale.

Spacing Scale Example

--space-1 (xs)

0.25rem (4px)

--space-2 (sm)

0.5rem (8px)

--space-3 (md)

0.75rem (12px)

--space-4 (lg)

1rem (16px)

--space-6 (xl)

1.5rem (24px)

--space-8 (2xl)

2rem (32px)

--space-12 (3xl)

3rem (48px)

--space-16 (4xl)

4rem (64px)

Common Spacing Systems

/* Option 1: Numeric scale (4px base) */
:root {
  --space-0: 0;
  --space-1: 0.25rem;  /* 4px */
  --space-2: 0.5rem;   /* 8px */
  --space-3: 0.75rem;  /* 12px */
  --space-4: 1rem;     /* 16px */
  --space-5: 1.25rem;  /* 20px */
  --space-6: 1.5rem;   /* 24px */
  --space-8: 2rem;     /* 32px */
  --space-10: 2.5rem;  /* 40px */
  --space-12: 3rem;    /* 48px */
  --space-16: 4rem;    /* 64px */
  --space-20: 5rem;    /* 80px */
  --space-24: 6rem;    /* 96px */
}

/* Option 2: T-shirt sizes */
:root {
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 2rem;
  --space-xl: 4rem;
  --space-2xl: 8rem;
}

/* Option 3: Semantic names */
:root {
  --spacing-tight: 0.5rem;
  --spacing-normal: 1rem;
  --spacing-relaxed: 1.5rem;
  --spacing-loose: 2rem;
}

Using Spacing Tokens

/* In components */
.card {
  padding: var(--space-4);
  margin-bottom: var(--space-6);
  gap: var(--space-3);
}

.button {
  padding: var(--space-2) var(--space-4);
}

.section {
  padding-top: var(--space-12);
  padding-bottom: var(--space-12);
}

/* Spacing utilities */
.p-4 { padding: var(--space-4); }
.m-4 { margin: var(--space-4); }
.gap-4 { gap: var(--space-4); }