Themes

Dark Mode and Theme System

Theme System Overview

Baseline UI supports a flexible theme system with two modes of operation: automatic system-based theming and manual theme switching with persistence.

Automatic Theming

Uses CSS prefers-color-scheme to detect system preferences automatically.

  • No JavaScript required
  • Respects system settings
  • Updates automatically

Manual Switching

Uses data-theme attribute for user-controlled theme selection.

  • Toggle button control
  • localStorage persistence
  • Overrides system preference

Automatic System Theming

The framework uses CSS custom properties that are adjusted based on the media query @media (prefers-color-scheme: dark). All colors, glassmorphism effects and components adapt automatically when the user's system preference changes.

CSS 
@media (prefers-color-scheme: dark) {
  :root {
    --color-text: #f3f4f6;
    --color-bg: #111827;
    --color-border: #374151;
    /* All theme colors automatically adjust */
  }
}

Theme Colors

Dark Mode (Default)

Dark mode is the default theme for Baseline UI, featuring a dark background with light text:

  • Background: Dark Navy #111827
  • Text: Light Gray #f3f4f6
  • Accent: Ice Blue #60a5fa
  • Border: Muted Gray #374151

Dark Mode Preview

This is how text appears in dark mode with the default Baseline UI styling.

Light Mode

Light mode features a clean white background with dark text, ideal for bright environments:

  • Background: White #ffffff
  • Text: Dark Navy #111827
  • Accent: Ice Blue #4A9EFF
  • Border: rgba(0, 0, 0, 0.15)

Light Mode Preview

This is how text appears in light mode with inverted colors for optimal readability.

Manual Theme Switching

In addition to automatic system theming, Baseline UI supports manual theme switching via the data-theme attribute. This allows users to choose their preferred theme regardless of system settings.

Using the data-theme Attribute

Set the data-theme attribute on the <html> element to manually control the theme:

HTML 
<!-- Dark Mode (Default) -->
<html data-theme="dark">
  <!-- Your content -->
</html>

<!-- Light Mode -->
<html data-theme="light">
  <!-- Your content -->
</html>

Theme Persistence with localStorage

The documentation uses localStorage to remember the user's theme preference across page reloads:

JavaScript 
// Save theme preference
localStorage.setItem('theme', 'dark');

// Load theme preference
const savedTheme = localStorage.getItem('theme') || 'dark';
document.documentElement.setAttribute('data-theme', savedTheme);

Theme Priority

When data-theme is set, it takes precedence over the system preference (prefers-color-scheme). This allows users to override their system settings for this specific site.

Theme Switcher Button

This documentation includes a theme switcher button in the top-right of the sidebar. Try it now by clicking the moon/sun icon next to "Baseline UI"!

How It Works

The theme switcher button toggles between dark and light mode, persists your choice in localStorage, and updates the icon to reflect the current theme:

JavaScript 
function initThemeSwitcher() {
  const switcher = document.getElementById('theme-switcher');
  const icon = document.getElementById('theme-icon');
  const html = document.documentElement;
  
  // Load saved theme or default to dark
  const savedTheme = localStorage.getItem('theme') || 'dark';
  
  function applyTheme(theme) {
    html.setAttribute('data-theme', theme);
    // Update icon: moon for dark, sun for light
    icon.className = theme === 'dark' ? 'fas fa-moon' : 'fas fa-sun';
    localStorage.setItem('theme', theme);
  }
  
  // Apply initial theme
  applyTheme(savedTheme);
  
  // Toggle on click
  switcher.addEventListener('click', function() {
    const currentTheme = html.getAttribute('data-theme') || 'dark';
    const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
    applyTheme(newTheme);
  });
}

HTML Structure

The theme switcher button uses Font Awesome icons for visual feedback:

HTML 
<button class="bl-btn bl-btn-secondary" 
        id="theme-switcher" 
        aria-label="Toggle theme">
  <i id="theme-icon" class="fas fa-moon"></i>
</button>
fa-moon
Dark Mode
fa-sun
Light Mode

Customization

You can customize theme colors by overriding CSS custom properties:

CSS 
/* Custom Theme Colors */
:root {
  --color-accent: #your-color;
  --color-bg: #your-bg-color;
  --color-text: #your-text-color;
}

/* Dark Mode Customizations */
[data-theme="dark"] {
  --color-accent: #your-dark-color;
  --color-bg: #your-dark-bg;
  --color-text: #your-dark-text;
}

/* Light Mode Customizations */
[data-theme="light"] {
  --color-accent: #your-light-color;
  --color-bg: #your-light-bg;
  --color-text: #your-light-text;
}

Glassmorphism in Themes

The glassmorphism effects also adapt to the theme. In dark mode, the glass backgrounds and borders are adjusted accordingly to ensure the correct contrast strength.

Light Glass

Subtle transparency

Medium Glass

Balanced effect

Heavy Glass

Strong presence