AutoCom Docs

Color Modes

Auto Commerce supports four color modes that can be applied to any theme. Each mode provides a distinct visual experience while maintaining full functionality.

Available Modes

Light Mode

The default appearance with light backgrounds and dark text. Optimal for well-lit environments.

┌─────────────────────────────────────┐
│  ████████████████████  (Header)     │  ← Dark text
│  ░░░░░░░░░░░░░░░░░░░░              │  ← White background
│  ░░░ Card ░░░░░░░░░░░              │
│  ░░░░░░░░░░░░░░░░░░░░              │
│  ░░░░░░░░░░░░░░░░░░░░              │
└─────────────────────────────────────┘

Best for:

  • Bright office environments
  • Daylight use
  • Print-friendly screenshots

Dark Mode

Dark backgrounds with light text. Reduces eye strain in low-light conditions and saves battery on OLED displays.

┌─────────────────────────────────────┐
│  ████████████████████  (Header)     │  ← Light text
│  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓              │  ← Dark background
│  ▓▓▓ Card ▓▓▓▓▓▓▓▓▓▓▓              │
│  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓              │
│  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓              │
└─────────────────────────────────────┘

Best for:

  • Evening/night use
  • Reducing eye strain
  • OLED battery savings
  • Developer preference

Monochrome Mode

Grayscale UI that removes all color, useful for accessibility or creating a minimal aesthetic.

┌─────────────────────────────────────┐
│  ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒  (Header)    │  ← Grayscale
│  ░░░░░░░░░░░░░░░░░░░░              │  ← No color
│  ░░░ Card ░░░░░░░░░░░              │
│  ░░░░░░░░░░░░░░░░░░░░              │
│  ░░░░░░░░░░░░░░░░░░░░              │
└─────────────────────────────────────┘

Best for:

  • Color blindness accessibility
  • Minimal/zen aesthetics
  • Focus on content over design
  • Print preparation

System Mode

Automatically follows your operating system's color preference. When your OS switches between light and dark, the dashboard follows.

Best for:

  • Matching OS appearance
  • Automatic day/night switching
  • Consistent experience across apps

Changing Color Mode

Via Settings

  1. Go to Settings → Appearance
  2. Scroll to the Color Mode section
  3. Click on your preferred mode

Changes take effect immediately and persist across sessions.

Via Code

import { useColorMode } from '@/hooks/use-theme';

function ColorModeToggle() {
  const { colorMode, setColorMode, isDark, isMonochrome } = useColorMode();

  return (
    <div>
      <p>Current mode: {colorMode}</p>
      <p>Resolved: {isDark ? 'dark' : isMonochrome ? 'monochrome' : 'light'}</p>

      <button onClick={() => setColorMode('light')}>Light</button>
      <button onClick={() => setColorMode('dark')}>Dark</button>
      <button onClick={() => setColorMode('monochrome')}>Mono</button>
      <button onClick={() => setColorMode('system')}>System</button>
    </div>
  );
}

How It Works

Token-Based Colors

Each theme defines separate token sets for each color mode:

// Theme configuration
export const themeConfig = {
  tokens: lightTokens,           // Default (light mode)
  darkTokens: darkTokens,        // Dark mode
  monochromeTokens: monoTokens,  // Monochrome mode
};

CSS Variable Injection

When you change the color mode, the theme engine:

  1. Selects the appropriate token set
  2. Injects tokens as CSS custom properties
  3. Adds a class to <html> (dark or monochrome)
/* Dynamically set by theme engine */
:root {
  --background: 0 0% 100%;
  --foreground: 222 84% 5%;
  --primary: 222 47% 11%;
  /* ... */
}

html.dark {
  --background: 222 84% 5%;
  --foreground: 210 40% 98%;
  /* ... */
}

Monochrome Filter

Monochrome mode combines grayscale tokens with a CSS filter to ensure ALL colors become grayscale, including any hardcoded values:

.monochrome body {
  filter: grayscale(100%);
}

Persistence

Color mode preferences are saved in two locations:

  1. localStorage - Instant load on next visit
  2. Server API - Syncs across devices
// Automatic persistence flow
setColorMode('dark')
  → localStorage.setItem('autocom_color_mode', 'dark')
  → POST /api/v1/settings/theme { color_mode: 'dark' }

System Mode Detection

When using System mode, the theme engine:

  1. Reads prefers-color-scheme media query
  2. Listens for changes in real-time
  3. Updates the UI automatically
// Internal system detection
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
const systemMode = mediaQuery.matches ? 'dark' : 'light';

// Listen for OS changes
mediaQuery.addEventListener('change', (e) => {
  const newMode = e.matches ? 'dark' : 'light';
  applyColorMode(newMode);
});

Theme-Specific Colors

Each theme defines its own color palette for each mode:

ThemeShadcn

Token Light Dark
Primary hsl(222, 47%, 11%) hsl(210, 40%, 98%)
Background hsl(0, 0%, 100%) hsl(222, 84%, 5%)
Foreground hsl(222, 84%, 5%) hsl(210, 40%, 98%)

ThemeModern

Token Light Dark
Primary hsl(243, 75%, 59%) hsl(243, 75%, 65%)
Background hsl(220, 20%, 98%) hsl(224, 30%, 8%)
Foreground hsl(224, 71%, 4%) hsl(0, 0%, 95%)

Accessibility

WCAG Compliance

All color modes maintain proper contrast ratios:

  • Text: Minimum 4.5:1 contrast ratio
  • Large Text: Minimum 3:1 contrast ratio
  • UI Elements: Minimum 3:1 contrast ratio

Monochrome for Color Blindness

Monochrome mode removes reliance on color differentiation, making the UI accessible for users with color vision deficiencies.

Reduced Motion

Color mode transitions respect prefers-reduced-motion:

@media (prefers-reduced-motion: reduce) {
  * {
    transition: none !important;
  }
}

API Reference

useColorMode Hook

function useColorMode(): {
  colorMode: 'light' | 'dark' | 'system' | 'monochrome';
  resolvedColorMode: 'light' | 'dark' | 'monochrome';
  setColorMode: (mode: ColorMode) => void;
  isDark: boolean;
  isMonochrome: boolean;
}
Property Type Description
colorMode ColorMode Current setting (may be 'system')
resolvedColorMode string Actual applied mode
setColorMode function Change the color mode
isDark boolean True if resolved mode is dark
isMonochrome boolean True if resolved mode is monochrome

Troubleshooting

Colors Not Changing

  1. Clear browser cache and localStorage
  2. Ensure JavaScript is enabled
  3. Check browser console for errors

System Mode Not Detecting

  1. Verify OS has dark mode enabled
  2. Check browser supports prefers-color-scheme
  3. Some browsers require restart after OS change

Flash of Wrong Color on Load

This can happen if the color mode loads after initial render. Ensure:

  1. Color mode is read from localStorage early
  2. CSS includes default dark mode styles

Next Steps