Theming

A project's colors, corner radius and typeface come from a theme — a preset baked into the compiler, an optional theme.toml, and an optional inline table.

Tokens resolve in color classes, so a project gets a semantic vocabulary — bg-card, text-muted-foreground, border-border — instead of hex literals scattered through its markup.

The three layers

Each layer overrides the one before it:

theme.toml is discovered, not registered — the way SvelteKit finds svelte.config.js. If the file is not there, the preset stands on its own.

Presets

# whitehall.toml
[theme]
preset = "shadcn"
base_color = "olive"    # optional; "neutral" if you say nothing

Which one Material moves

base_color picks one of shadcn's neutral ramps and only shadcn reads it. Material generates its schemes from a seed hue instead, which is a different idea, so the setting is ignored rather than rejected there — switch presets to compare without having to delete the line. To move Material's color, override the role:

[theme]
preset = "material3"

[theme.colors]
primary = "#00639B"

The 19 tokens the shadcn preset defines:

background          foreground
card                card-foreground
popover             popover-foreground
primary             primary-foreground
secondary           secondary-foreground
muted               muted-foreground
accent              accent-foreground
destructive         destructive-foreground
border              input                 ring

Base colors

The preset builds its palette on a base color — the neutral ramp every token except destructive is derived from. This is the same knob as tailwind.baseColor in shadcn's components.json: it swaps the neutral underneath the whole palette without changing any other decision. Say nothing and the app is gray; say olive and it is green.

These are shadcn's own seven, taken verbatim from the registry. A base color is a starting point, not a commitment — everything in theme.toml and [theme.colors] still overrides it token by token.

Switching base colors at runtime

base_color picks one ramp at build time, which is what an app with a look wants. An app that lets its user pick binds it on <App> instead, the same way theme= is bound:

// src/main.wh
import $app.stores.ThemeStore

<App theme={ThemeStore.mode} baseColor={ThemeStore.base}>
  <slot />
</App>

// src/stores/stores.wh
@store
object ThemeStore {
    var mode: String = "dark"
    var base: String = "neutral"
}

Writing ThemeStore.base = "olive" repaints the whole app, with no rebuild. Every ramp is emitted into WhitehallTheme.kt and chosen inside the composition, exactly as the two schemes already are.

theme.toml

Every field is optional; anything absent keeps its preset value.

# Which of shadcn's seven neutral ramps the palette is built on.
base_color = "neutral"

# Base corner radius, which drives the whole rounded-* scale.
# Accepts "0.625rem", "10px", "10dp", or a bare number in dp.
radius = "0.625rem"

# Tokens here apply to both schemes.
[colors]
ring = "neutral-400"

# ...and are overridden per scheme. Same cascade as shadcn's `:root` and `.dark`.
[colors.light]
background = "oklch(1 0 0)"
foreground = "#0a0a0a"
primary = "#171717"

[colors.dark]
background = "#0a0a0a"
foreground = "#fafafa"
primary = "#e5e5e5"

An unknown scheme ([colors.midnight]) is an error, not a silent drop. So is an unknown base_color.

The radius scale

radius is one number and every corner in the app is derived from it, so moving it reshapes the whole app at once — which is the point of having the setting. shadcn's multipliers:

rounded-none and the bare rounded are Tailwind's own and stay fixed, as does everything under preset = "none".

Font

font = "geist"              # geist | system | "static/Inter.ttf"

Geist ships inside the compiler (169 KB variable TTF, SIL OFL 1.1) and is written to res/font/ at build time. It is bundled rather than fetched from Google Fonts on purpose: a downloadable font needs the network on first run and flashes a fallback before it arrives. Projects that would rather trade a flash for 169 KB can set font = "system".

All nine weights are declared against the font's wght axis, so font-bold gets Geist's real bold rather than a synthesized smear of the Regular master. This needs API 26, which is min_sdk.

Color values

oklch is what shadcn and Tailwind v4 publish, so a theme copied from the shadcn registry pastes in unedited. Everything normalizes to #rrggbb or #rrggbbaa before codegen.

Inline overrides

For a single token, skip the file:

# whitehall.toml
[theme.colors]
primary = "#34d399"
muted-foreground = "neutral-400"

Inline values apply to both schemes and beat theme.toml.

Using tokens

Token names are used verbatim after bg-, text- and border-:

<Column class="bg-card border border-border rounded-lg p-16">
  <Text class="text-card-foreground text-lg font-bold">Total revenue</Text>
  <Text class="text-muted-foreground text-sm">+20.1% from last month</Text>
</Column>

Names may contain hyphens, which is what lets them mirror shadcn's vocabulary. Tokens keep working with an opacity suffix — bg-primary/50 is the lookup plus .copy(alpha = 0.5f).

Dark mode

Which scheme the app uses is declared on <App> in src/main.wh:

<App theme="dark">
  <slot />
</App>

"system" is accepted as a synonym for "auto", since that is what mode-watcher and next-themes call it. darkMode= is the previous spelling of this prop and still parses; theme= wins if both appear.

All four work at runtime. Theme tokens resolve inside the composition, so "auto" follows the device and a store binding follows the store, repainting live in both cases — no rebuild. The status bar icons follow the app's scheme too, not the device's.

The runtime token layer

Every build writes a WhitehallTheme.kt into the project package, holding the resolved palette as Compose Unstyled theme tokens:

object WhitehallTokens {
    val colors = ThemeProperty<Color>("colors")

    val background = ThemeToken<Color>("background")
    val mutedForeground = ThemeToken<Color>("muted-foreground")
    // ...
}

Both schemes are emitted, and which one is in force is decided inside the composition. Names are converted to Kotlin: muted-foreground becomes mutedForeground. Two tokens that would produce the same Kotlin name are a build error rather than a silent shadow.

Current limits

• The launch window follows the theme, but has no launch screen. The window Android draws before the app's first frame takes its color from background, per scheme. Drawing your own launch screen over it is designed but not built.
• Widgets and notifications have no theme. Glance runs in a different composition and cannot read the app's CompositionLocals, so src/widgets/ keeps the Tailwind palette and hex. This is a property of Glance, not a gap to be closed.
• Wear bakes its tokens. The Wear module has neither WhitehallTheme.kt nor the theming dependency, and draws with androidx.wear.compose, so a token in src/wear/ is the literal hex for the scheme the build picked. Pin theme= for a Wear app that uses tokens.
• A token named after a Material role shadows it. With a populated palette, bg-primary resolves to the project's primary rather than MaterialTheme.colorScheme.primary. That is the intent, but it means turning on a preset changes existing color classes.
• The single-file path has no theme. whitehall compile foo.wh does not read whitehall.toml, so color classes naming theme tokens are unknown-class errors there.

See Also

• Components — the shadcn component library the preset turns on
• Tailwind Classes — the full color-class reference