Dark Mode Token System — Light and Dark Theme Token Architecture

Dark Mode Token Architecture

A dark mode token system doesn't just invert colors. It requires careful mapping of every visual token to ensure readability, contrast, and aesthetic quality in both themes.

Two-Layer Token Architecture

Separate your tokens into two layers:

Layer 1: Primitive tokens (theme-independent)

:root {
  --palette-blue-50: #eff6ff;
  --palette-blue-500: #3b82f6;
  --palette-blue-900: #1e3a8a;
  --palette-gray-50: #f9fafb;
  --palette-gray-900: #111827;
}

Layer 2: Semantic tokens (theme-dependent)

/* Light theme (default) */
:root {
  --colors-bg: var(--palette-gray-50);
  --colors-text: var(--palette-gray-900);
  --colors-primary: var(--palette-blue-500);
  --colors-surface: #ffffff;
  --colors-border: #e5e7eb;
}

/* Dark theme */
.dark {
  --colors-bg: var(--palette-gray-900);
  --colors-text: var(--palette-gray-50);
  --colors-primary: var(--palette-blue-500);
  --colors-surface: #1f2937;
  --colors-border: #374151;
}

What Changes in Dark Mode

Not everything inverts. Follow these guidelines:

• Backgrounds: Swap light for dark
• Text: Swap dark for light
• Primary colors: Often stay the same or shift slightly lighter
• Borders: Use lighter shades in dark mode
• Shadows: Increase opacity (dark backgrounds absorb shadow)
• Images/illustrations: May need separate dark variants

Implementation Strategies

1. CSS class toggle (.dark): Best for manual theme switching (next-themes)
2. @media (prefers-color-scheme: dark): Follows OS preference
3. Both: Use media query as default, class toggle as override

Token File Structure

{
  "colors": {
    "bg": {
      "light": "#f9fafb",
      "dark": "#111827"
    },
    "text": {
      "light": "#111827",
      "dark": "#f9fafb"
    }
  }
}

Transform tools like Style Dictionary can convert this structure into platform-specific output.