Dark Mode Agent Skill
Theme switching with CSS variables, system preference detection, next-themes, and persistence.
The Skill
Full content, every format. Copy it, download it, or install with one command.
---
description: Theme switching with CSS variables, system preference detection, next-themes, and persistence.
homepage: https://yepapi.com/skills/dark-mode
metadata:
tags: [theme, dark-mode, css-variables, next-themes]
---
# Dark Mode
## Rules
- Use `next-themes` for Next.js apps — wraps the app in `<ThemeProvider attribute="class" defaultTheme="system">`
- CSS variables for colors — define in `:root` (light) and `.dark` (dark), reference as `var(--background)`
- System preference detection: `defaultTheme="system"` respects `prefers-color-scheme` media query
- Theme toggle component: cycle between light/dark/system — use `useTheme()` hook from `next-themes`
- Tailwind integration: enable `darkMode: "class"` in tailwind config, use `dark:` prefix for overrides
- Hydration fix: suppress hydration mismatch by mounting theme toggle only after `useEffect` or using `suppressHydrationWarning`
- Persistence: `next-themes` stores preference in `localStorage` and applies it as a `class` on `<html>`
- Transition: add `transition-colors duration-200` to body for smooth theme switch
## Patterns
```tsx
// Layout wrapper
import { ThemeProvider } from "next-themes";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
{children}
</ThemeProvider>
</body>
</html>
);
}
```
```tsx
// Theme toggle
"use client";
import { useTheme } from "next-themes";
import { useEffect, useState } from "react";
export function ThemeToggle() {
const { theme, setTheme } = useTheme();
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
if (!mounted) return null;
return (
<button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
{theme === "dark" ? "☀️" : "🌙"}
</button>
);
}
```
```css
/* CSS variables */
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
}
.dark {
--background: 222.2 84% 4.9%;
--foreground: 210 40% 98%;
}
```
## Avoid
- Hardcoding colors instead of CSS variables — makes theming impossible
- Forgetting `suppressHydrationWarning` on `<html>` — causes hydration errors
- Flash of wrong theme: ensure `next-themes` script runs before paint (it does by default)
- Only supporting light/dark without system option — respect user OS preferenceInstall
Why Use the Dark Mode Skill?
Without this skill, your AI guesses at dark mode patterns. It might hallucinate deprecated APIs, use outdated conventions, or miss best practices entirely. With it, your AI follows a proven ruleset — every suggestion aligns with current standards.
Drop this skill into your project and your AI instantly knows the rules. Better code suggestions, fewer errors, faster shipping.
Try These Prompts
These prompts work better with the Dark Mode skill installed. Your AI knows the context and writes code that fits.
"Add dark mode with CSS variables, system preference detection, and smooth transitions"
"Create a theme provider with next-themes that persists user preference across sessions"
"Build a complete dark/light/system theme switcher with proper color tokens"
Dark Mode skill — FAQ
It covers CSS variable theming, system preference detection, next-themes integration, and persistence. Your AI implements dark mode that works correctly with SSR and avoids flash of unstyled content.
Run `npx skills add YepAPI/skills --skill dark-mode` in your project root. This copies the skill file into your repo where your AI coding tool can read it automatically.
The skill uses a blocking script that reads the stored preference before React hydrates. It includes the next-themes pattern that sets the correct theme class on the HTML element during SSR.