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.
Click to expandThe 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:
ThemeProviderfrom@kit/ui/theme- the toast container,
Toasterfrom@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
- The user's choice (
light,darkorsystem) is stored in thethemecookie byThemeProvider. middleware/02.theme.tsreads the cookie and sets the theme class on<html>in the server response, so the first paint is already right. (middleware/05.locale.tssetslang.)- For
system, the server renderslightplus a tiny inline script that switches todarkbefore first paint if the OS prefers dark. - A missing or unrecognized cookie falls back to
DEFAULT_THEME_MODE. WithENABLE_THEME_TOGGLE=false, the cookie is ignored and everyone getsDEFAULT_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.
| 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; useuseThemefrom@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 →