---
name: tailwind-syntax-dark-mode
description: >
Use when adding, debugging, or migrating dark-mode support in a Tailwind
project: choosing between the default `prefers-color-scheme` strategy and
user-toggleable class or attribute strategies, wiring the JavaScript
toggle, swapping CSS-variable token values for light vs dark, or
porting v3 `darkMode` configuration to the v4 `@custom-variant dark`
directive.
Prevents the four canonical dark-mode failures: assuming `dark:`
utilities need configuration before they work, leaving v3's
`darkMode: 'class'` config in a v4 project (silently ignored),
forgetting the v4 `@custom-variant dark` directive when migrating
from v3 `darkMode: 'class'`, and shipping a toggle that flashes
the wrong theme on first paint because the script runs after CSS.
Covers: default `media` strategy, class-based toggling (v3
`darkMode: 'class'` and 'selector', v4 `@custom-variant dark
(&:where(.dark, .dark *))`), attribute-based toggling
(`[data-theme="dark"]`), custom variant strategies, theme-token
swap via CSS variables, and the canonical JavaScript toggle
snippet using `localStorage` plus `matchMedia`. Always shows
v3 and v4 in side-by-side blocks; never fuses a single snippet
that hides the version difference (per D-008).
Keywords: dark mode, dark variant, dark:bg-, dark:text-,
prefers-color-scheme, darkMode class, darkMode selector,
custom-variant dark, where dark class, data-theme dark,
toggle dark mode, localStorage theme, matchMedia,
next-themes, light dark system, color scheme,
how do I add dark mode, dark mode not working,
dark utilities ignored, flash of wrong theme, FOUC,
flash of unstyled content, OS dark mode, system theme,
v3 to v4 dark mode migration, darkMode config removed.
license: MIT
compatibility: "Designed for Claude Code. Requires Tailwind CSS v3.4 or v4.0+."
metadata:
author: OpenAEC-Foundation
version: "1.0"
---
# Tailwind CSS : Dark Mode
Three strategies, four moving parts. ALWAYS pick a strategy first, then implement all four parts (CSS configuration, markup, toggle script, optional theme-token swap) consistently. NEVER mix v3 config syntax with v4 directive syntax in one project.
## Quick Reference
### The three strategies
| Strategy | When the `dark:` variant applies | Pick when |
|----------|-----------------------------------|-----------|
| `media` (default) | OS-level `prefers-color-scheme: dark` | NEVER need a manual user toggle; ALWAYS respect OS preference verbatim |
| `class` / `selector` | A class on `` (default `.dark`) | User has a UI toggle; want to override OS preference |
| `attribute` (custom) | A data attribute (e.g., `data-theme="dark"`) | Existing design system already uses attribute-based theming |
### Three invariants
1. ALWAYS apply `dark:` utilities to the element that should react. NEVER attempt a global stylesheet swap; Tailwind's variant model is per-utility.
2. ALWAYS run the JS toggle BEFORE the page paints. NEVER place the toggle inside a deferred `