A Guide to Implementing Dark Mode with CSS

Understanding Dark Mode Requirements
CSS Variables: The Foundation of Theming
Detecting System-Level Dark Mode Preferences
Adding a User Toggle for Dark Mode
Handling Edge Cases: Images, Icons, and Third-Party Content
Testing and Optimization
Best Practices for Dark Mode Implementation
Conclusion
References

1. Understanding Dark Mode Requirements

Before diving into code, it’s critical to define clear goals for your dark mode implementation. Key requirements include:

Accessibility First

Dark mode must maintain sufficient color contrast to meet WCAG 2.1 standards (a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text). Poor contrast can make content unreadable, defeating the purpose of reducing eye strain.

Respect User Preferences

Users may have system-level dark mode enabled (e.g., via Windows, macOS, or mobile OS settings). Your implementation should prioritize this by default, then allow users to override it with a manual toggle.

Consistency Across the Interface

All UI elements—text, buttons, cards, and backgrounds—must adapt uniformly to dark mode. Inconsistent theming (e.g., a bright white card on a dark background) breaks immersion and harms usability.

Persistence

If a user manually toggles dark mode, their preference should persist across sessions (e.g., via localStorage).

2. CSS Variables: The Foundation of Theming

CSS Custom Properties (variables) are the backbone of modern theming. They allow you to define reusable values (e.g., colors, spacing) and update them globally—making dark mode toggling simple and efficient.

Step 1: Define Light Mode Variables

Start by defining core color variables for light mode in the :root selector (global scope):

:root {
  /* Background colors */
  --bg-primary: #ffffff; /* Main background */
  --bg-secondary: #f5f5f5; /* Card/section background */
  
  /* Text colors */
  --text-primary: #333333; /* Primary text */
  --text-secondary: #666666; /* Secondary text */
  
  /* Accent colors */
  --accent: #007bff; /* Buttons, links */
  
  /* Border colors */
  --border: #e0e0e0; /* Borders */
}

Step 2: Override Variables for Dark Mode

Next, define dark mode variables by scoping them to a .dark class on the :root or <html> element. This class will be toggled via JavaScript later:

.dark {
  /* Background colors */
  --bg-primary: #1a1a1a; /* Dark main background */
  --bg-secondary: #2d2d2d; /* Dark card background */
  
  /* Text colors */
  --text-primary: #f0f0f0; /* Light primary text */
  --text-secondary: #b0b0b0; /* Light secondary text */
  
  /* Accent colors (adjust for dark mode readability) */
  --accent: #4dabf7; /* Brighter accent for dark mode */
  
  /* Border colors */
  --border: #3d3d3d; /* Dark borders */
}

Step 3: Apply Variables to UI Elements

Use the variables throughout your CSS to style elements. This ensures all components inherit the current theme’s colors:

body {
  background-color: var(--bg-primary);
  color: var(--text-primary);
  transition: background-color 0.3s ease, color 0.3s ease; /* Smooth transition */
}

.card {
  background-color: var(--bg-secondary);
  border: 1px solid var(--border);
  padding: 1.5rem;
  border-radius: 8px;
}

.btn {
  background-color: var(--accent);
  color: white;
  padding: 0.5rem 1rem;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

a {
  color: var(--accent);
}

The transition property ensures colors fade smoothly when switching themes, improving user experience.

3. Detecting System-Level Dark Mode Preferences

Most modern operating systems (Windows 10+, macOS 10.14+, iOS 13+, Android 10+) let users enable dark mode at the system level. Use the prefers-color-scheme media query to detect this preference and apply dark mode automatically.

How It Works

The prefers-color-scheme media query returns dark, light, or no-preference. Use it to conditionally apply the .dark class on page load:

/* Apply dark mode if system prefers it (no user override yet) */
@media (prefers-color-scheme: dark) {
  :root {
    /* Fallback: Use dark mode variables if no user toggle is set */
    --bg-primary: #1a1a1a;
    /* ... other dark variables (duplicate of .dark class) ... */
  }
}

Wait—duplicating variables in both .dark and the media query is messy. Instead, use the media query to add the .dark class to the HTML element via JavaScript. This keeps variables centralized.

4. Adding a User Toggle for Dark Mode

Users may want to override their system preference (e.g., a user with system light mode who prefers dark mode on your site). A toggle switch lets them choose, with persistence via localStorage.

Step 1: Add HTML for the Toggle

Add a simple toggle (e.g., a checkbox) to your UI:

<div class="theme-toggle">
  <label for="dark-mode-toggle">Dark Mode</label>
  <input 
    type="checkbox" 
    id="dark-mode-toggle" 
    aria-label="Toggle dark mode"
  >
</div>

Step 2: Style the Toggle (Optional but Recommended)

Style the toggle to look like a switch. Here’s a basic example:

.theme-toggle {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  margin: 1rem;
}

#dark-mode-toggle {
  width: 40px;
  height: 20px;
  appearance: none;
  background: var(--border);
  border-radius: 10px;
  position: relative;
  cursor: pointer;
}

#dark-mode-toggle:checked {
  background: var(--accent);
}

#dark-mode-toggle::before {
  content: "";
  width: 16px;
  height: 16px;
  background: white;
  border-radius: 50%;
  position: absolute;
  top: 2px;
  left: 2px;
  transition: transform 0.3s ease;
}

#dark-mode-toggle:checked::before {
  transform: translateX(20px); /* Slide to the right when checked */
}

Step 3: JavaScript for Toggling and Persistence

Use JavaScript to:

Check for saved preferences in localStorage on page load.
Toggle the .dark class when the user clicks the switch.
Update localStorage with the new preference.

// Get elements
const toggle = document.getElementById("dark-mode-toggle");
const html = document.documentElement;

// Check for saved theme preference or use system preference
const savedTheme = localStorage.getItem("theme");
const systemTheme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";

// Set initial theme
const initialTheme = savedTheme || systemTheme;
if (initialTheme === "dark") {
  html.classList.add("dark");
  toggle.checked = true;
}

// Toggle theme when switch is clicked
toggle.addEventListener("change", () => {
  if (toggle.checked) {
    // Enable dark mode
    html.classList.add("dark");
    localStorage.setItem("theme", "dark");
  } else {
    // Enable light mode
    html.classList.remove("dark");
    localStorage.setItem("theme", "light");
  }
});

Step 4: Sync with System Preference Changes

If the user updates their system theme while your site is open, sync the toggle:

window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e) => {
  const newTheme = e.matches ? "dark" : "light";
  // Only update if no saved preference exists
  if (!localStorage.getItem("theme")) {
    if (newTheme === "dark") {
      html.classList.add("dark");
      toggle.checked = true;
    } else {
      html.classList.remove("dark");
      toggle.checked = false;
    }
  }
});

5. Handling Edge Cases

Dark mode can break unexpected elements. Here’s how to fix common issues:

Images and Media

Photographs: Avoid inverting images (it distorts colors). Instead, use darker variants of images for dark mode. Use the <picture> element with a media query:

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

SVGs/Icons: Use currentColor for SVG fills/strokes to inherit text color (adapts to themes):
```
<svg fill="currentColor" viewBox="0 0 24 24">
  <path d="M12 3..."></path>
</svg>
```

Third-Party Content

Iframes (e.g., ads, maps) or embeds may not respect dark mode. Use prefers-color-scheme in their URLs if supported (e.g., YouTube: ?color=white for dark mode).

Forms and Inputs

Browsers style form elements (e.g., input, select) differently. Override defaults with theme variables:

input, select, textarea {
  background-color: var(--bg-secondary);
  color: var(--text-primary);
  border: 1px solid var(--border);
}

6. Testing and Optimization

Cross-Browser Compatibility

CSS Variables: Supported in all modern browsers (Chrome 49+, Firefox 31+, Safari 9.1+).
prefers-color-scheme: Supported in Chrome 76+, Firefox 67+, Safari 12.1+.
For older browsers, use a polyfill like css-vars-ponyfill for CSS variables.

Accessibility Testing

Use tools like WebAIM Contrast Checker to verify text contrast.
Run Lighthouse audits to catch accessibility issues.

Performance

CSS variables are processed by the browser, so they’re fast. Avoid excessive JavaScript for theme toggling.
Use localStorage sparingly (only store the theme preference, not large data).

7. Best Practices for Dark Mode Implementation

Prioritize System Preferences: Default to the user’s OS setting, then let them override.
Offer a Clear Toggle: Make the toggle visible and accessible (e.g., in the header/settings).
Test Contrast Rigorously: Poor contrast harms usability—never compromise here.
Persist Preferences: Use localStorage to remember user choices.
Avoid Forcing Modes: Never enable dark mode without user consent (e.g., via a popup).

8. Conclusion

Dark mode is more than a trend—it’s a usability feature that enhances accessibility and user satisfaction. By leveraging CSS variables, respecting system preferences, and adding a user toggle, you can implement a seamless dark mode experience.

Remember: The goal is to give users choice. With careful testing and attention to detail, your dark mode will delight users and set your site apart.

Table of Contents