Skip to content

Theme System

Overview

Our theme system provides seamless light and dark mode adaptations that maintain brand consistency while optimizing for different viewing conditions. Built on Material Design 3 principles, the system ensures excellent readability and accessibility across all themes.

Theme Philosophy

Brand Consistency

Our themes maintain consistent brand identity across all modes:

  • Purple & Amber palette adapts intelligently to each theme
  • Typography hierarchy remains clear in both light and dark
  • Component behavior is predictable across theme switches
  • Visual relationships are preserved in all conditions

User Experience Priority

  • Smooth transitions between theme changes
  • Optimized contrast for each viewing condition
  • Accessibility compliance in all theme variants
  • Performance optimization for theme switching

Light Theme

Our light theme emphasizes clarity, professionalism, and approachability:

Primary

#673ab7

Secondary

#ffc107

Surface

White

Text

#1a1a1a

Light Theme Characteristics

  • High contrast for excellent readability
  • Bright surfaces for clear content hierarchy
  • Subtle shadows for depth without distraction
  • Crisp borders for component definition

Dark Theme

Our dark theme emphasizes sophistication, focus, and reduced eye strain:

Primary

#ba68c8

Secondary

#ffd54f

Surface

Dark Gray

Text

#f5f5f5

Dark Theme Characteristics

  • Adjusted purple/amber maintain brand recognition
  • Dark surfaces reduce eye strain in low light
  • Enhanced shadows provide depth in dark environments
  • Optimized contrast for comfortable long-form reading

Theme Transitions

Smooth Animations

Our theme system includes sophisticated transition animations:

--brand-theme-transition:
  background-color 300ms cubic-bezier(0.4, 0, 0.2, 1),
  color 300ms cubic-bezier(0.4, 0, 0.2, 1),
  border-color 300ms cubic-bezier(0.4, 0, 0.2, 1),
  box-shadow 300ms cubic-bezier(0.4, 0, 0.2, 1);

Component Adaptations

All components automatically adapt during theme changes:

Buttons maintain their hierarchy while adapting colors and shadows for each theme.

.brand-button--primary {
  background: var(--brand-gradient-primary);
  /* Automatically uses theme-appropriate gradient */
}

Cards adjust background, borders, and shadows for optimal theme integration.

.brand-card {
  background-color: var(--brand-surface-primary);
  border-color: var(--md-sys-color-outline-variant);
  /* Theme-aware surface and border colors */
}

Form elements adapt contrast and focus states for each theme.

.brand-input:focus {
  border-color: var(--md-sys-color-primary);
  /* Dynamic focus color based on theme */
}

Technical Implementation

CSS Custom Properties

Our theme system uses CSS custom properties for dynamic adaptation:

:root {
  /* Dynamic surface colors */
  --brand-surface-primary: var(--md-sys-color-surface);
  --brand-surface-secondary: var(--md-sys-color-surface-container);

  /* Dynamic text colors */
  --brand-text-primary: var(--md-sys-color-on-surface);
  --brand-text-secondary: var(--md-sys-color-on-surface-variant);
}

Theme Detection

The system automatically detects and responds to theme changes:

[data-md-color-scheme="slate"] {
  /* Dark theme overrides */
  --brand-primary-300: #ba68c8;  /* Lighter purple for dark backgrounds */
  --brand-secondary-300: #ffd54f; /* Lighter amber for dark backgrounds */
}

Material Design Integration

Our themes integrate seamlessly with Material Design 3 tokens:

Token Light Theme Dark Theme
--md-sys-color-primary #673ab7 (Deep Purple) #ba68c8 (Light Purple)
--md-sys-color-secondary #ffb300 (Amber) #ffd54f (Light Amber)
--md-sys-color-surface #ffffff (White) #212121 (Dark Gray)
--md-sys-color-on-surface #1a1a1a (Near Black) #f5f5f5 (Off White)

Component Examples

Theme-Aware Cards

Light Theme

Documentation Card

Clear, bright interface for daytime reading

Content is highly readable with excellent contrast against the white background.

Dark Theme

Documentation Card

Comfortable, dark interface for extended reading

Content remains clear and readable while reducing eye strain in low-light conditions.

Theme-Aware Navigation

Light Navigation
Dark Navigation

Accessibility Features

WCAG Compliance

Both themes maintain WCAG 2.1 AA compliance:

Element Light Contrast Dark Contrast Status
Body Text 4.5:1 4.5:1 ✅ Pass
Headings 7.2:1 6.8:1 ✅ Pass
UI Elements 3.1:1 3.2:1 ✅ Pass
Link Text 5.1:1 4.9:1 ✅ Pass

High Contrast Support

Automatic adaptations for users who prefer high contrast:

@media (prefers-contrast: high) {
  .brand-card,
  .brand-button,
  .brand-input {
    border-width: 2px; /* Enhanced borders */
  }
}

Reduced Motion Support

Respects user motion preferences:

@media (prefers-reduced-motion: reduce) {
  .brand-themed {
    transition: none; /* Removes transitions */
  }
}

Theme Usage Guidelines

Design Principles

Best Practices

✅ Test in both themes during development
✅ Use semantic colors from our design system
✅ Maintain brand recognition across themes
✅ Optimize for readability in each context
✅ Consider user environment (bright vs. dark settings)

Implementation Guidelines

Technical Best Practices

✅ Use CSS custom properties for theme-aware styling
✅ Apply transition classes for smooth theme changes
✅ Test accessibility in both light and dark modes
✅ Validate contrast ratios for all color combinations
✅ Consider print styles (force light theme for printing)

Common Patterns

/* Theme-aware component */
.my-component {
  background-color: var(--brand-surface-primary);
  color: var(--brand-text-primary);
  border-color: var(--md-sys-color-outline-variant);
  transition: var(--brand-theme-transition);
}

/* Theme-specific enhancements */
[data-md-color-scheme="slate"] .my-component {
  box-shadow: var(--brand-shadow-lg);
}

Performance Optimization

Efficient Transitions

  • GPU-accelerated transitions for smooth performance
  • Optimized selectors to minimize style recalculation
  • Batched animations to reduce layout thrashing

Loading Strategy

  • Inline critical theme styles for immediate application
  • Defer non-critical theme enhancements until after load
  • Cache theme preferences for faster subsequent loads

Browser Support

Our theme system supports all modern browsers:

  • ✅ Chrome 88+
  • ✅ Firefox 78+
  • ✅ Safari 14+
  • ✅ Edge 88+

Fallbacks

  • CSS custom properties with fallback values
  • Graceful degradation for older browsers
  • Progressive enhancement for modern features

This theme system ensures our brand identity remains strong and recognizable while providing the best possible user experience across all viewing conditions and user preferences.