# CHORUS Services Design Tokens Implementation Guide

## Overview

This document provides comprehensive implementation guidelines for the CHORUS Services design tokens system, ensuring consistent application of the brand system across all components while maintaining excellent user experience.

## 1. Color System Design Tokens

### 1.1 Primary Brand Colors

```css
:root {
  /* Primary Brand Palette */
  --color-carbon-black: #000000;
  --color-walnut-brown: #8B4513;
  --color-brushed-aluminum: #C0C0C0;
  --color-natural-paper: #F5F5DC;
  
  /* System Colors */
  --color-orchestration-blue: #007AFF;
  --color-success-green: #34C759;
  --color-warning-amber: #FF9500;
  --color-error-red: #FF3B30;
  
  /* Neutral Grays */
  --color-gray-50: #F9FAFB;
  --color-gray-100: #F3F4F6;
  --color-gray-200: #E5E7EB;
  --color-gray-300: #D1D5DB;
  --color-gray-400: #9CA3AF;
  --color-gray-500: #6B7280;
  --color-gray-600: #4B5563;
  --color-gray-700: #374151;
  --color-gray-800: #1F2937;
  --color-gray-900: #111827;
  --color-gray-950: #030712;
}
```

### 1.2 Semantic Color Tokens

```css
:root {
  /* Background Hierarchy */
  --bg-primary: var(--color-carbon-black);
  --bg-secondary: #0A0A0A;
  --bg-tertiary: #1A1A1A;
  --bg-quaternary: #2A2A2A;
  --bg-elevated: #1F1F1F;
  --bg-overlay: rgba(0, 0, 0, 0.8);
  
  /* Text Hierarchy */
  --text-primary: #FFFFFF;
  --text-secondary: #E5E5E5;
  --text-tertiary: #A8A8A8;
  --text-quaternary: #6D6D6D;
  --text-disabled: #484848;
  --text-accent: var(--color-walnut-brown);
  --text-link: var(--color-orchestration-blue);
  
  /* Border Colors */
  --border-primary: rgba(255, 255, 255, 0.1);
  --border-secondary: rgba(255, 255, 255, 0.05);
  --border-focus: var(--color-orchestration-blue);
  --border-error: var(--color-error-red);
  --border-success: var(--color-success-green);
  
  /* Interactive States */
  --interactive-primary: var(--color-orchestration-blue);
  --interactive-primary-hover: #0056D6;
  --interactive-primary-active: #004BB5;
  --interactive-secondary: var(--color-walnut-brown);
  --interactive-secondary-hover: #A0522D;
  --interactive-disabled: var(--color-gray-600);
  
  /* Status Colors */
  --status-success: var(--color-success-green);
  --status-warning: var(--color-warning-amber);
  --status-error: var(--color-error-red);
  --status-info: var(--color-orchestration-blue);
}
```

### 1.3 Alpha Transparency Tokens

```css
:root {
  /* Background Alphas */
  --bg-alpha-10: rgba(255, 255, 255, 0.1);
  --bg-alpha-05: rgba(255, 255, 255, 0.05);
  --bg-alpha-02: rgba(255, 255, 255, 0.02);
  
  /* Interactive Alphas */
  --interactive-alpha-hover: rgba(0, 122, 255, 0.1);
  --interactive-alpha-active: rgba(0, 122, 255, 0.2);
  --interactive-alpha-focus: rgba(0, 122, 255, 0.3);
  
  /* Shadow Alphas */
  --shadow-alpha-light: rgba(0, 0, 0, 0.1);
  --shadow-alpha-medium: rgba(0, 0, 0, 0.2);
  --shadow-alpha-heavy: rgba(0, 0, 0, 0.4);
}
```

## 2. Typography System Design Tokens

### 2.1 Font Family Tokens

```css
:root {
  /* Primary Font Families */
  --font-hero: 'Exo', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-display: 'SF Pro Display', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-text: 'SF Pro Text', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-body: 'Roboto', -apple-system, BlinkMacSystemFont, sans-serif;
  --font-mono: 'SF Mono', 'Roboto Mono', 'Consolas', monospace;
  
  /* Font Weight Tokens */
  --font-weight-thin: 100;
  --font-weight-light: 300;
  --font-weight-regular: 400;
  --font-weight-medium: 500;
  --font-weight-semibold: 600;
  --font-weight-bold: 700;
  --font-weight-heavy: 800;
}
```

### 2.2 Typography Scale Tokens

```css
:root {
  /* Font Size Scale */
  --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 */
  --font-size-8xl: 6rem;      /* 96px */
  
  /* Line Height Tokens */
  --line-height-none: 1;
  --line-height-tight: 1.1;
  --line-height-snug: 1.2;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.6;
  --line-height-loose: 2;
  
  /* Letter Spacing */
  --letter-spacing-tight: -0.025em;
  --letter-spacing-normal: 0;
  --letter-spacing-wide: 0.025em;
  --letter-spacing-wider: 0.05em;
}
```

### 2.3 Typography Component Tokens

```css
:root {
  /* Hero Typography */
  --hero-font-family: var(--font-hero);
  --hero-font-weight: var(--font-weight-thin);
  --hero-font-size: clamp(3rem, 6vw, 6rem);
  --hero-line-height: var(--line-height-tight);
  --hero-letter-spacing: var(--letter-spacing-tight);
  
  /* Heading Typography */
  --heading-h1-size: var(--font-size-5xl);
  --heading-h2-size: var(--font-size-4xl);
  --heading-h3-size: var(--font-size-3xl);
  --heading-h4-size: var(--font-size-2xl);
  --heading-h5-size: var(--font-size-xl);
  --heading-h6-size: var(--font-size-lg);
  
  /* Body Typography */
  --body-large-size: var(--font-size-lg);
  --body-base-size: var(--font-size-base);
  --body-small-size: var(--font-size-sm);
  
  /* Interface Typography */
  --ui-button-size: var(--font-size-base);
  --ui-label-size: var(--font-size-sm);
  --ui-caption-size: var(--font-size-xs);
}
```

## 3. Spacing System Design Tokens

### 3.1 Base Spacing Scale

```css
:root {
  /* Base spacing unit: 4px */
  --space-0: 0;
  --space-px: 1px;
  --space-0-5: 0.125rem;  /* 2px */
  --space-1: 0.25rem;     /* 4px */
  --space-1-5: 0.375rem;  /* 6px */
  --space-2: 0.5rem;      /* 8px */
  --space-2-5: 0.625rem;  /* 10px */
  --space-3: 0.75rem;     /* 12px */
  --space-3-5: 0.875rem;  /* 14px */
  --space-4: 1rem;        /* 16px */
  --space-5: 1.25rem;     /* 20px */
  --space-6: 1.5rem;      /* 24px */
  --space-7: 1.75rem;     /* 28px */
  --space-8: 2rem;        /* 32px */
  --space-9: 2.25rem;     /* 36px */
  --space-10: 2.5rem;     /* 40px */
  --space-11: 2.75rem;    /* 44px */
  --space-12: 3rem;       /* 48px */
  --space-14: 3.5rem;     /* 56px */
  --space-16: 4rem;       /* 64px */
  --space-20: 5rem;       /* 80px */
  --space-24: 6rem;       /* 96px */
  --space-28: 7rem;       /* 112px */
  --space-32: 8rem;       /* 128px */
  --space-36: 9rem;       /* 144px */
  --space-40: 10rem;      /* 160px */
  --space-44: 11rem;      /* 176px */
  --space-48: 12rem;      /* 192px */
  --space-52: 13rem;      /* 208px */
  --space-56: 14rem;      /* 224px */
  --space-60: 15rem;      /* 240px */
  --space-64: 16rem;      /* 256px */
  --space-72: 18rem;      /* 288px */
  --space-80: 20rem;      /* 320px */
  --space-96: 24rem;      /* 384px */
}
```

### 3.2 Semantic Spacing Tokens

```css
:root {
  /* Component Spacing */
  --spacing-component-xs: var(--space-2);
  --spacing-component-sm: var(--space-4);
  --spacing-component-md: var(--space-6);
  --spacing-component-lg: var(--space-8);
  --spacing-component-xl: var(--space-12);
  
  /* Layout Spacing */
  --spacing-layout-xs: var(--space-4);
  --spacing-layout-sm: var(--space-8);
  --spacing-layout-md: var(--space-16);
  --spacing-layout-lg: var(--space-24);
  --spacing-layout-xl: var(--space-32);
  
  /* Section Spacing */
  --spacing-section-xs: var(--space-16);
  --spacing-section-sm: var(--space-24);
  --spacing-section-md: var(--space-32);
  --spacing-section-lg: var(--space-48);
  --spacing-section-xl: var(--space-64);
}
```

## 4. Border Radius Design Tokens

```css
:root {
  /* Border Radius Scale */
  --radius-none: 0;
  --radius-sm: 0.125rem;   /* 2px */
  --radius-base: 0.25rem;  /* 4px */
  --radius-md: 0.375rem;   /* 6px */
  --radius-lg: 0.5rem;     /* 8px */
  --radius-xl: 0.75rem;    /* 12px */
  --radius-2xl: 1rem;      /* 16px */
  --radius-3xl: 1.5rem;    /* 24px */
  --radius-full: 9999px;
  
  /* Component Radius */
  --radius-button: var(--radius-lg);
  --radius-card: var(--radius-xl);
  --radius-input: var(--radius-lg);
  --radius-modal: var(--radius-2xl);
  --radius-avatar: var(--radius-full);
}
```

## 5. Shadow Design Tokens

```css
:root {
  /* Shadow Scale */
  --shadow-xs: 0 1px 2px 0 var(--shadow-alpha-light);
  --shadow-sm: 0 1px 3px 0 var(--shadow-alpha-light), 0 1px 2px -1px var(--shadow-alpha-light);
  --shadow-base: 0 1px 3px 0 var(--shadow-alpha-light), 0 1px 2px -1px var(--shadow-alpha-light);
  --shadow-md: 0 4px 6px -1px var(--shadow-alpha-light), 0 2px 4px -2px var(--shadow-alpha-light);
  --shadow-lg: 0 10px 15px -3px var(--shadow-alpha-light), 0 4px 6px -4px var(--shadow-alpha-light);
  --shadow-xl: 0 20px 25px -5px var(--shadow-alpha-light), 0 8px 10px -6px var(--shadow-alpha-light);
  --shadow-2xl: 0 25px 50px -12px var(--shadow-alpha-medium);
  --shadow-inner: inset 0 2px 4px 0 var(--shadow-alpha-light);
  
  /* Elevation Shadows for Dark Theme */
  --shadow-elevation-1: 0 2px 8px var(--shadow-alpha-medium);
  --shadow-elevation-2: 0 4px 16px var(--shadow-alpha-medium);
  --shadow-elevation-3: 0 8px 32px var(--shadow-alpha-heavy);
  --shadow-elevation-4: 0 16px 64px var(--shadow-alpha-heavy);
  
  /* Interactive Shadows */
  --shadow-button-hover: 0 4px 12px var(--interactive-alpha-focus);
  --shadow-button-active: 0 2px 4px var(--interactive-alpha-active);
  --shadow-focus-ring: 0 0 0 3px var(--interactive-alpha-focus);
}
```

## 6. Animation and Transition Tokens

```css
:root {
  /* Duration Tokens */
  --duration-instant: 0ms;
  --duration-fast: 150ms;
  --duration-normal: 250ms;
  --duration-slow: 350ms;
  --duration-slower: 500ms;
  
  /* Easing Functions */
  --ease-linear: linear;
  --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-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
  
  /* Component Transitions */
  --transition-button: all var(--duration-fast) var(--ease-out);
  --transition-hover: all var(--duration-normal) var(--ease-out);
  --transition-focus: all var(--duration-fast) var(--ease-out);
  --transition-modal: all var(--duration-normal) var(--ease-in-out);
  --transition-slide: transform var(--duration-normal) var(--ease-out);
}
```

## 7. Z-Index System Tokens

```css
:root {
  /* Z-Index Scale */
  --z-auto: auto;
  --z-0: 0;
  --z-10: 10;
  --z-20: 20;
  --z-30: 30;
  --z-40: 40;
  --z-50: 50;
  
  /* Component Z-Index */
  --z-dropdown: 1000;
  --z-sticky: 1020;
  --z-fixed: 1030;
  --z-modal-backdrop: 1040;
  --z-offcanvas: 1050;
  --z-modal: 1060;
  --z-popover: 1070;
  --z-tooltip: 1080;
  --z-toast: 1090;
}
```

## 8. Responsive Breakpoint Tokens

```css
:root {
  /* Breakpoint Values */
  --breakpoint-xs: 320px;
  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
  --breakpoint-xl: 1280px;
  --breakpoint-2xl: 1536px;
}

/* Media Query Mixins */
@custom-media --xs-up (min-width: 320px);
@custom-media --sm-up (min-width: 640px);
@custom-media --md-up (min-width: 768px);
@custom-media --lg-up (min-width: 1024px);
@custom-media --xl-up (min-width: 1280px);
@custom-media --2xl-up (min-width: 1536px);

@custom-media --xs-down (max-width: 639px);
@custom-media --sm-down (max-width: 767px);
@custom-media --md-down (max-width: 1023px);
@custom-media --lg-down (max-width: 1279px);
@custom-media --xl-down (max-width: 1535px);
```

## 9. Component-Specific Tokens

### 9.1 Button Tokens

```css
:root {
  /* Button Sizing */
  --button-height-sm: 2rem;      /* 32px */
  --button-height-md: 2.5rem;    /* 40px */
  --button-height-lg: 3rem;      /* 48px */
  --button-height-xl: 3.5rem;    /* 56px */
  
  --button-padding-x-sm: var(--space-3);
  --button-padding-x-md: var(--space-4);
  --button-padding-x-lg: var(--space-6);
  --button-padding-x-xl: var(--space-8);
  
  /* Button Typography */
  --button-font-size-sm: var(--font-size-sm);
  --button-font-size-md: var(--font-size-base);
  --button-font-size-lg: var(--font-size-lg);
  --button-font-weight: var(--font-weight-semibold);
  
  /* Button Colors */
  --button-primary-bg: var(--interactive-primary);
  --button-primary-bg-hover: var(--interactive-primary-hover);
  --button-primary-text: var(--text-primary);
  
  --button-secondary-bg: transparent;
  --button-secondary-border: var(--interactive-secondary);
  --button-secondary-text: var(--interactive-secondary);
  --button-secondary-bg-hover: var(--interactive-secondary);
  --button-secondary-text-hover: var(--text-primary);
}
```

### 9.2 Form Input Tokens

```css
:root {
  /* Input Sizing */
  --input-height-sm: 2rem;
  --input-height-md: 2.5rem;
  --input-height-lg: 3rem;
  
  --input-padding-x: var(--space-3);
  --input-padding-y: var(--space-2);
  
  /* Input Colors */
  --input-bg: var(--bg-tertiary);
  --input-border: var(--border-primary);
  --input-border-focus: var(--border-focus);
  --input-text: var(--text-primary);
  --input-placeholder: var(--text-quaternary);
  
  /* Input States */
  --input-border-error: var(--border-error);
  --input-border-success: var(--border-success);
}
```

### 9.3 Card Tokens

```css
:root {
  /* Card Styling */
  --card-bg: var(--bg-secondary);
  --card-border: var(--border-primary);
  --card-radius: var(--radius-card);
  --card-shadow: var(--shadow-elevation-1);
  --card-shadow-hover: var(--shadow-elevation-2);
  
  --card-padding-sm: var(--space-4);
  --card-padding-md: var(--space-6);
  --card-padding-lg: var(--space-8);
  
  /* Card Header */
  --card-header-border: var(--border-secondary);
  --card-header-padding: var(--space-4);
}
```

## 10. Usage Guidelines

### 10.1 Token Naming Conventions

- **Primitive tokens**: `--color-blue-500`, `--space-4`, `--font-size-lg`
- **Semantic tokens**: `--text-primary`, `--bg-secondary`, `--interactive-hover`
- **Component tokens**: `--button-height-md`, `--card-padding-lg`

### 10.2 Token Application Examples

```css
/* Using primitive tokens */
.custom-element {
  color: var(--color-orchestration-blue);
  margin: var(--space-4);
  font-size: var(--font-size-lg);
}

/* Using semantic tokens (preferred) */
.text-content {
  color: var(--text-primary);
  background: var(--bg-secondary);
  border: 1px solid var(--border-primary);
}

/* Using component tokens */
.custom-button {
  height: var(--button-height-md);
  padding: 0 var(--button-padding-x-md);
  font-size: var(--button-font-size-md);
  font-weight: var(--button-font-weight);
}
```

### 10.3 Dark Mode Considerations

All tokens are optimized for dark mode by default. When implementing components:

1. Always use semantic tokens for colors
2. Test contrast ratios with tools like WebAIM
3. Ensure focus states are clearly visible
4. Verify readability across all typography scales

### 10.4 Responsive Implementation

```css
/* Responsive spacing example */
.section {
  padding: var(--spacing-section-sm);
}

@media (--md-up) {
  .section {
    padding: var(--spacing-section-md);
  }
}

@media (--xl-up) {
  .section {
    padding: var(--spacing-section-lg);
  }
}
```

## 11. Validation and Testing

### 11.1 Token Validation Checklist

- [ ] All color tokens meet WCAG contrast requirements
- [ ] Typography tokens scale properly across breakpoints
- [ ] Spacing tokens create consistent visual rhythm
- [ ] Animation tokens respect reduced motion preferences
- [ ] Z-index tokens prevent stacking conflicts

### 11.2 Automated Testing

Consider implementing automated tests for:
- Color contrast validation
- Typography scale consistency
- Spacing rhythm verification
- Component token completeness

This design token system provides the foundation for consistent, accessible, and maintainable styling across the CHORUS Services platform while ensuring excellent user experience at scale.