# Tailwind Syntax Dark Mode
> 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
- Skill: `impertio-studio/tailwind-syntax-dark-mode` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add impertio-studio/tailwind-syntax-dark-mode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/impertio-studio/tailwind-syntax-dark-mode/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: Impertio-Studio (https://skillmd.com/u/impertio-studio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/impertio-studio/tailwind-syntax-dark-mode
---
# 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 `