Prompt zum Hinzufügen des Dark Mode mit Tailwind CSS v4

KI-Agent-Prompt zum Hinzufügen systembewusster Dark-Mode-Unterstützung in einer Next.js-App mit Tailwind CSS v4 CSS-Variablen und next-themes, ohne aufblitzenden Inhalt beim Laden.

Geben Sie diesen Prompt Ihrem Agenten, um den Dark Mode mit dem CSS-variablenbasierten Theming von Tailwind v4 und next-themes hinzuzufügen – und so das Aufblitzen von unformatiertem Inhalt zu verhindern, das naive localStorage-Implementierungen plagt.

Haupt-Prompt

You are working in a Next.js App Router project with TypeScript and Tailwind CSS v4.

Task: add dark mode with system preference detection and a manual toggle.

Requirements:
- Install `next-themes`.
- In `src/app/layout.tsx`, wrap the app in `<ThemeProvider attribute="class" defaultTheme="system" enableSystem>`.
  The `ThemeProvider` is a Client Component — create a wrapper `src/components/Providers.tsx` if
  the root layout must remain a Server Component.
- In `src/styles/global.css`, define CSS custom properties for both themes using the Tailwind v4
  `@theme` directive:
    - Light: `--color-bg: oklch(100% 0 0)`, `--color-text: oklch(9% 0 0)`.
    - Dark (inside `[class="dark"]` selector): override those variables.
  Apply them to the body as `background: var(--color-bg)` and `color: var(--color-text)`.
- Create `src/components/ThemeToggle.tsx` (Client Component) using `useTheme` from `next-themes`.
  It should cycle through light → dark → system on click and show a sun/moon/monitor icon.
  Use Tailwind's built-in `dark:` variant for icon visibility — do NOT use conditional classNames
  based on the `theme` string for icon color.
- Do not use `tailwind.config.ts` `darkMode: 'class'` — that is Tailwind v3 API. In v4, the
  `dark:` variant is class-based by default.
- Do NOT install lucide-react or any icon library — use SVG inline.

Stop and list all planned file changes before writing any code.

Implementierungshinweise

In Tailwind v4 funktioniert der Dark Mode über das dark:-Präfix mit der .dark-Klasse auf html automatisch – es ist kein Konfigurationseintrag erforderlich.
next-themes liest das gespeicherte Theme aus localStorage und setzt die Klasse vor dem ersten Rendern, was den FOUC verhindert.
Der ThemeProvider muss clientseitig sein, aber das root-layout.tsx kann serverseitig bleiben, indem der Provider in eine Providers.tsx-Wrapper-Komponente mit 'use client' ausgelagert wird.

Erwartete Dateiänderungen

src/app/layout.tsx                     (edited — add Providers wrapper)
src/components/Providers.tsx           (new — Client Component with ThemeProvider)
src/components/ThemeToggle.tsx         (new — Client Component)
src/styles/global.css                  (edited — CSS custom properties for light/dark)
package.json                           (edited — add next-themes)

Abnahmekriterien

Beim ersten Laden mit systemseitig eingestelltem Dark Mode wird die Seite dunkel ohne Aufblitzen gerendert.
Das Umschalten von ThemeToggle durchläuft die Modi Hell, Dunkel und System; die Präferenz bleibt beim Neuladen erhalten.
Alle vorhandenen dark: Tailwind-Dienstprogramme funktionieren ohne Konfigurationsänderungen.
bun run build beendet sich mit Exit-Code 0.

Testbefehle

bun add next-themes
bun run typecheck
bun run build
bun run dev
# open DevTools, set system dark mode, reload — confirm no white flash
# click ThemeToggle three times and confirm cycle: light → dark → system

Häufige KI-Fehler

Hinzufügen von darkMode: 'class' zu einer tailwind.config.ts, die in einem v4-Projekt nicht existiert.
Das root Server Component layout.tsx mit 'use client' umschließen, anstatt eine Providers-Komponente auszulagern.
Verwendung von theme === 'dark' für bedingtes Rendering anstelle der dark:-Variante von Tailwind, was zu Hydrierungsfehlern führt.
Vergessen von enableSystem auf ThemeProvider, sodass die Systempräferenz-Erkennung nicht funktioniert.

Fehlerbehebungs-Prompt

There's a white flash on load or a hydration mismatch. Fix in order:
1. Ensure `ThemeProvider` has `attribute="class"` and `enableSystem` props.
2. Make sure `Providers.tsx` (not `layout.tsx`) is marked `'use client'`.
3. Remove any `theme === 'dark'` conditional rendering from `ThemeToggle` — use `dark:` Tailwind
   variants instead so the server and client render the same HTML.
Show only the corrected diff.