michaelschiemer/backups/docs-backup-20250731125004/design-system/foundations.md

Design System Foundations

Core design principles, tokens, and guidelines for consistent visual language.

🎨 Color System

Primary Palette

--color-primary: #6366f1;     /* Indigo - Main brand color */
--color-primary-50: #eef2ff;  /* Lightest tint */
--color-primary-100: #e0e7ff;
--color-primary-200: #c7d2fe;
--color-primary-300: #a5b4fc;
--color-primary-400: #818cf8;
--color-primary-500: #6366f1; /* Base */
--color-primary-600: #4f46e5;
--color-primary-700: #4338ca;
--color-primary-800: #3730a3;
--color-primary-900: #312e81; /* Darkest shade */

Semantic Colors

/* Success - Green */
--color-success: #10b981;
--color-success-light: #d1fae5;
--color-success-dark: #047857;

/* Warning - Amber */
--color-warning: #f59e0b;
--color-warning-light: #fef3c7;
--color-warning-dark: #d97706;

/* Error - Red */
--color-error: #ef4444;
--color-error-light: #fee2e2;
--color-error-dark: #dc2626;

/* Info - Blue */
--color-info: #3b82f6;
--color-info-light: #dbeafe;
--color-info-dark: #1d4ed8;

Neutral Palette

--color-gray-50: #f8fafc;
--color-gray-100: #f1f5f9;
--color-gray-200: #e2e8f0;
--color-gray-300: #cbd5e1;
--color-gray-400: #94a3b8;
--color-gray-500: #64748b;
--color-gray-600: #475569;
--color-gray-700: #334155;
--color-gray-800: #1e293b;
--color-gray-900: #0f172a;

📝 Typography

Font Stacks

/* Sans Serif - Primary */
--font-family-sans: 'Inter', system-ui, -apple-system, 'Segoe UI', sans-serif;

/* Monospace - Code */
--font-family-mono: 'SF Mono', 'Monaco', 'Cascadia Code', 'Fira Code', monospace;

/* Serif - Optional */
--font-family-serif: 'Charter', 'Georgia', 'Times New Roman', serif;

Type Scale

/* Font Sizes (16px base) */
--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 */
--text-8xl: 6rem;      /* 96px */
--text-9xl: 8rem;      /* 128px */

Font Weights

--font-thin: 100;
--font-extralight: 200;
--font-light: 300;
--font-normal: 400;
--font-medium: 500;
--font-semibold: 600;
--font-bold: 700;
--font-extrabold: 800;
--font-black: 900;

Line Heights

--leading-none: 1;
--leading-tight: 1.25;
--leading-snug: 1.375;
--leading-normal: 1.5;
--leading-relaxed: 1.625;
--leading-loose: 2;

📏 Spacing System

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

🔲 Border Radius

--radius-none: 0;
--radius-sm: 0.125rem;   /* 2px */
--radius: 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;   /* Pill shape */

🌫 Shadows & Elevation

/* Box Shadows */
--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
--shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
--shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
--shadow-inner: inset 0 2px 4px 0 rgba(0, 0, 0, 0.06);

/* Colored Shadows */
--shadow-primary: 0 4px 14px 0 rgba(99, 102, 241, 0.15);
--shadow-success: 0 4px 14px 0 rgba(16, 185, 129, 0.15);
--shadow-warning: 0 4px 14px 0 rgba(245, 158, 11, 0.15);
--shadow-error: 0 4px 14px 0 rgba(239, 68, 68, 0.15);

📐 Layout & Grid

Breakpoints

--breakpoint-sm: 640px;   /* Small tablets */
--breakpoint-md: 768px;   /* Large tablets */
--breakpoint-lg: 1024px;  /* Laptops */
--breakpoint-xl: 1280px;  /* Desktops */
--breakpoint-2xl: 1536px; /* Large desktops */

Container Sizes

--container-sm: 640px;
--container-md: 768px;
--container-lg: 1024px;
--container-xl: 1280px;
--container-2xl: 1536px;

Z-Index Scale

--z-auto: auto;
--z-0: 0;
--z-10: 10;
--z-20: 20;
--z-30: 30;
--z-40: 40;
--z-50: 50;

/* Named layers */
--z-dropdown: 1000;
--z-sticky: 1020;
--z-fixed: 1030;
--z-modal-backdrop: 1040;
--z-modal: 1050;
--z-popover: 1060;
--z-tooltip: 1070;
--z-toast: 1080;

⏱ Motion & Animation

Duration

--duration-75: 75ms;
--duration-100: 100ms;
--duration-150: 150ms;
--duration-200: 200ms;
--duration-300: 300ms;
--duration-500: 500ms;
--duration-700: 700ms;
--duration-1000: 1000ms;

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

/* Custom easing */
--ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
--ease-smooth: cubic-bezier(0.25, 0.46, 0.45, 0.94);

🎭 Theme System

Light Theme (Default)

:root {
  --background: var(--color-gray-50);
  --surface: #ffffff;
  --surface-variant: var(--color-gray-100);
  --border: var(--color-gray-200);
  --text-primary: var(--color-gray-900);
  --text-secondary: var(--color-gray-600);
  --text-muted: var(--color-gray-500);
  --text-disabled: var(--color-gray-400);
}

Dark Theme

[data-theme="dark"] {
  --background: var(--color-gray-900);
  --surface: var(--color-gray-800);
  --surface-variant: var(--color-gray-700);
  --border: var(--color-gray-600);
  --text-primary: var(--color-gray-50);
  --text-secondary: var(--color-gray-300);
  --text-muted: var(--color-gray-400);
  --text-disabled: var(--color-gray-500);
  
  /* Adjust shadows for dark mode */
  --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.3), 0 1px 2px 0 rgba(0, 0, 0, 0.2);
  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.3), 0 2px 4px -1px rgba(0, 0, 0, 0.2);
  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.3), 0 4px 6px -2px rgba(0, 0, 0, 0.2);
}

📊 Usage Guidelines

Semantic Token Usage

/* Use semantic tokens for meaning */
.success-message {
  color: var(--color-success);
  background: var(--color-success-light);
  border-color: var(--color-success);
}

/* Use scale tokens for consistency */
.card {
  padding: var(--space-6);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-md);
}

/* Use theme tokens for adaptability */
.content {
  background: var(--surface);
  color: var(--text-primary);
  border: 1px solid var(--border);
}

Responsive Design

/* Mobile first approach */
.component {
  padding: var(--space-4);
  font-size: var(--text-sm);
  
  @media (min-width: 768px) {
    padding: var(--space-6);
    font-size: var(--text-base);
  }
  
  @media (min-width: 1024px) {
    padding: var(--space-8);
    font-size: var(--text-lg);
  }
}

Accessibility Considerations

/* Ensure sufficient contrast */
.text-on-primary {
  color: white; /* Passes WCAG AA on primary blue */
}

/* Respect motion preferences */
.animated-element {
  transition: transform var(--duration-300) var(--ease-out);
  
  @media (prefers-reduced-motion: reduce) {
    transition: none;
  }
}

/* Focus indicators */
.interactive-element:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
}

---

For implementation examples, see CSS Architecture
For component usage, see UI Components
For admin-specific patterns, see Admin Interface