Theming and dark mode

The dashboard supports a light and a dark theme, and each studio can override the brand colour and font. All three layers meet in CSS custom properties.

How the theme is chosen

next-themes is configured in the root layout:

<ThemeProvider
	attribute="class"
	disableTransitionOnChange
	enableSystem
	defaultTheme={config.defaultTheme}
	themes={Array.from(config.enabledThemes)}
>

apps/saas/config.ts sets enabledThemes: ["light", "dark"] and defaultTheme: "dark".
attribute="class" puts .dark on the html element.
globals.css declares @variant dark (&:where(.dark, .dark *));, so Tailwind’s dark: variant follows that class and not the OS preference.

ColorModeToggle (in the user menu and on the auth pages) switches the theme.

Tokens

Base tokens

frontend/tooling/tailwind/theme.css (package @repo/tailwind-config) defines the tokens under :root and .dark, then maps each to a Tailwind colour in an @theme block.

Token	Tailwind utility	Light	Dark
`--background`	`bg-background`	`#f4f5f7`	`#0e0e14`
`--foreground`	`text-foreground`	`#18181b`	white
`--card`	`bg-card`	`#ffffff`	`#1d1d29`
`--popover`	`bg-popover`	`#ffffff`	`#1d1d29`
`--primary`	`bg-primary`, `text-primary`	`#18181b`	white
`--primary-foreground`	`text-primary-foreground`	`#ffffff`	`#1d1d29`
`--secondary`, `--muted`	`bg-secondary`, `bg-muted`	`#eef0f3`	`#2a2a38`, `#1d1d29`
`--muted-foreground`	`text-muted-foreground`	`#6b6b73`	`#a3a3b2`
`--accent`	`bg-accent`	`#f1f2f5`	`#2a2a38`
`--border`	`border-border`	`#e5e7eb`	`#2a2a38`
`--input`	`border-input`	`#d3d7dd`	`#2a2a38`
`--ring`	`ring-ring`	`#18181b`	`#7b7b8c`
`--destructive`	`bg-destructive`	`#dc2626`	red 600
`--success`	`bg-success`, `text-success`	`#16a34a`	emerald 600
`--line-soft`	`border-line-soft`	`#edeff2`	`#232330`
`--bg-1`	`bg-bg-1`	`#fafbfc`	`#1a1a25`
`--radius`	`rounded-lg` and the derived scale	`0.875rem`	same

--line-soft is a divider softer than the hairline. --bg-1 is an inset surface between the page and a card. The radius scale is derived: --radius-sm is 0.6 of --radius, --radius-md 0.8, --radius-lg 1, up to --radius-4xl at 2.6. --font-display resolves to Heebo (--font-heebo from the root layout) and is used through font-display on headings.

App level overrides

apps/saas/app/globals.css imports the base theme and adds a few tokens of its own:

Token	Light	Dark	Use
`--sidebar`	`#ffffff`	`#15151f`	`bg-sidebar` on the nav
`--set-working`	`#18181b`	`#e8e8ef`	The neutral “working set” chip in the program builder
`--set-working-ink`	`#ffffff`	`#15151f`	Its text

It also re-points three dark tokens: --background to #15151f, and --card and --popover to #1e1e2b. So the dark surfaces the dashboard actually paints are those values, not the ones in theme.css.

Global base rules

Also in globals.css:

Every border defaults to var(--border).
svg.lucide gets stroke-width: 1.5.
cursor: pointer is set once for enabled buttons, [role="button"], [role="tab"], links with href, label[for] and summary. Disabled controls get cursor: not-allowed. Do not set cursors per element.
A container utility (centered, max-width 7xl, 1.5rem inline padding) and a no-scrollbar utility.

Studio branding

Each studio’s Branding record is stored by the core API on the studio. OrgTheme injects it as a style tag on every studio page. brandingCss(branding) in modules/shared/lib/branding.ts emits overrides for both themes:

Branding field	Tokens overridden	Themes
`primaryColor`	`--primary`, `--color-primary`, `--primary-foreground`, `--color-primary-foreground`, `--ring`, `--color-ring`	light and dark
`radius`	`--radius`	light and dark
`fontFamily`	`--font-sans` with `!important`	light and dark
`logoScale`	`--brand-logo-scale`	light and dark
`secondaryColor`	`--secondary`, `--color-secondary` and their foregrounds	light only
`accentColor`	`--accent`, `--color-accent` and their foregrounds	light only

Both the semantic token and its --color-* twin are set. Tailwind 4 resolves --color-* at :root, so a preview that scopes overrides to a wrapper element has to set the --color-* variables directly. Supporting functions in the same file:

parseBranding(raw) validates the untyped JSON from the API. Colours must match a hex pattern, anything invalid becomes null.
readableForeground(hex) picks black or white text for a background by luminance.
googleFontHref(fontFamily) returns a Google Fonts stylesheet URL for fonts in FONT_OPTIONS.
FONT_OPTIONS, PRESET_PALETTES, HOME_THEMES (classic, glass, poster, bento) feed the branding editor.

Because the primary colour is a studio choice, never assume bg-primary is dark or light. Pair it with text-primary-foreground.

Writing themed UI

Use tokens for every neutral:

Need	Use
Page background	`bg-background`
Card, panel, dialog	`bg-card`
Inset area inside a card	`bg-bg-1` or `bg-muted`
Body text	`text-foreground`
Secondary text	`text-muted-foreground`
Border	`border-border`, or `border-line-soft` for a softer divider
Hover on a neutral control	`hover:bg-accent`

Saturated brand and status colours (a blue badge, an orange warning) may be literals. They read on both themes. When a tint is pale, give it a dark counterpart on the same element:

// coaches/team-permissions.ts
trainees: "bg-[#e8f1fe] text-[#2563eb] dark:bg-blue-400/15 dark:text-blue-300",

For CSS written outside Tailwind (a feature stylesheet or a CSS string), declare a custom property and re-point it under .dark in the same file. No shadows on in page containers. Separate surfaces with a border.

The theme check

frontend/tools/check-theme-tokens.mjs (pnpm check:theme) fails when a themed surface uses a colour that only works in one theme.

What it scans

Roots: apps/saas/ and packages/ui/. The marketing app is out of scope. It has a fixed palette and no dark mode.
Files: .ts, .tsx, .css. Ignores node_modules, .next, .turbo, dist, generated, public.
Comment lines are skipped.

What it flags

Pattern	Message
`bg-white` with no `dark:bg-*` on the line. `bg-white/40` style scrims are allowed	Use `bg-card` or `bg-background`, or pair it with `dark:bg-*`
`text-black` with no `dark:text-*` on the line	Use `text-foreground`
`bg-` or `border-` with a 50, 100 or 200 shade of any Tailwind colour family, with no `dark:` on the line	A pale tint needs a `dark:` counterpart
A hex literal with lightness 0.85 or higher, with no `dark:` on the line	Near white literal: use a token
A hex literal with saturation under 0.12 and lightness 0.22 or lower, with no `dark:` on the line	Near black neutral: use `text-foreground` or a token that inverts

Pure #fff, #ffffff, #000 and #000000 are always allowed. A saturated dark colour is allowed, because it still reads on the dark shell.

Escapes

A themed custom property. Declaring --my-surface: #fafafa is fine when the same file also declares --my-surface under a .dark selector. The script parses the file for properties declared inside .dark blocks.
theme-ok. A comment containing theme-ok: <reason> on the line, or within the three lines above it, silences the finding. Three lines is enough to sit above an opening tag and its className.
ALWAYS_ONE_THEME. A list of files and patterns that are one fixed palette on purpose. Each entry needs a comment saying why.

Current exemptions: the mobile preview theme and branding files, BrandingView, the home banner CTA styles, every *AppPreview.tsx, HomeSkins, the form builder’s simulator files, everything under app/(start)/, PlanGaugePicker, the AutoFit sync bar, SmartsendLogo, the select-size-preview harness and all .test.ts files. They paint the trainee app, a standalone branded flow, or a third party logo.

When it runs

Hook	Command
Pre-commit (lint-staged)	`node tools/check-theme-tokens.mjs` on staged `.ts`, `.tsx` and `.css` files under `apps` and `packages`
Pre-push	`node tools/check-theme-tokens.mjs` over the whole tree, before oxlint
Manual	`pnpm check:theme`, or pass file paths to scan only those

It is not a step in .github/workflows/ci.yml.

Phone previews

Components that draw the trainee app inside the dashboard use APP_DARK and APP_LIGHT from modules/shared/lib/mobile-preview-theme.ts with inline styles. They show the app’s palette whatever the dashboard theme is. That is why they are exempt from the check, and why ClientAppPhoneFrame takes a theme prop instead of reading tokens.

​How the theme is chosen

​Tokens

​Base tokens

​App level overrides

​Global base rules

​Studio branding

​Writing themed UI

​The theme check

​What it scans

​What it flags

​Escapes

​When it runs

​Phone previews