# Theming (/docs/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 [#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](/docs/applying-a-theme) for the exact imports, classes, and colour-mode
rules.

## Component variants [#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.

```tsx
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 [#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](/docs/token-reference) for the full contract. Read [Colour](/docs/color) for
the semantic roles it exposes.

## Continue learning [#continue-learning]

<Cards>
  <Card href="/docs/applying-a-theme" title="Applying a theme">
    Load the CSS, set the root classes, and preserve them through portals.
  </Card>

  <Card href="/docs/color" title="Colour">
    Choose semantic surfaces and roles for custom UI.
  </Card>

  <Card href="/docs/authoring-a-theme" title="Authoring a theme">
    Compile a product-owned stylesheet from a curated `defineTheme` input.
  </Card>

  <Card href="/docs/token-reference" title="Token reference">
    Browse the public semantic CSS variables for custom UI.
  </Card>
</Cards>