Dark mode

Follow the user's preference

PimoluProvider supports light, dark and system. System resolves the browser's prefers-color-scheme preference. Use usePimoluTheme to change the mode and read resolvedTheme when you need a concrete light or dark value.

"use client";

import { Button, usePimoluTheme } from "@pimolu/react";

export function ColorModeButton() {
  const { resolvedTheme, setTheme } = usePimoluTheme();
  return (
    <Button
      appearance="outline"
      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
    >
      Switch to {resolvedTheme === "dark" ? "light" : "dark"} mode
    </Button>
  );
}

Keep the first render consistent

For a saved explicit preference in Next.js, validate its cookie on the server and pass the same initial value to the client Provider. This website's SiteProvider and lib/preferences.ts are working references.

Render the same application structure on the server and client. Avoid reading window or matchMedia during the server render, and do not suppress hydration errors to conceal a mismatch.

Review every surface

Use semantic CSS variables instead of maintaining separate hardcoded application palettes. Inspect fields, borders, disabled states, images, overlays and focus in both modes. Changing the mode must not reset application state or hide information.