# Theme and Layout

> The root layout, light/dark/system theming, theme colors and the UI components.

*Canonical: https://makerkit.dev/docs/void-cloudflare/configuration/theme*

---

Every page is wrapped by the root layout, and the theme is rendered on the server from a cookie, so pages never flash the wrong theme.

This page is part of the [Configuration documentation](./overview).

{% img src="/assets/images/docs/void-cloudflare/dashboard.png" width="1440" height="900" alt="The demo dashboard in light mode, within the application sidebar." /%}

The demo dashboard in light mode, within the application sidebar.

## Root Layout

`apps/web/pages/layout.tsx` (yours to edit) loads the global styles and wraps every page in:

- `ThemeProvider` from `@kit/ui/theme`
- the toast container, `Toaster` from `@kit/ui/sonner`

When `ENABLE_THEME_TOGGLE` is on, every section shows a theme toggle:

| Where | Toggle |
|---|---|
| `pages/(app)/` | The Theme submenu in the account menu (`apps/web/components/account-dropdown.tsx`) |
| `pages/auth/`, `pages/password-reset/`, `pages/invitation/`, `pages/email-change/`, `pages/onboarding/organization.tsx`, the 404 page | `FloatingModeToggle` (`apps/web/components/floating-mode-toggle.tsx`), top-right corner |
| `pages/(marketing)/` | The footer's bottom row, next to the language selector |

A page you add outside these folders has no toggle until you add `<FloatingModeToggle />` or give it a layout.

Pages can opt out or use another layout with Void's named layouts (`export const layout = 'name'` and `pages/_layouts/`).

## How the Theme Works

1. The user's choice (`light`, `dark` or `system`) is stored in the `theme` cookie by `ThemeProvider`.
2. `middleware/02.theme.ts` reads the cookie and sets the theme class on `<html>` in the server response, so the first paint is already right. (`middleware/05.locale.ts` sets `lang`.)
3. For `system`, the server renders `light` plus a tiny inline script that switches to `dark` before first paint if the OS prefers dark.
4. A missing or unrecognized cookie falls back to `DEFAULT_THEME_MODE`. With `ENABLE_THEME_TOGGLE=false`, the cookie is ignored and everyone gets `DEFAULT_THEME_MODE`.

The cookie name, the allowed values and the parsing live in one place, `@kit/ui/theme`, used by both the server and the browser.

In components:

```tsx
import { useTheme } from '@kit/ui/theme';

const { theme, resolvedTheme, setTheme } = useTheme();
```

Ready-made toggles: `ModeToggle` and `SubMenuModeToggle` (`@kit/ui/mode-toggle`), `MobileModeToggle` (`@kit/ui/mobile-mode-toggle`). Their labels are kit messages under `theme` in `packages/i18n/src/messages/<locale>/common.json`.

## Colors and Tokens

Theme colors are CSS variables in `apps/web/styles/theme.css` (yours): `:root` for light, `.dark` for dark. Components use semantic Tailwind classes (`bg-background`, `text-foreground`, `text-muted-foreground`), so changing the variables re-themes everything.

The landing page hero is a dark panel in both themes, coloured by `--hero-background` (one value in `:root`, one in `.dark`). Pick any dark colour, e.g. `--hero-background: oklch(0.3 0.15 265);` for deep blue: the text, pill and buttons on it stay light.

| File | Owner | Purpose |
|---|---|---|
| `styles/globals.css` | kit | Entry: Tailwind 4, animations, shadcn variants and utilities (`shadcn/tailwind.css`), Inter font, imports the files below |
| `styles/theme.css` | you | Color tokens, radius, base styles |
| `styles/custom.css` | you | Your global styles |
| `styles/shadcn-ui.css` | kit | Maps tokens to Tailwind theme variables |
| `styles/makerkit.css` | kit | Styles for Makerkit components |

Tailwind scans `packages/*/src`, `apps/web/pages` and `apps/web/components` for classes. Add a `@source` line in `globals.css` if you put components elsewhere.

## UI Components

Import components from `@kit/ui/<name>` (e.g. `@kit/ui/button`, `@kit/ui/card`, `@kit/ui/dialog`). They are shadcn components in the `base-mira` style, built on Base UI, plus Makerkit components. Rules for changing or adding them are in `packages/ui/AGENTS.md`; the main one is never to edit `packages/ui/src/shadcn/`, which is regenerated by the shadcn CLI.

## Common Pitfalls

- Using `next-themes`: it isn't installed; use `useTheme` from `@kit/ui/theme`.
- Hard-coding colors (`bg-white`, `text-black`): they don't follow dark mode. Use the semantic classes.
- Reading the theme from `localStorage`: the server can't see it, so the first paint would be wrong.
- Worrying about the inline system-theme script and the Content Security Policy: the security middleware gives every script in the server's response the nonce, so there is nothing to configure ([Content Security Policy](../security/content-security-policy)).

---

**Next:** [Error Pages →](./error-pages)
