Skip to main content

​
Theme System

Meelio uses a sophisticated theme system built on next-themes that provides dark mode, light mode, and automatic system-based theme switching.
Theme preferences are saved locally and persist across browser sessions.

​
Available Themes

Meelio offers three theme modes to match your preferences and environment.

Light Mode

A bright, clean interface optimized for well-lit environments.

Dark Mode

A comfortable dark theme that reduces eye strain in low-light conditions.

System

Automatically matches your operating system’s theme preference.

​
Changing Your Theme

Access theme settings through the Settings dialog:
1

Open Settings

Click the settings icon in the dock or press Cmd/Ctrl + S
2

Navigate to Appearance

Select the “Appearance” tab from the settings sidebar
3

Select Your Theme

Choose from Light, Dark, or System theme options

​
Light Mode

Perfect for daytime use and bright environments.Features:
  • High contrast for outdoor visibility
  • Clean, professional appearance
  • Reduced blue light compared to pure white backgrounds
  • Optimized color palette for readability
theme: "light"

​
Theme Implementation

Meelio’s theme system is powered by a React Context provider that manages theme state and persistence.

​
Technical Details

The theme system uses the ThemeProvider component located at:
// packages/shared/src/components/common/theme-provider.tsx

export type Theme = "dark" | "light" | "system";

interface ThemeProviderState {
  theme: Theme;
  setTheme: (theme: Theme) => void;
}
Key Features:
  • LocalStorage persistence with key ui-theme
  • Automatic system theme detection via media queries
  • Real-time theme updates without page reload
  • CSS class-based theme switching on <html> element
Developers can access the theme system in custom components:
import { useTheme } from "@/components/common/theme-provider";

function MyComponent() {
  const { theme, setTheme } = useTheme();
  
  return (
    <button onClick={() => setTheme("dark")}>
      Current theme: {theme}
    </button>
  );
}
Meelio listens to the system’s color scheme preference:
const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");

// Automatically applies system theme
if (theme === "system") {
  const systemTheme = mediaQuery.matches ? "dark" : "light";
  document.documentElement.classList.add(systemTheme);
}
The system theme updates automatically when your OS theme changes, without requiring a page refresh.

​
Visual Customization Beyond Themes

In addition to theme selection, Meelio offers other appearance customization options:

​
Background Wallpapers

Dynamic Backgrounds

Choose from a curated collection of beautiful wallpapers to personalize your workspace.Options:
  • Static wallpapers from the gallery
  • Automatic wallpaper rotation (see General Settings)
  • Custom shadow overlay for better text readability
  • Blur effects for content focus
Access backgrounds through the Backgrounds icon in the dock.

​
Dock Customization

Dock Appearance

Customize your dock’s visual presentation:Settings:
  • Toggle icon labels for cleaner appearance
  • Show/hide individual dock items
  • Responsive dock layout on mobile devices
See Settings for complete dock customization options.

​
Accessibility Features

Meelio’s theme system is built with accessibility in mind:
Both light and dark themes maintain WCAG AA contrast ratios for text readability:
  • Text on background: minimum 4.5:1 ratio
  • Interactive elements: clear focus indicators
  • Muted text: maintains 3:1 minimum contrast
Meelio respects your system’s reduced motion preferences:
@media (prefers-reduced-motion: reduce) {
  /* Animations are simplified or removed */
}
UI elements don’t rely solely on color:
  • Icons accompany color-coded elements
  • Text labels provide context
  • Patterns and shapes distinguish states

​
Theme-Aware Components

Meelio’s components automatically adapt to your selected theme:

​
UI Components

All panels and cards adjust their background colors, borders, and shadows based on the active theme.
  • Light: Subtle shadows with light backgrounds
  • Dark: Elevated surfaces with subtle highlights

​
Color Palette

Meelio uses a sophisticated color system that adapts to your theme: 
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --border: 214.3 31.8% 91.4%;
  /* ... additional color variables */
}
The color system uses HSL values for precise color control and smooth theme transitions.

​
Best Practices

Recommendations:
  • Use Light theme for daytime work in bright environments
  • Switch to Dark theme in low-light conditions or evening
  • Select System theme to automatically match your device’s settings
  • Consider enabling dark mode 2-3 hours before bedtime to reduce blue light
Wallpaper Selection:
  • Choose darker wallpapers for dark theme
  • Use lighter, softer wallpapers for light theme
  • Enable shadow overlay if text readability is reduced
  • Test different wallpapers with your preferred theme
Multi-Device Setup:
  • Use System theme for automatic consistency
  • Export your settings to maintain preferences
  • Consider different themes for desktop vs mobile
The System theme option is recommended for most users as it provides automatic adaptation to your environment throughout the day.

​
Troubleshooting

If your theme isn’t displaying correctly:
  1. Clear your browser cache and reload
  2. Check that JavaScript is enabled
  3. Verify localStorage is not disabled
  4. Try selecting the theme again in Settings
If System theme doesn’t update automatically:
  1. Refresh the page after changing OS theme
  2. Check browser permissions for system preferences
  3. Try selecting a specific theme, then switch back to System
If your theme resets on page reload:
  1. Check that cookies/localStorage are enabled
  2. Verify you’re not in private/incognito mode
  3. Check browser storage quota

Build docs developers (and LLMs) love

Get started for freeTalk to us