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 is a stylesheet and an identity class. The stylesheet declares the theme's semantic values for the element that carries its identity class, and that class belongs on <html>. A document uses one theme at a time.

Luke UI provides two themes as separate packages, @luke-ui/theme-tactile and @luke-ui/theme-paper. A product can also compile its own theme with defineTheme.

The shared stylesheet, @luke-ui/react/stylesheet.css, sets the document baseline from the theme's tokens. It carries no theme identity.

Each theme includes light and dark colour values. Without an explicit data-color-mode, the document follows the system preference. data-color-mode on <html> fixes the mode for the whole document.

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 appearance, tone, prominence, size, and interaction behaviour. The theme supplies the semantic values behind those choices.

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

function SaveButton() {
	return <Button prominence="high">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