Theme

Theme behavior is split between app/layout.tsx, lib/layout.shared.tsx, and app/globals.css. The provider stores the selected mode, the layout renders the switch, and CSS tokens determine how each mode looks.

Change the available modes

baseOptions() enables light, dark, and system choices:

themeSwitch: {
  mode: "light-dark-system",
},

The custom header also renders the same mode:

<ThemeSwitch mode="light-dark-system" />

Keep both values aligned. Use "light-dark" if the design should not expose the system option.

Set the initial appearance

RootProvider from fumadocs-ui/provider/next integrates next-themes. To pass provider options, configure its theme props in app/layout.tsx:

<RootProvider
  theme={{
    defaultTheme: "system",
    enableSystem: true,
  }}
>
  {children}
</RootProvider>

Adjust shape and density

The base radius drives derived Tailwind radius utilities:

:root {
  --radius: 0.5rem;
}

Use semantic utilities in components so changes stay global:

<aside className="rounded-lg border bg-card p-4 text-card-foreground" />

Best practices

• Test every customization in both modes and with the system setting.
• Use semantic tokens instead of literal colors in JSX.
• Preserve suppressHydrationWarning on <html>; the theme class is resolved in the browser.
• Maintain sufficient contrast for text, links, focus rings, and code.

Tip: Treat themes as token sets, not separate component implementations. This prevents light and dark modes from drifting apart.

See Colors for the palette and Typography for font tokens.