Theming

A theme supplies the semantic values used by Luke UI components and custom UI. It is static CSS and does not change component behaviour.

Theme foundations

A theme stylesheet themes the whole document from :root. Import one theme stylesheet, and every element uses its semantic values, with no class applied and no JavaScript.

rootClassName applies the shared reset and base typography. It carries no theme identity. Apply it to an element you already own, such as the application shell.

Each theme includes light and dark colour values. The active colour mode chooses between them. An explicit data-color-mode is optional. Without one, the theme follows the system preference. Colour-mode scopes nest freely. Theme identities do not. A nested theme identity resolves its own identity-owned values correctly, and its colour, depth, and action-control-finish values also resolve correctly under the system-controlled mode. An explicit data-color-mode scope on or inside the nested identity makes those mode-dependent values compete with the ancestor identity at equal precedence, so stylesheet order decides the winner.

Loading more than one theme in the same document needs an explicit identity class, so one theme wins over the other's :root fallback.

Read Applying a theme for the exact imports, classes, and colour-mode rules.

Component variants

Components define the choices available within the theme. For example, Button owns its tone, appearance, size, and interaction behaviour. The theme supplies the semantic values behind those choices.

import { Button } from '@luke-ui/react/button';

function SaveButton() {
	return (
		<Button appearance="solid" tone="accent">
			Save changes
		</Button>
	);
}

Prefer component props over custom CSS. Author a theme when the product needs a different visual foundation across the system.

Semantic tokens

The active theme exposes a typed, public vars contract. Use it when a custom element sits beside Luke UI components.

Read Token reference for the full contract. Read Colour for the semantic roles it exposes.

Continue learning