Last updated: Aug 4, 2025, 11:26 AM UTC

Design System Tokens

Status: Complete Token Architecture
Version: 1.0.0
Verified: Cross-platform consistency validated

Executive Summary

Design tokens are the DNA of our visual language—atomic design decisions that ensure perfect consistency across every platform, framework, and device. Our token system creates a single source of truth that scales from a button to an entire application.

Token Architecture Philosophy

Principle Implementation Developer Benefit
Platform Agnostic JSON source → Any format Use in any tech stack
Systematic Scaling Mathematical relationships Predictable sizing
Semantic Naming Purpose over appearance Self-documenting code
Accessibility First WCAG built-in Compliant by default
Performance Optimized CSS custom properties Runtime flexibility

Token Categories

graph TD A[Design Tokens] --> B[Core Tokens] A --> C[Semantic Tokens] A --> D[Component Tokens] B --> E[Colors] B --> F[Typography] B --> G[Spacing] B --> H[Animation] C --> I[Intent] C --> J[State] C --> K[Interactive] D --> L[Buttons] D --> M[Forms] D --> N[Cards] style A fill:#2563EB,color:#fff style B fill:#e1f5fe style C fill:#f3e5f5 style D fill:#e8f5e8

Section 1: Core Color Tokens (800 words)

Color Architecture

Our color system balances brand expression with functional clarity, using a scientifically-derived palette that works across all contexts.

Color token system showing primitive colors, semantic mappings, and theme variations

Comprehensive color token architecture with semantic layering

Primitive Color Tokens

Base Color Scales:

{
  "color": {
    "blue": {
      "50": "#eff6ff",
      "100": "#dbeafe",
      "200": "#bfdbfe",
      "300": "#93c5fd",
      "400": "#60a5fa",
      "500": "#3b82f6",
      "600": "#2563eb",
      "700": "#1d4ed8",
      "800": "#1e40af",
      "900": "#1e3a8a",
      "950": "#172554"
    },
    "gray": {
      "50": "#f9fafb",
      "100": "#f3f4f6",
      "200": "#e5e7eb",
      "300": "#d1d5db",
      "400": "#9ca3af",
      "500": "#6b7280",
      "600": "#4b5563",
      "700": "#374151",
      "800": "#1f2937",
      "900": "#111827",
      "950": "#030712"
    },
    "green": {
      "50": "#f0fdf4",
      "100": "#dcfce7",
      "200": "#bbf7d0",
      "300": "#86efac",
      "400": "#4ade80",
      "500": "#22c55e",
      "600": "#16a34a",
      "700": "#15803d",
      "800": "#166534",
      "900": "#14532d"
    }
  }
}

Primary Blue Scale:

Shade Hex Sample
50 #eff6ff
100 #dbeafe
200 #bfdbfe
300 #93c5fd
400 #60a5fa
500 #3b82f6
600 #2563eb
700 #1d4ed8
800 #1e40af
900 #1e3a8a
950 #172554 

#### 🎯 Semantic Color Tokens

**Functional Mapping**:
```javascript
// Semantic color tokens map to primitives
const semanticColors = {
  // Brand
  "color-brand-primary": "{color.blue.600}",
  "color-brand-secondary": "{color.purple.600}",
  "color-brand-accent": "{color.teal.500}",
  
  // Background
  "color-background-primary": "{color.white}",
  "color-background-secondary": "{color.gray.50}",
  "color-background-tertiary": "{color.gray.100}",
  "color-background-inverse": "{color.gray.900}",
  
  // Text
  "color-text-primary": "{color.gray.900}",
  "color-text-secondary": "{color.gray.600}",
  "color-text-tertiary": "{color.gray.500}",
  "color-text-inverse": "{color.white}",
  "color-text-link": "{color.blue.600}",
  
  // Interactive States
  "color-interactive-default": "{color.blue.600}",
  "color-interactive-hover": "{color.blue.700}",
  "color-interactive-active": "{color.blue.800}",
  "color-interactive-disabled": "{color.gray.300}",
  
  // Feedback
  "color-success": "{color.green.600}",
  "color-warning": "{color.amber.600}",
  "color-error": "{color.red.600}",
  "color-info": "{color.blue.600}"
};

Theme Variations

Dark Mode Tokens:

{
  "color-dark": {
    "background-primary": "{color.gray.900}",
    "background-secondary": "{color.gray.800}",
    "background-tertiary": "{color.gray.700}",
    "text-primary": "{color.gray.50}",
    "text-secondary": "{color.gray.300}",
    "text-tertiary": "{color.gray.400}",
    "border": "{color.gray.700}"
  }
}

Color Application Rules

Contrast Requirements:

Token Combination Min Ratio Use Case
text-primary on background-primary 15:1 Body text
text-secondary on background-primary 7:1 Secondary text
interactive on background 4.5:1 Buttons/Links
text-inverse on brand-primary 4.5:1 White on blue

Section 2: Spacing & Sizing Tokens (700 words)

Mathematical Spacing System

Our spacing system uses a base-8 grid with mathematical scaling to create harmonious, predictable layouts.

Spacing scale showing 4px base unit with multipliers from 0.5x to 16x creating consistent rhythm

Base-8 spacing system with harmonic progression

Spacing Scale

Base Unit System:

// 4px base unit for maximum flexibility
const spacing = {
  "space-0": "0",           // 0px
  "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
  "space-32": "8rem",       // 128px
  "space-40": "10rem",      // 160px
  "space-48": "12rem",      // 192px
  "space-56": "14rem",      // 224px
  "space-64": "16rem"       // 256px
};

Semantic Spacing Tokens

Component-Level Spacing:

{
  "spacing": {
    // Page Layout
    "layout-content-max": "{space-64}",      // 1024px
    "layout-gutter": "{space-6}",            // 24px
    "layout-margin": "{space-8}",            // 32px
    
    // Component Spacing
    "component-padding-xs": "{space-2}",     // 8px
    "component-padding-sm": "{space-3}",     // 12px
    "component-padding-md": "{space-4}",     // 16px
    "component-padding-lg": "{space-6}",     // 24px
    "component-padding-xl": "{space-8}",     // 32px
    
    // Form Elements
    "input-padding-x": "{space-4}",          // 16px
    "input-padding-y": "{space-3}",          // 12px
    "form-gap": "{space-6}",                 // 24px
    
    // Content Spacing
    "text-gap-paragraph": "{space-4}",       // 16px
    "text-gap-section": "{space-12}",        // 48px
    "list-gap": "{space-2}"                  // 8px
  }
}

Sizing Tokens

Component Sizes:

const sizing = {
  // Heights
  "size-input": "44px",        // Touch-friendly
  "size-button": "44px",       // Consistent with input
  "size-button-sm": "36px",    // Compact variant
  "size-button-lg": "52px",    // Prominent CTA
  "size-navbar": "64px",       // Fixed header
  "size-sidebar": "260px",     // Navigation width
  
  // Breakpoints
  "screen-xs": "375px",        // Small phone
  "screen-sm": "640px",        // Large phone
  "screen-md": "768px",        // Tablet
  "screen-lg": "1024px",       // Small desktop
  "screen-xl": "1280px",       // Desktop
  "screen-2xl": "1536px",      // Large desktop
  
  // Container Widths
  "container-xs": "100%",
  "container-sm": "640px",
  "container-md": "768px",
  "container-lg": "1024px",
  "container-xl": "1280px"
};

Section 3: Typography Tokens (700 words)

Type System Architecture

Typography tokens create readable, scannable content with clear hierarchy across all devices.

Typography scale showing font sizes from 12px to 72px with line height and weight variations

Modular typography scale with responsive sizing

Font Family Tokens

{
  "font": {
    "family": {
      "sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
      "mono": "'JetBrains Mono', 'SF Mono', Consolas, monospace",
      "display": "'Inter', sans-serif"
    },
    "weight": {
      "normal": "400",
      "medium": "500", 
      "semibold": "600",
      "bold": "700",
      "extrabold": "800"
    }
  }
}

Type Scale Tokens

Modular Scale (1.25 ratio):

const typeScale = {
  "font-size-xs": "0.75rem",      // 12px
  "font-size-sm": "0.875rem",     // 14px
  "font-size-base": "1rem",       // 16px
  "font-size-lg": "1.125rem",     // 18px
  "font-size-xl": "1.25rem",      // 20px
  "font-size-2xl": "1.5rem",      // 24px
  "font-size-3xl": "1.875rem",    // 30px
  "font-size-4xl": "2.25rem",     // 36px
  "font-size-5xl": "3rem",        // 48px
  "font-size-6xl": "3.75rem",     // 60px
  "font-size-7xl": "4.5rem",      // 72px
  
  // Line Height
  "leading-none": "1",
  "leading-tight": "1.25",
  "leading-snug": "1.375",
  "leading-normal": "1.5",
  "leading-relaxed": "1.625",
  "leading-loose": "2",
  
  // Letter Spacing
  "tracking-tighter": "-0.05em",
  "tracking-tight": "-0.025em",
  "tracking-normal": "0",
  "tracking-wide": "0.025em",
  "tracking-wider": "0.05em",
  "tracking-widest": "0.1em"
};

Semantic Typography Tokens

{
  "text": {
    // Headings
    "heading-1": {
      "size": "{font-size-5xl}",
      "weight": "{font-weight-bold}",
      "line-height": "{leading-tight}",
      "letter-spacing": "{tracking-tight}"
    },
    "heading-2": {
      "size": "{font-size-4xl}",
      "weight": "{font-weight-semibold}",
      "line-height": "{leading-tight}"
    },
    
    // Body Text
    "body-default": {
      "size": "{font-size-base}",
      "weight": "{font-weight-normal}",
      "line-height": "{leading-normal}"
    },
    "body-small": {
      "size": "{font-size-sm}",
      "weight": "{font-weight-normal}",
      "line-height": "{leading-normal}"
    },
    
    // UI Text
    "button": {
      "size": "{font-size-base}",
      "weight": "{font-weight-medium}",
      "letter-spacing": "{tracking-wide}"
    },
    "label": {
      "size": "{font-size-sm}",
      "weight": "{font-weight-medium}"
    }
  }
}

Section 4: Animation Tokens (600 words)

Motion System

Animation tokens ensure consistent, performant motion that enhances rather than distracts from the user experience.

Animation timing curves showing ease-in, ease-out, ease-in-out, and spring easing functions

Standardized timing functions for consistent motion

Duration Tokens

const duration = {
  "duration-instant": "50ms",    // Immediate feedback
  "duration-fast": "150ms",      // Micro-interactions
  "duration-normal": "250ms",    // Standard transitions
  "duration-slow": "350ms",      // Complex animations
  "duration-slower": "500ms",    // Page transitions
  "duration-slowest": "700ms"    // Dramatic effects
};

Easing Tokens

{
  "easing": {
    "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
    "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
    "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
    "ease-spring": "cubic-bezier(0.5, 1.5, 0.5, 1)",
    "ease-bounce": "cubic-bezier(0.68, -0.55, 0.265, 1.55)"
  }
}

Animation Presets

const animations = {
  // Fade
  "fade-in": {
    duration: "{duration-fast}",
    easing: "{easing-ease-out}",
    properties: ["opacity"]
  },
  
  // Scale
  "scale-up": {
    duration: "{duration-normal}",
    easing: "{easing-ease-spring}",
    properties: ["transform"]
  },
  
  // Slide
  "slide-in": {
    duration: "{duration-normal}",
    easing: "{easing-ease-out}",
    properties: ["transform", "opacity"]
  }
};

Section 5: Shadow & Effects Tokens (500 words)

Elevation System

Shadow tokens create consistent depth and hierarchy throughout the interface.

Shadow elevation system showing 5 levels from subtle to dramatic with examples

Five-level elevation system for depth hierarchy

Shadow Scale

{
  "shadow": {
    "shadow-xs": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
    "shadow-sm": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)",
    "shadow-md": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)",
    "shadow-lg": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)",
    "shadow-xl": "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)",
    "shadow-2xl": "0 25px 50px -12px rgb(0 0 0 / 0.25)",
    "shadow-inner": "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)",
    "shadow-none": "0 0 #0000"
  }
}

Effect Tokens

const effects = {
  // Border Radius
  "radius-none": "0",
  "radius-sm": "0.125rem",    // 2px
  "radius-md": "0.375rem",    // 6px
  "radius-lg": "0.5rem",      // 8px
  "radius-xl": "0.75rem",     // 12px
  "radius-2xl": "1rem",       // 16px
  "radius-full": "9999px",
  
  // Opacity
  "opacity-0": "0",
  "opacity-25": "0.25",
  "opacity-50": "0.5",
  "opacity-75": "0.75",
  "opacity-100": "1",
  
  // Blur
  "blur-sm": "4px",
  "blur-md": "8px",
  "blur-lg": "16px",
  "blur-xl": "24px"
};

Section 6: Token Implementation (400 words)

Export Formats

Design tokens are exported in multiple formats for maximum compatibility.

Design Tools

  • Figma variables
  • Sketch library
  • Adobe XD assets
  • Style Dictionary

Development

  • CSS custom properties
  • Sass variables
  • JavaScript/TypeScript
  • JSON/YAML

Build Process

// Token transformation pipeline
const StyleDictionary = require('style-dictionary');

StyleDictionary.extend({
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{
        destination: 'tokens.css',
        format: 'css/variables'
      }]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{
        destination: 'tokens.js',
        format: 'javascript/es6'
      }]
    }
  }
}).buildAllPlatforms();

Conclusion

Design tokens transform design decisions into living code. Our comprehensive token system ensures every pixel, every animation, and every interaction maintains perfect consistency while enabling rapid iteration and platform flexibility.

Next Steps

  1. Review Typography Guide for detailed type implementation
  2. Explore Color Palette for brand color usage
  3. Study Component Library for token application

This token system ensures NudgeCampaign maintains visual consistency across every touchpoint while enabling efficient, scalable development.