Themes

Five palettes over one set of components. Each theme authors 30 values; the 69 semantic names every component reads stay the same, so swapping a theme never touches component source. Below is every shipped palette, light and dark.

Compare

Try one here

This picker repaints the whole documentation site, including the specimen below, so you can read a theme in a real interface before installing it.

Every theme supplies 30 palette values and inherits the same 69 semantic names. The CLI also installs the shared type, spacing, border, and radius foundation. Components consume 28 palette values through the semantic layer; --tone-8 and --tone-9 are reserved for neutral-ramp compatibility and future deep-ink roles.

The CLI writes the foundation, semantic layer, and selected palette directly into the CSS file you choose during setup.

npx @beaket/ui init --theme solace
# Later, switch the saved project to another theme
npx @beaket/ui theme --theme tobacco

Dark mode

Every theme ships with a dark twin. Once the CLI has written the tokens, dark mode works automatically — no flags, no extra imports, no toggle configuration required.

How it works

The CSS written by the CLI contains both light and dark values. With no data-theme attribute on <html>, @media (prefers-color-scheme: dark) follows the OS. Set data-theme="light" or data-theme="dark" to force a scheme; remove the attribute for system mode. Your app owns persistence and applying the attribute before first paint, for example through a cookie read by your server layout.

document.documentElement.dataset.theme = "dark";
document.documentElement.dataset.theme = "light";
delete document.documentElement.dataset.theme; // system

Customize safely

The marked block is managed: theme regenerates it. Put brand overrides in the generated stub after beaket:theme:end. Keep its explicit light, system-dark and forced-dark selectors: plain :root has lower specificity than the generated dark selectors. The stub is emitted once and preserved on later syncs.

npx @beaket/ui theme --theme tobacco --diff
npx @beaket/ui theme --theme tobacco --dry-run
# Review, then apply (confirmation defaults to No)
npx @beaket/ui theme --theme tobacco

Both preview flags leave CSS, config and backups untouched. A stored managed-block hash detects local edits; replacement saves a numbered backup. --overwrite explicitly skips confirmation. Generated CSS also honors prefers-reduced-motion, shortening animations and transitions, including pseudo-elements. Spacing uses Tailwind's existing 4px utility scale, not a separate custom scale.

Docs preview controls

The theme picker in this documentation site is a local preview implementation, not an @beaket/ui CSS API. It reads theme from the URL and beaket-theme / beaket-color-scheme from this site's localStorage, then injects the generated token values onto the document before paint. Those keys affect this documentation site only; importing a package palette does not read them.

The consumer contract is the root data-theme attribute in CLI-generated CSS, not this site's storage keys. Raw source palettes remain the light/dark authoring inputs.