tailwind-syntax-dark-mode
Installation
SKILL.md
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 <html> (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
- ALWAYS apply
dark:utilities to the element that should react. NEVER attempt a global stylesheet swap; Tailwind's variant model is per-utility. - ALWAYS run the JS toggle BEFORE the page paints. NEVER place the toggle inside a deferred
<script>or wait for React hydration; a flash-of-wrong-theme is the visible failure. - ALWAYS keep the strategy choice consistent across v3 and v4 boundaries. NEVER leave a v3
darkMode: 'class'config in a v4 project: v4 silently ignores it.