{
  "id": "add-dark-mode-with-tailwind",
  "type": "prompts",
  "category": "prompts",
  "locale": "zh",
  "url": "/zh/prompts/add-dark-mode-with-tailwind",
  "title": "添加 Tailwind CSS v4 暗色模式的提示",
  "description": "AI 代理提示：使用 Tailwind CSS v4 CSS 变量和 next-themes 为 Next.js 应用添加系统感知的暗色模式，加载时无闪烁。",
  "tools": [
    "Cursor",
    "Claude Code",
    "Codex",
    "Windsurf"
  ],
  "stack": [
    "Next.js",
    "TypeScript",
    "Tailwind"
  ],
  "tags": [
    "tailwind",
    "nextjs",
    "typescript"
  ],
  "difficulty": "easy",
  "updated": "2026-06-08",
  "markdown": "将此提示交给您的代理，以便使用 Tailwind v4 的基于 CSS 变量的主题系统和 `next-themes` 添加暗色模式——防止困扰简单 `localStorage` 实现的未样式内容闪烁。\n\n## 主要提示\n\n```txt title=\"Main Prompt\"\nYou are working in a Next.js App Router project with TypeScript and Tailwind CSS v4.\n\nTask: add dark mode with system preference detection and a manual toggle.\n\nRequirements:\n- Install `next-themes`.\n- In `src/app/layout.tsx`, wrap the app in `<ThemeProvider attribute=\"class\" defaultTheme=\"system\" enableSystem>`.\n  The `ThemeProvider` is a Client Component — create a wrapper `src/components/Providers.tsx` if\n  the root layout must remain a Server Component.\n- In `src/styles/global.css`, define CSS custom properties for both themes using the Tailwind v4\n  `@theme` directive:\n    - Light: `--color-bg: oklch(100% 0 0)`, `--color-text: oklch(9% 0 0)`.\n    - Dark (inside `[class=\"dark\"]` selector): override those variables.\n  Apply them to the body as `background: var(--color-bg)` and `color: var(--color-text)`.\n- Create `src/components/ThemeToggle.tsx` (Client Component) using `useTheme` from `next-themes`.\n  It should cycle through light → dark → system on click and show a sun/moon/monitor icon.\n  Use Tailwind's built-in `dark:` variant for icon visibility — do NOT use conditional classNames\n  based on the `theme` string for icon color.\n- Do not use `tailwind.config.ts` `darkMode: 'class'` — that is Tailwind v3 API. In v4, the\n  `dark:` variant is class-based by default.\n- Do NOT install lucide-react or any icon library — use SVG inline.\n\nStop and list all planned file changes before writing any code.\n```\n\n## 实现说明\n\n- 在 Tailwind v4 中，通过 `dark:` 前缀的暗色模式会自动与 `html` 元素上的 `.dark` 类配合使用——无需配置项。\n- `next-themes` 从 `localStorage` 读取已保存的主题，并在首次渲染前设置类，从而防止 FOUC（未样式内容闪烁）。\n- `ThemeProvider` 必须在客户端，但根 `layout.tsx` 可以保持服务端，通过将 provider 提取到标记为 `'use client'` 的 `Providers.tsx` 包装组件中。\n\n## 预期文件更改\n\n```txt\nsrc/app/layout.tsx                     (edited — add Providers wrapper)\nsrc/components/Providers.tsx           (new — Client Component with ThemeProvider)\nsrc/components/ThemeToggle.tsx         (new — Client Component)\nsrc/styles/global.css                  (edited — CSS custom properties for light/dark)\npackage.json                           (edited — add next-themes)\n```\n\n## 验收标准\n\n- 首次加载时，如果系统设置为暗色，页面应无闪烁地渲染暗色。\n- 切换 ThemeToggle 将循环显示亮色、暗色和系统模式；偏好设置会在重新加载后保留。\n- 所有现有的 `dark:` Tailwind 工具无需任何配置更改即可工作。\n- `bun run build` 退出码为 0。\n\n## 测试命令\n\n```bash\nbun add next-themes\nbun run typecheck\nbun run build\nbun run dev\n# open DevTools, set system dark mode, reload — confirm no white flash\n# click ThemeToggle three times and confirm cycle: light → dark → system\n```\n\n## 常见的 AI 错误\n\n- 向 v4 项目中不存在的 `tailwind.config.ts` 添加 `darkMode: 'class'`。\n- 用 `'use client'` 包裹根服务器组件 `layout.tsx`，而不是提取一个 Providers 组件。\n- 使用 `theme === 'dark'` 条件渲染而不是 Tailwind 的 `dark:` 变体，导致水合不匹配。\n- 忘记在 `ThemeProvider` 上设置 `enableSystem`，导致系统偏好检测无法正常工作。\n\n## 修复提示\n\n```txt title=\"Fix Prompt\"\nThere's a white flash on load or a hydration mismatch. Fix in order:\n1. Ensure `ThemeProvider` has `attribute=\"class\"` and `enableSystem` props.\n2. Make sure `Providers.tsx` (not `layout.tsx`) is marked `'use client'`.\n3. Remove any `theme === 'dark'` conditional rendering from `ThemeToggle` — use `dark:` Tailwind\n   variants instead so the server and client render the same HTML.\nShow only the corrected diff.\n```"
}