Theme and Layout

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

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.

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

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:

WhereToggle
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 pageFloatingModeToggle (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:

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.

FileOwnerPurpose
styles/globals.csskitEntry: Tailwind 4, animations, shadcn variants and utilities (shadcn/tailwind.css), Inter font, imports the files below
styles/theme.cssyouColor tokens, radius, base styles
styles/custom.cssyouYour global styles
styles/shadcn-ui.csskitMaps tokens to Tailwind theme variables
styles/makerkit.csskitStyles 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).

Next: Error Pages →