Dark Mode Design Guide

Dark mode has evolved from a niche preference to a standard expectation. 82% of users prefer it, and major companies like Apple, Google, and Microsoft have adopted it as a core feature.

1.1 Why Dark Mode?

1.2 What You'll Learn

This guide will make you an expert in dark mode design:

1. Color science in dark interfaces
2. Common mistakes and how to avoid them
3. Elevation and depth system
4. Color adaptation and contrast
5. Technical implementation with CSS
6. Smooth transitions between modes
7. Testing and accessibility

Understanding eye physiology is crucial for designing effective dark interfaces.

2.1 How We Perceive Light

Our eyes have two types of photoreceptors:

2.2 The Problem of Excessive Contrast

Pure white text (#FFFFFF) on pure black (#000000) causes:

• Halation effect: Text appears to "glow" and blur
• Eye strain: Pupil constantly contracts/dilates
• Afterimage: Residual images when looking away

2.3 The 87% Rule

Material Design recommends that main text in dark mode should have 87% opacity over the background, not 100%. This reduces contrast to comfortable levels while maintaining readability.

Avoid these mistakes that ruin user experience.

A well-designed color system is the foundation of successful dark mode.

4.1 Backgrounds: Layer System

Material Design uses an elevation system where higher surfaces are lighter:

4.2 Text: Hierarchy with Opacity

4.3 Brand Colors

Adjust your brand colors for dark mode:

• Reduce saturation: -10% to -20%
• Increase lightness: +10% to +20%
• Verify contrast: Minimum 4.5:1 with background

In dark mode, elevation is communicated with luminosity, not shadows.

5.1 The Overlay Concept

Each elevation level adds a semi-transparent white layer over the base background:

5.2 CSS Implementation

/* Dark mode elevation system */
.surface-0 { background: #121212; }
.surface-1 { background: #1E1E1E; } /* 5% overlay */
.surface-2 { background: #232323; } /* 7% overlay */
.surface-3 { background: #252525; } /* 8% overlay */
.surface-4 { background: #272727; } /* 9% overlay */

/* Or with CSS custom properties */
:root[data-theme="dark"] {
  --surface-base: #121212;
  --surface-1: color-mix(in srgb, white 5%, #121212);
  --surface-2: color-mix(in srgb, white 7%, #121212);
}

Each component needs specific considerations for dark mode.

6.1 Buttons

6.2 Inputs and Forms

6.3 Cards

In dark mode, cards use elevation instead of shadows:

• Lighter background than page base
• Optional subtle borders (#333)
• No box-shadow or very subtle

6.4 Icons

Icons need opacity adjustments:

• Active: 87% opacity
• Inactive: 60% opacity
• Disabled: 38% opacity

Semantic colors (success, error, warning, info) need specific adjustments for dark mode.

7.1 The Problem with Bright Colors

Standard semantic colors are too intense on dark backgrounds:

7.2 Conversion Table

Images and videos need special treatment in dark mode.

8.1 The Brightness Problem

Bright images on dark backgrounds create uncomfortable contrast. Solutions:

[data-theme="dark"] img {
  filter: brightness(0.9);
}

.image-container::after {
  content: '';
  position: absolute;
  inset: 0;
  background: rgba(0,0,0,0.1);
  pointer-events: none;
}

<picture>
  <source srcset="hero-dark.jpg" 
          media="(prefers-color-scheme: dark)">
  <img src="hero-light.jpg" alt="Hero">
</picture>

8.2 Logos and SVGs

Logos need specific versions for dark mode:

• Dark logo: For light backgrounds
• Light logo: For dark backgrounds
• Monochrome logo: That works on both

Multiple ways to implement dark mode, each with pros and cons.

9.1 CSS Custom Properties (Recommended)

:root {
  /* Light mode (default) */
  --color-bg: #FFFFFF;
  --color-surface: #F9FAFB;
  --color-text: #111827;
  --color-text-secondary: #6B7280;
  --color-primary: #3B82F6;
  --color-border: #E5E7EB;
}

[data-theme="dark"] {
  --color-bg: #121212;
  --color-surface: #1E1E1E;
  --color-text: rgba(255,255,255,0.87);
  --color-text-secondary: rgba(255,255,255,0.60);
  --color-primary: #60A5FA;
  --color-border: #333333;
}

/* Usage */
body {
  background: var(--color-bg);
  color: var(--color-text);
}

9.2 System Preference Detection

/* CSS */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #121212;
    /* ... rest of dark variables */
  }
}

/* JavaScript */
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)');

// Listen for changes
prefersDark.addEventListener('change', (e) => {
  document.documentElement.dataset.theme = e.matches ? 'dark' : 'light';
});

9.3 Manual Toggle with Persistence

// Read saved preference or system preference
function getTheme() {
  const saved = localStorage.getItem('theme');
  if (saved) return saved;
  return window.matchMedia('(prefers-color-scheme: dark)').matches 
    ? 'dark' 
    : 'light';
}

// Apply theme
function setTheme(theme) {
  document.documentElement.dataset.theme = theme;
  localStorage.setItem('theme', theme);
}

// Toggle
function toggleTheme() {
  const current = document.documentElement.dataset.theme;
  setTheme(current === 'dark' ? 'light' : 'dark');
}

// Initialize
setTheme(getTheme());

A well-designed transition makes theme switching pleasant instead of jarring.

10.1 Basic Transition

/* Global transition */
* {
  transition: background-color 200ms ease, 
              color 200ms ease,
              border-color 200ms ease;
}

/* Exclude elements that shouldn't animate */
img, video, iframe {
  transition: none;
}

10.2 Advanced Transition with View Transitions API

// Modern browsers
function toggleTheme() {
  if (!document.startViewTransition) {
    // Fallback for browsers without support
    setTheme(getNextTheme());
    return;
  }
  
  document.startViewTransition(() => {
    setTheme(getNextTheme());
  });
}

Dark mode has its own accessibility challenges.

11.1 WCAG Contrast

Contrast requirements are the same, but harder to achieve:

11.2 Focus States

Focus indicators must be very visible in dark mode:

[data-theme="dark"] :focus-visible {
  outline: 2px solid #60A5FA;
  outline-offset: 2px;
}

11.3 Users with Light Sensitivity

Some users need dark mode for medical reasons:

• Migraines: Bright light can trigger them
• Photophobia: Extreme light sensitivity
• Astigmatism: Light text on dark may be harder

A complete checklist to ensure your dark mode works perfectly.

12.1 Testing Checklist

Let's analyze how the best apps implement dark mode.

13.1 Twitter/X

13.2 Slack

13.3 Discord