Theme System with CSS Variables and Pre-built Themes

[olucasandrade]

Task: Theme System with CSS Variables and Pre-built Themes

Description

Implement a centralized theme system using CSS variables and React Context. Create 4-5 pre-built themes (Dark Pro, Nord, Dracula, Monokai) and complete dark mode polish to eliminate all light-mode artifacts. This is the foundation task that enables all visual work.

Acceptance Criteria

• ThemeProvider component created with React Context
• CSS variables defined for all color tokens (background, text, borders, accents, etc.)
• 4-5 pre-built themes implemented (Dark Pro as default, Nord, Dracula, Monokai, optional Monokai Pro)
• Theme switching works instantly via localStorage
• Dark mode completely polished - zero light-mode color leaks
• Mantine theme extended with custom dark palettes
• Theme preference persists across sessions
• All existing components in web + desktop render correctly with new theme system
• Landing page has consistent branding via Tailwind CSS variables

Technical Details

Implementation Approach

Central theme in packages/ui (shared by web + desktop):

1. Create packages/ui/src/theme/ThemeProvider.tsx with theme state and switching logic
2. Define theme presets in packages/ui/src/theme/themes.ts:
   • Dark Pro (default), Nord, Dracula, Monokai
3. Inject CSS variables into document root via ThemeProvider
4. Extend existing packages/ui/src/theme.ts (Mantine config) to use CSS variables
5. Export ThemeProvider and hooks from packages/ui

Web app (apps/web):
6. Update apps/web/src/app/[locale]/layout.tsx to wrap with ThemeProvider
7. Audit all apps/web/src/components/ for hardcoded colors

Desktop app (apps/desktop):
8. Update desktop's root layout to wrap with ThemeProvider from @trevo/ui
9. Verify all desktop components render correctly with theme system

Landing page (apps/landing):
10. Add Tailwind CSS variables for consistent branding (independent from Mantine)
11. Ensure landing visuals align with main app's design language

Key Considerations

• Use semantic color names (e.g., --color-bg-primary, --color-text-heading) not literal colors
• Ensure proper contrast ratios (WCAG AA minimum)
• Test theme switching doesn't cause flash of unstyled content
• Custom scrollbar styling for each theme

Files Affected

packages/ui (central theme):

• packages/ui/src/theme/ThemeProvider.tsx (new)
• packages/ui/src/theme/themes.ts (new - theme presets)
• packages/ui/src/theme.ts (modify - extend Mantine config)
• packages/ui/src/index.ts (modify - export ThemeProvider + hooks)

apps/web:

• apps/web/src/app/[locale]/layout.tsx (modify - wrap with ThemeProvider)
• apps/web/src/providers/MantineProvider.tsx (modify to use theme context)
• apps/web/tailwind.config.ts (extend with CSS variable references)
• All component files in apps/web/src/components/ (audit for hardcoded colors)

apps/desktop:

• Desktop root layout (modify - wrap with ThemeProvider)
• apps/desktop/tailwind.config.ts (extend with CSS variable references)
• Desktop components (audit for hardcoded colors)

apps/landing:

• apps/landing/tailwind.config.ts (add brand CSS variables)
• Landing components (align visual style)

Dependencies

• Design input for theme color palettes
• No code dependencies (first task)

Effort Estimate

• Size: M (Medium)
• Hours: 16-22 hours (expanded to cover 3 apps + shared package)
• Parallel: true (no dependencies, can start immediately)

Definition of Done

• Code implemented and tested
• All 4-5 themes working and switchable
• No light-mode artifacts in dark themes
• Theme preference persists correctly
• Documentation added to README about theme system
• Code reviewed
• Merged to main branch