# Dark Mode Theming > Implement robust dark mode and theming systems with next-themes, CSS custom properties, and Tailwind CSS for seamless user experience. - Skill: `jaivishchauhan/dark-mode-theming` (Agent Skill) - Install (CLI): `npx skillmds@latest add jaivishchauhan/dark-mode-theming` - Raw SKILL.md: https://api.skillmd.com/api/skills/jaivishchauhan/dark-mode-theming/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: JaivishChauhan (https://skillmd.com/u/jaivishchauhan) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/jaivishchauhan/dark-mode-theming --- # Dark Mode & Theming System ## Overview A robust theming system allows users to choose between light, dark, and system-preference modes. We use `next-themes` for theme state management and CSS custom properties for dynamic styling. ## Setup with next-themes ### Installation ```bash npm install next-themes ``` ### Theme Provider Setup ```tsx // components/providers/theme-provider.tsx "use client"; import { ThemeProvider as NextThemesProvider } from "next-themes"; import type { ThemeProviderProps } from "next-themes"; /** * Theme provider wrapper for next-themes. * Manages light/dark/system theme preferences. */ export function ThemeProvider({ children, ...props }: ThemeProviderProps) { return ( {children} ); } ``` ### Root Layout Integration ```tsx // app/layout.tsx import { ThemeProvider } from "@/components/providers/theme-provider"; export default function RootLayout({ children, }: { children: React.ReactNode; }) { return ( {children} ); } ``` > **Note:** `suppressHydrationWarning` is required on `` to prevent hydration mismatch from the injected script. ## Theme Toggle Component ### Basic Toggle ```tsx // components/theme-toggle.tsx "use client"; import { useTheme } from "next-themes"; import { useEffect, useState } from "react"; import { Sun, Moon, Monitor } from "lucide-react"; /** * Theme toggle button with three states: light, dark, system. * Handles hydration mismatch gracefully. */ export function ThemeToggle() { const [mounted, setMounted] = useState(false); const { theme, setTheme } = useTheme(); // Prevent hydration mismatch useEffect(() => { setMounted(true); }, []); if (!mounted) { // Render placeholder with same dimensions to prevent layout shift return ( ); } ``` ### Animated Toggle with Framer Motion ```tsx // components/theme-toggle-animated.tsx "use client"; import { useTheme } from "next-themes"; import { useEffect, useState } from "react"; import { motion, AnimatePresence } from "framer-motion"; import { Sun, Moon } from "lucide-react"; export function ThemeToggleAnimated() { const [mounted, setMounted] = useState(false); const { resolvedTheme, setTheme } = useTheme(); useEffect(() => { setMounted(true); }, []); if (!mounted) { return (
); } const isDark = resolvedTheme === "dark"; return ( ); } ``` ### Dropdown Theme Selector ```tsx // components/theme-dropdown.tsx "use client"; import { useTheme } from "next-themes"; import { useEffect, useState, useRef } from "react"; import { motion, AnimatePresence } from "framer-motion"; import { Sun, Moon, Monitor, ChevronDown } from "lucide-react"; const themes = [ { value: "light", label: "Light", icon: Sun }, { value: "dark", label: "Dark", icon: Moon }, { value: "system", label: "System", icon: Monitor }, ] as const; export function ThemeDropdown() { const [mounted, setMounted] = useState(false); const [open, setOpen] = useState(false); const { theme, setTheme } = useTheme(); const dropdownRef = useRef(null); useEffect(() => { setMounted(true); }, []); // Close on outside click useEffect(() => { function handleClickOutside(event: MouseEvent) { if ( dropdownRef.current && !dropdownRef.current.contains(event.target as Node) ) { setOpen(false); } } document.addEventListener("mousedown", handleClickOutside); return () => document.removeEventListener("mousedown", handleClickOutside); }, []); if (!mounted) { return (
); } const currentTheme = themes.find((t) => t.value === theme) || themes[2]; const CurrentIcon = currentTheme.icon; return (
{open && ( {themes.map((t) => (
    • ))}     )}
    ); } ``` ## CSS Custom Properties System ### Design Tokens ```css /* app/globals.css */ @tailwind base; @tailwind components; @tailwind utilities; @layer base { :root { /* Background Colors */ --background: 0 0% 100%; /* white */ --foreground: 240 10% 3.9%; /* zinc-950 */ /* Card & Surface Colors */ --card: 0 0% 100%; --card-foreground: 240 10% 3.9%; /* Primary Brand Color */ --primary: 262.1 83.3% 57.8%; /* violet-500 */ --primary-foreground: 0 0% 98%; /* Secondary Color */ --secondary: 240 4.8% 95.9%; /* zinc-100 */ --secondary-foreground: 240 5.9% 10%; /* Muted/Subtle */ --muted: 240 4.8% 95.9%; --muted-foreground: 240 3.8% 46.1%; /* Accent */ --accent: 240 4.8% 95.9%; --accent-foreground: 240 5.9% 10%; /* Destructive/Error */ --destructive: 0 84.2% 60.2%; /* red-500 */ --destructive-foreground: 0 0% 98%; /* Borders & Inputs */ --border: 240 5.9% 90%; --input: 240 5.9% 90%; --ring: 262.1 83.3% 57.8%; /* Radius */ --radius: 0.5rem; } .dark { /* Dark Mode Overrides */ --background: 240 10% 3.9%; /* zinc-950 */ --foreground: 0 0% 98%; /* zinc-50 */ --card: 240 10% 3.9%; --card-foreground: 0 0% 98%; --primary: 263.4 70% 50.4%; /* violet-600 */ --primary-foreground: 0 0% 98%; --secondary: 240 3.7% 15.9%; /* zinc-800 */ --secondary-foreground: 0 0% 98%; --muted: 240 3.7% 15.9%; --muted-foreground: 240 5% 64.9%; --accent: 240 3.7% 15.9%; --accent-foreground: 0 0% 98%; --destructive: 0 62.8% 30.6%; --destructive-foreground: 0 0% 98%; --border: 240 3.7% 15.9%; --input: 240 3.7% 15.9%; --ring: 263.4 70% 50.4%; } } ``` ### Tailwind Configuration ```js // tailwind.config.js module.exports = { darkMode: "class", // Required for next-themes theme: { extend: { colors: { background: "hsl(var(--background))", foreground: "hsl(var(--foreground))", card: { DEFAULT: "hsl(var(--card))", foreground: "hsl(var(--card-foreground))", }, primary: { DEFAULT: "hsl(var(--primary))", foreground: "hsl(var(--primary-foreground))", }, secondary: { DEFAULT: "hsl(var(--secondary))", foreground: "hsl(var(--secondary-foreground))", }, muted: { DEFAULT: "hsl(var(--muted))", foreground: "hsl(var(--muted-foreground))", }, accent: { DEFAULT: "hsl(var(--accent))", foreground: "hsl(var(--accent-foreground))", }, destructive: { DEFAULT: "hsl(var(--destructive))", foreground: "hsl(var(--destructive-foreground))", }, border: "hsl(var(--border))", input: "hsl(var(--input))", ring: "hsl(var(--ring))", }, borderRadius: { lg: "var(--radius)", md: "calc(var(--radius) - 2px)", sm: "calc(var(--radius) - 4px)", }, }, }, }; ``` ### Using Theme Colors ```tsx // Components use semantic color names

    Card Title

    Card description

    ``` ## Multiple Theme Support ### Extended Themes ```css /* app/globals.css */ @layer base { :root { /* Light theme (default) */ } .dark { /* Dark theme */ } .theme-blue { --primary: 221.2 83.2% 53.3%; /* blue-500 */ --ring: 221.2 83.2% 53.3%; } .theme-green { --primary: 142.1 76.2% 36.3%; /* green-600 */ --ring: 142.1 76.2% 36.3%; } .theme-orange { --primary: 24.6 95% 53.1%; /* orange-500 */ --ring: 24.6 95% 53.1%; } /* Combine with dark mode */ .dark.theme-blue { --primary: 217.2 91.2% 59.8%; /* blue-400 */ --ring: 217.2 91.2% 59.8%; } } ``` ### Theme & Color Picker ```tsx // components/theme-picker.tsx "use client"; import { useTheme } from "next-themes"; import { useEffect, useState } from "react"; const colorThemes = [ { value: "default", label: "Violet", color: "#8b5cf6" }, { value: "theme-blue", label: "Blue", color: "#3b82f6" }, { value: "theme-green", label: "Green", color: "#22c55e" }, { value: "theme-orange", label: "Orange", color: "#f97316" }, ]; export function ThemePicker() { const [mounted, setMounted] = useState(false); const { theme, setTheme, resolvedTheme } = useTheme(); const [colorTheme, setColorTheme] = useState("default"); useEffect(() => { setMounted(true); // Load saved color theme const saved = localStorage.getItem("color-theme"); if (saved) setColorTheme(saved); }, []); useEffect(() => { // Apply color theme class document.documentElement.classList.remove( ...colorThemes.map((t) => t.value), ); if (colorTheme !== "default") { document.documentElement.classList.add(colorTheme); } localStorage.setItem("color-theme", colorTheme); }, [colorTheme]); if (!mounted) return null; return (
    {/* Mode Toggle */}
    {["light", "dark", "system"].map((mode) => ( ))}
    {/* Color Theme */}
    {colorThemes.map((ct) => (
    ); } ``` ## Dark Mode Images ### Conditional Images ```tsx // Different images for light/dark export function LogoImage() { return ( <> Logo Logo ); } // Using CSS filter for simple icons Icon; ``` ### Image with Overlay ```tsx // Darken images in dark mode
    Photo
    ``` ## Theme-Aware Gradients ```tsx // Gradient that adapts to theme
    Content
    // Glass effect
    Glassmorphism
    ``` ## Smooth Theme Transitions ### Global Transition ```css /* app/globals.css */ @layer base { * { @apply transition-colors duration-200; } } /* Or be more specific to prevent animation issues */ body, .theme-transition { transition: background-color 0.3s ease, color 0.3s ease, border-color 0.3s ease; } ``` ### Disable During Switch ```tsx // ThemeProvider with transition handling ``` ## Theme Hook Utilities ```tsx // hooks/use-theme-utils.ts import { useTheme } from "next-themes"; import { useEffect, useState } from "react"; /** * Extended theme hook with utilities. */ export function useThemeUtils() { const { theme, setTheme, resolvedTheme, systemTheme } = useTheme(); const [mounted, setMounted] = useState(false); useEffect(() => { setMounted(true); }, []); const isDark = resolvedTheme === "dark"; const isLight = resolvedTheme === "light"; const isSystem = theme === "system"; const toggle = () => { setTheme(isDark ? "light" : "dark"); }; const cycleTheme = () => { const themes = ["light", "dark", "system"]; const currentIndex = themes.indexOf(theme || "system"); const nextIndex = (currentIndex + 1) % themes.length; setTheme(themes[nextIndex]); }; return { theme, setTheme, resolvedTheme, systemTheme, mounted, isDark, isLight, isSystem, toggle, cycleTheme, }; } ``` ## Complete Example: Themed Card ```tsx // components/themed-card.tsx import { motion } from "framer-motion"; interface ThemedCardProps { title: string; description: string; icon: React.ReactNode; } export function ThemedCard({ title, description, icon }: ThemedCardProps) { return ( {/* Gradient overlay - theme aware */}
    {/* Icon with theme colors */}
    {icon}

    {title}

    {description}

    ); } ``` ## Testing Checklist - [ ] Theme persists across page reloads - [ ] No flash of unstyled content (FOUC) - [ ] System preference detection works - [ ] Toggle animations are smooth - [ ] Images/icons adapt to theme - [ ] Contrast ratios meet WCAG in both modes - [ ] Form inputs visible in both modes - [ ] Focus states visible in both modes - [ ] Third-party embeds adapt (if applicable) ## Troubleshooting ### Flash of Wrong Theme - Ensure `suppressHydrationWarning` on `` - Use `disableTransitionOnChange` prop - Check that provider wraps entire app ### Hydration Mismatch - Use mounted check before rendering theme-dependent UI - Render placeholder during SSR ### Theme Not Persisting - Check localStorage is available - Ensure `storageKey` prop if custom - Verify no conflicting localStorage keys