Theming

A single seed colour generates the full Material Design 3 token set for both light and dark modes.

How colour generation works

Under the hood, createMD3Theme uses Google's @material/material-color-utilities to derive tonal palettes from the HCT colour space. Each palette produces tokens at specific tone levels defined by the MD3 spec—e.g. primary is tone 40 in light mode and tone 80 in dark mode.

import { createMD3Theme } from "md3-next";

// One seed → full MD3 palette
const theme = createMD3Theme({ seed: "#006A6A" });

// Access raw tokens
theme.tokens.light.primary;          // hex string
theme.tokens.dark.primaryContainer;   // hex string

Choosing a seed colour

Your seed colour is your brand colour. The algorithm extracts its hue and chroma, then builds harmonious secondary and tertiary palettes automatically. A few examples:

Light, dark & system modes

Pass mode to createMD3Theme to set the initial preference. The MD3Provider resolves "system" at runtime using prefers-color-scheme. Users can switch at any time via setMode or toggleMode.

const { mode, setMode, toggleMode } = useMD3();

// mode is the resolved value: "light" | "dark"
// setMode("dark")  — explicit
// setMode("system") — follow OS
// toggleMode()      — flip light ↔ dark

Full token reference(showing light mode)

Typography scale

The MD3 type scale is mapped to MUI typography variants automatically: