[Design] Build Comprehensive Design System with CSS Tokens, Dark Theme, and Brand Integration

[KarenZita01]

Description

The frontend uses TailwindCSS 4 with PostCSS but has no custom theme configuration beyond the default variables. There's no consistent color palette, typography system, spacing scale, or component style overrides. As the application grows with dozens of components, a well-defined design theme is essential for visual consistency.

Design system gaps:

• No CSS custom properties for brand colors beyond background/foreground
• No typography scale (font sizes, line heights, font weights)
• No spacing scale
• No shadow scale for elevation
• No border radius token system
• No breakpoint naming convention
• No animation/transition timing configuration
• No dark theme refinement (current dark theme is basic)
• No component-specific CSS variables for customization
• No brand asset integration (logo, icons)

Technical Context & Impact

• Affected Components/Files: app/globals.css, tailwind.config.ts (missing - v4 doesn't need it but needs CSS config)
• Impact: Inconsistent visual design; hard to maintain theme changes

Step-by-Step Implementation Guide

1. Define design tokens in globals.css using @theme directive:
   • Colors: brand-50 through brand-950, success, warning, error, info
   • Typography: font-size-xs through font-size-5xl, font-leading, font-tracking
   • Spacing: space-1 through space-16 corresponding to 0.25rem increments
   • Shadows: shadow-sm, shadow-md, shadow-lg, shadow-xl
   • Radii: radius-sm, radius-md, radius-lg, radius-full
2. Create CSS variable pattern for component customization:

   .card { --card-bg: var(--color-surface); --card-border: var(--color-border); }
   .btn { --btn-bg: var(--color-brand); --btn-text: white; }

3. Implement comprehensive dark theme: Each semantic color has a dark variant; test all components in both themes
4. Add brand assets: /public/logo.svg, /public/icon.svg, /public/logo-mark.svg with proper sizing
5. Create icon set: Use SVG sprite or lucide-react for consistent icons across app
6. Add TailwindCSS Typography plugin: tailwindcss-typography for prose content formatting
7. Document design system: Create src/lib/design/DESIGN_TOKENS.md with visual examples of all tokens
8. Create visual regression tests: Chromatic or Percy integration for component visual testing

Verification & Testing Steps

1. Run npm run build and verify CSS compiles without errors
2. View dark mode and light mode for every component
3. Verify brand colors are used consistently (not hardcoded hex values)
4. Check typography scale: headers should use brand font, body uses system font
5. Test shadow/elevation on cards, modals, and dropdowns
6. Run npx tsc --noEmit