Dark Mode Design

Dark mode is not light mode inverted. It's a distinct design that requires its own surface hierarchy, color logic, and testing approach.

The Core Principle: Elevation Through Luminance

On light backgrounds, elevation is shown with shadows (darker = higher). On dark backgrounds, shadows don't read. Instead, elevated surfaces get lighter.

Surface Tokens (Minimum 4 Levels)

dark/surface/base      = #121212  (deepest, page background)
dark/surface/raised    = #1E1E1E  (cards, panels)
dark/surface/elevated  = #272727  (dropdowns, menus, hover)
dark/surface/overlay   = #323232  (modals, dialogs, tooltips)

Never Use Pure Black

Pure black (#000000) causes:

• Excessive contrast with white text (halation effect)
• No room for elevation hierarchy
• Lost depth cues on OLED (true black = off = no shadow visible)

Use #121212 to #1E1E1E as base.

Color Adaptation

Brand Colors

• Desaturate by 10-20% for dark surfaces (fully saturated colors vibrate)
• Lighten primary for better contrast on dark backgrounds
• Test all brand colors on dark surfaces

Semantic Colors

Text Colors

• Primary text: #E0E0E0 (87% white, not pure white)
• Secondary text: #A0A0A0 (60% white)
• Disabled text: #6E6E6E (38% white)
• Pure white (#FFFFFF): reserved for emphasis only

Image & Media Handling

Shadow Replacement

On dark backgrounds, replace shadows with:

Implementation Architecture

CSS Custom Properties Approach

:root {
  --surface-base: #FFFFFF;
  --surface-raised: #FFFFFF;
  --text-primary: rgba(0, 0, 0, 0.87);
  /* shadows for light mode */
}

[data-theme="dark"] {
  --surface-base: #121212;
  --surface-raised: #1E1E1E;
  --text-primary: rgba(255, 255, 255, 0.87);
  /* borders instead of shadows */
}

Tailwind CSS

// tailwind.config.js
module.exports = {
  darkMode: 'class', // or 'media'
  // dark: prefix works automatically
}

Respecting System Preference

Always default to prefers-color-scheme, with optional manual override:

1. Check prefers-color-scheme: dark
2. Allow user toggle (stored in localStorage)
3. Apply theme class before render to prevent flash

Testing Checklist

• All text meets WCAG AA on dark surfaces (4.5:1 for body)
• All interactive states visible (hover, focus, active, disabled)
• No pure black backgrounds (#000000)
• Images don't become invisible or harsh
• Shadows replaced with borders/surface changes
• Tested on OLED and LCD screens
• Tested with color blindness simulators
• Smooth theme transition (no jarring flash)
• Third-party embeds handled (may need overrides)

Reference Map

• references/surface-token-map.md — luminance elevation ladder, text opacity, shadow swaps
• references/contrast-adaptation.md — WCAG 2.2 contrast QA and brand/media adaptation

Related Skills

• For design tokens → use design-systems
• For color and contrast → use ui-visual-design
• For accessibility testing → use a11y-accessibility-design