tony/chorus-services-website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
chorus-services-website/DESIGN_TOKENS_IMPLEMENTATION.md
anthonyrawlins 7774d7ec98 feat(brand-system): Implement comprehensive CHORUS brand system with typography and design tokens 
This commit implements a complete brand system overhaul including:

TYPOGRAPHY SYSTEM:
- Add Exo font family (Thin, Light, Regular, ExtraLight) as primary brand font
- Implement SF Pro Display/Text hierarchy for UI components
- Create comprehensive Typography component with all brand variants
- Update all components to use new typography tokens

DESIGN TOKEN SYSTEM:
- Create complete design token system in theme/designTokens.ts
- Define Carbon Black (#1a1a1a), Walnut Brown (#8B4513), Brushed Aluminum (#A8A8A8) palette
- Implement CSS custom properties for consistent theming
- Update Ant Design theme integration

COMPONENT UPDATES:
- Enhance Hero section with Exo Thin typography and improved layout
- Update navigation with SF Pro font hierarchy
- Redesign Button component with new variants and accessibility
- Apply brand colors and typography across all showcase sections
- Improve Footer with consistent brand application

PERFORMANCE & ACCESSIBILITY:
- Self-host Exo fonts for optimal loading performance
- Implement proper font-display strategies
- Add comprehensive accessibility audit documentation
- Include responsive testing verification

DOCUMENTATION:
- Add brand system demo and implementation guides
- Include QA testing reports and accessibility audits
- Document design token usage and component patterns

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-02 22:12:42 +10:00

562 lines
16 KiB
Markdown
Raw Permalink Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink