thrillwiki_django_no_react/memory-bank/design-system/design-tokens.md

ThrillWiki Design System - Design Tokens

Overview

Comprehensive design token system for ThrillWiki's frontend redesign, establishing consistent visual language across all components and templates.

Color System

Brand Colors

:root {
  /* Primary Brand Colors */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-200: #bfdbfe;
  --color-primary-300: #93c5fd;
  --color-primary-400: #60a5fa;
  --color-primary-500: #3b82f6;  /* Main brand blue */
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-primary-800: #1e40af;
  --color-primary-900: #1e3a8a;
  --color-primary-950: #172554;

  /* Secondary Colors - Complementary Orange */
  --color-secondary-50: #fff7ed;
  --color-secondary-100: #ffedd5;
  --color-secondary-200: #fed7aa;
  --color-secondary-300: #fdba74;
  --color-secondary-400: #fb923c;
  --color-secondary-500: #f97316;  /* Main accent orange */
  --color-secondary-600: #ea580c;
  --color-secondary-700: #c2410c;
  --color-secondary-800: #9a3412;
  --color-secondary-900: #7c2d12;
  --color-secondary-950: #431407;
}

Semantic Colors

:root {
  /* Success Colors */
  --color-success-50: #f0fdf4;
  --color-success-100: #dcfce7;
  --color-success-200: #bbf7d0;
  --color-success-300: #86efac;
  --color-success-400: #4ade80;
  --color-success-500: #22c55e;
  --color-success-600: #16a34a;
  --color-success-700: #15803d;
  --color-success-800: #166534;
  --color-success-900: #14532d;

  /* Warning Colors */
  --color-warning-50: #fffbeb;
  --color-warning-100: #fef3c7;
  --color-warning-200: #fde68a;
  --color-warning-300: #fcd34d;
  --color-warning-400: #fbbf24;
  --color-warning-500: #f59e0b;
  --color-warning-600: #d97706;
  --color-warning-700: #b45309;
  --color-warning-800: #92400e;
  --color-warning-900: #78350f;

  /* Error Colors */
  --color-error-50: #fef2f2;
  --color-error-100: #fee2e2;
  --color-error-200: #fecaca;
  --color-error-300: #fca5a5;
  --color-error-400: #f87171;
  --color-error-500: #ef4444;
  --color-error-600: #dc2626;
  --color-error-700: #b91c1c;
  --color-error-800: #991b1b;
  --color-error-900: #7f1d1d;

  /* Info Colors */
  --color-info-50: #f0f9ff;
  --color-info-100: #e0f2fe;
  --color-info-200: #bae6fd;
  --color-info-300: #7dd3fc;
  --color-info-400: #38bdf8;
  --color-info-500: #0ea5e9;
  --color-info-600: #0284c7;
  --color-info-700: #0369a1;
  --color-info-800: #075985;
  --color-info-900: #0c4a6e;
}

Neutral Colors (Light/Dark Mode)

:root {
  /* Light Mode Neutrals */
  --color-neutral-50: #f8fafc;
  --color-neutral-100: #f1f5f9;
  --color-neutral-200: #e2e8f0;
  --color-neutral-300: #cbd5e1;
  --color-neutral-400: #94a3b8;
  --color-neutral-500: #64748b;
  --color-neutral-600: #475569;
  --color-neutral-700: #334155;
  --color-neutral-800: #1e293b;
  --color-neutral-900: #0f172a;
  --color-neutral-950: #020617;
}

/* Dark Mode Color Overrides */
.dark {
  --color-neutral-50: #020617;
  --color-neutral-100: #0f172a;
  --color-neutral-200: #1e293b;
  --color-neutral-300: #334155;
  --color-neutral-400: #475569;
  --color-neutral-500: #64748b;
  --color-neutral-600: #94a3b8;
  --color-neutral-700: #cbd5e1;
  --color-neutral-800: #e2e8f0;
  --color-neutral-900: #f1f5f9;
  --color-neutral-950: #f8fafc;
}

Theme-Aware Semantic Tokens

:root {
  /* Background Colors */
  --bg-primary: var(--color-neutral-50);
  --bg-secondary: var(--color-neutral-100);
  --bg-tertiary: var(--color-neutral-200);
  --bg-elevated: #ffffff;
  --bg-overlay: rgba(0, 0, 0, 0.5);

  /* Text Colors */
  --text-primary: var(--color-neutral-900);
  --text-secondary: var(--color-neutral-700);
  --text-tertiary: var(--color-neutral-500);
  --text-inverse: #ffffff;
  --text-brand: var(--color-primary-600);

  /* Border Colors */
  --border-primary: var(--color-neutral-200);
  --border-secondary: var(--color-neutral-300);
  --border-focus: var(--color-primary-500);
  --border-error: var(--color-error-500);

  /* Interactive Colors */
  --interactive-primary: var(--color-primary-500);
  --interactive-primary-hover: var(--color-primary-600);
  --interactive-primary-active: var(--color-primary-700);
  --interactive-secondary: var(--color-neutral-200);
  --interactive-secondary-hover: var(--color-neutral-300);
}

.dark {
  /* Dark Mode Background Colors */
  --bg-primary: var(--color-neutral-900);
  --bg-secondary: var(--color-neutral-800);
  --bg-tertiary: var(--color-neutral-700);
  --bg-elevated: var(--color-neutral-800);
  --bg-overlay: rgba(0, 0, 0, 0.7);

  /* Dark Mode Text Colors */
  --text-primary: var(--color-neutral-100);
  --text-secondary: var(--color-neutral-300);
  --text-tertiary: var(--color-neutral-500);
  --text-inverse: var(--color-neutral-900);
  --text-brand: var(--color-primary-400);

  /* Dark Mode Border Colors */
  --border-primary: var(--color-neutral-700);
  --border-secondary: var(--color-neutral-600);
  --border-focus: var(--color-primary-400);

  /* Dark Mode Interactive Colors */
  --interactive-primary: var(--color-primary-500);
  --interactive-primary-hover: var(--color-primary-400);
  --interactive-primary-active: var(--color-primary-300);
  --interactive-secondary: var(--color-neutral-700);
  --interactive-secondary-hover: var(--color-neutral-600);
}

Typography System

Font Families

:root {
  /* Primary Font - Poppins (existing) */
  --font-primary: 'Poppins', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  
  /* Monospace Font */
  --font-mono: 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
  
  /* System Font Stack (fallback) */
  --font-system: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
}

Font Sizes & Line Heights

:root {
  /* Font Sizes */
  --text-xs: 0.75rem;     /* 12px */
  --text-sm: 0.875rem;    /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg: 1.125rem;    /* 18px */
  --text-xl: 1.25rem;     /* 20px */
  --text-2xl: 1.5rem;     /* 24px */
  --text-3xl: 1.875rem;   /* 30px */
  --text-4xl: 2.25rem;    /* 36px */
  --text-5xl: 3rem;       /* 48px */
  --text-6xl: 3.75rem;    /* 60px */
  --text-7xl: 4.5rem;     /* 72px */

  /* Line Heights */
  --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: 0em;
  --tracking-wide: 0.025em;
  --tracking-wider: 0.05em;
  --tracking-widest: 0.1em;
}

Typography Scale

:root {
  /* Heading Styles */
  --heading-1: var(--text-4xl);
  --heading-1-line-height: var(--leading-tight);
  --heading-1-weight: 700;
  --heading-1-tracking: var(--tracking-tight);

  --heading-2: var(--text-3xl);
  --heading-2-line-height: var(--leading-tight);
  --heading-2-weight: 600;
  --heading-2-tracking: var(--tracking-tight);

  --heading-3: var(--text-2xl);
  --heading-3-line-height: var(--leading-snug);
  --heading-3-weight: 600;
  --heading-3-tracking: var(--tracking-normal);

  --heading-4: var(--text-xl);
  --heading-4-line-height: var(--leading-snug);
  --heading-4-weight: 600;
  --heading-4-tracking: var(--tracking-normal);

  --heading-5: var(--text-lg);
  --heading-5-line-height: var(--leading-normal);
  --heading-5-weight: 500;
  --heading-5-tracking: var(--tracking-normal);

  --heading-6: var(--text-base);
  --heading-6-line-height: var(--leading-normal);
  --heading-6-weight: 500;
  --heading-6-tracking: var(--tracking-wide);

  /* Body Text Styles */
  --body-large: var(--text-lg);
  --body-large-line-height: var(--leading-relaxed);
  --body-large-weight: 400;

  --body-base: var(--text-base);
  --body-base-line-height: var(--leading-normal);
  --body-base-weight: 400;

  --body-small: var(--text-sm);
  --body-small-line-height: var(--leading-normal);
  --body-small-weight: 400;

  --body-xs: var(--text-xs);
  --body-xs-line-height: var(--leading-normal);
  --body-xs-weight: 400;
}

Spacing System

Base Spacing Scale

:root {
  /* Spacing Scale (based on 4px grid) */
  --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 */
}

Semantic Spacing

:root {
  /* Component Spacing */
  --spacing-component-xs: var(--space-2);
  --spacing-component-sm: var(--space-3);
  --spacing-component-md: var(--space-4);
  --spacing-component-lg: var(--space-6);
  --spacing-component-xl: var(--space-8);

  /* Layout Spacing */
  --spacing-layout-xs: var(--space-4);
  --spacing-layout-sm: var(--space-6);
  --spacing-layout-md: var(--space-8);
  --spacing-layout-lg: var(--space-12);
  --spacing-layout-xl: var(--space-16);
  --spacing-layout-2xl: var(--space-24);

  /* Container Spacing */
  --spacing-container-xs: var(--space-4);
  --spacing-container-sm: var(--space-6);
  --spacing-container-md: var(--space-8);
  --spacing-container-lg: var(--space-12);
  --spacing-container-xl: var(--space-16);
}

Border Radius System

: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;

  /* Semantic Border Radius */
  --radius-button: var(--radius-md);
  --radius-card: var(--radius-lg);
  --radius-modal: var(--radius-xl);
  --radius-input: var(--radius-md);
  --radius-badge: var(--radius-full);
}

Shadow System

:root {
  /* Shadow Scale */
  --shadow-xs: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
  --shadow-sm: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1);
  --shadow-base: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
  --shadow-md: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
  --shadow-lg: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);
  --shadow-xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
  --shadow-2xl: 0 50px 100px -20px rgba(0, 0, 0, 0.25);
  --shadow-inner: inset 0 2px 4px 0 rgba(0, 0, 0, 0.05);

  /* Semantic Shadows */
  --shadow-card: var(--shadow-sm);
  --shadow-card-hover: var(--shadow-md);
  --shadow-modal: var(--shadow-xl);
  --shadow-dropdown: var(--shadow-lg);
  --shadow-button: var(--shadow-xs);
  --shadow-button-hover: var(--shadow-sm);
}

.dark {
  /* Dark Mode Shadow Adjustments */
  --shadow-xs: 0 1px 2px 0 rgba(0, 0, 0, 0.3);
  --shadow-sm: 0 1px 3px 0 rgba(0, 0, 0, 0.4), 0 1px 2px -1px rgba(0, 0, 0, 0.4);
  --shadow-base: 0 4px 6px -1px rgba(0, 0, 0, 0.4), 0 2px 4px -2px rgba(0, 0, 0, 0.4);
  --shadow-md: 0 10px 15px -3px rgba(0, 0, 0, 0.4), 0 4px 6px -4px rgba(0, 0, 0, 0.4);
  --shadow-lg: 0 20px 25px -5px rgba(0, 0, 0, 0.4), 0 8px 10px -6px rgba(0, 0, 0, 0.4);
  --shadow-xl: 0 25px 50px -12px rgba(0, 0, 0, 0.5);
  --shadow-2xl: 0 50px 100px -20px rgba(0, 0, 0, 0.5);
}

Z-Index System

:root {
  /* Z-Index Scale */
  --z-0: 0;
  --z-10: 10;
  --z-20: 20;
  --z-30: 30;
  --z-40: 40;
  --z-50: 50;

  /* Semantic Z-Index */
  --z-dropdown: var(--z-10);
  --z-sticky: var(--z-20);
  --z-fixed: var(--z-30);
  --z-modal-backdrop: var(--z-40);
  --z-modal: var(--z-50);
  --z-popover: var(--z-50);
  --z-tooltip: var(--z-50);
}

Breakpoint System

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

Animation & Transition System

:root {
  /* Timing 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);

  /* Duration Scale */
  --duration-75: 75ms;
  --duration-100: 100ms;
  --duration-150: 150ms;
  --duration-200: 200ms;
  --duration-300: 300ms;
  --duration-500: 500ms;
  --duration-700: 700ms;
  --duration-1000: 1000ms;

  /* Semantic Transitions */
  --transition-fast: var(--duration-150) var(--ease-out);
  --transition-base: var(--duration-200) var(--ease-out);
  --transition-slow: var(--duration-300) var(--ease-out);
  --transition-bounce: var(--duration-300) var(--ease-bounce);
}

Usage Guidelines

Color Usage

• Use semantic color tokens (--text-primary, --bg-elevated) instead of direct color values
• Ensure sufficient contrast ratios (4.5:1 for normal text, 3:1 for large text)
• Test all color combinations in both light and dark modes
• Use brand colors sparingly for emphasis and calls-to-action

Typography Usage

• Use the typography scale consistently across all components
• Maintain proper hierarchy with heading levels
• Ensure line heights provide comfortable reading experience
• Use font weights purposefully to create visual hierarchy

Spacing Usage

• Follow the 4px grid system for all spacing decisions
• Use semantic spacing tokens for consistent component spacing
• Maintain consistent spacing patterns within component families
• Consider touch targets (minimum 44px) for interactive elements

Implementation Notes

• All design tokens should be implemented as CSS custom properties
• Tokens should be imported into the main Tailwind CSS configuration
• Components should reference tokens rather than hardcoded values
• Dark mode variants should be automatically applied via CSS custom properties