chorus-services-website/DESIGN_TOKENS_IMPLEMENTATION.md

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

: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

: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

: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

: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

: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

: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

: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

: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

: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

: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

: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

: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

: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

: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

: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

: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

/* 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

/* 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.