---
title: Theming
description: Compose colour, spacing, and radius packs into a Radiant UI foundation.
group: Getting started
---

import { DesignTokenPanel } from '@/components/design-token-panel/design-token-panel';

export const config = {
	dependencies: {
		components: [DesignTokenPanel],
		scripts: ['./theming.script.ts'],
	},
};

# Theming

<p class="docs-lede">
	A Radiant UI theme is an import graph: colour, spacing, radius, elevation, typography, and motion packs plus
	semantic roles. Choose the combination once in the application stylesheet. Components consume the resulting roles,
	not a named palette.
</p>

<DesignTokenPanel />

## Start with the foundation

Import the default foundation and the component stylesheet in the application entry stylesheet. The default theme is
Glacier with the default spacing and radius packs.

```css
@import '@ecopages/radiant-ui/themes/default';
@import '@ecopages/radiant-ui/styles.css';
```

## Explore colour profiles

The live preview includes Glacier, Basalt, Ember, and Aurora. Aurora is the vivid, expressive option; the other
profiles are more restrained. Ember remaps Glacier neutrals to a warm accent; it is a preset, not a separate palette
file.

Important: this preview is documentation-only. Colour profiles switch with `data-rui-colors`. Spacing and radius
inject the published pack stylesheets at runtime, the same files an application would `@import`. Those attributes
are not a supported application API.

## Layer spacing and shape

Use `compact` where information density matters and `wide` where composition needs more air. Both packs scale
`--size-control-*` with `--space-8`, `--space-10`, and `--space-12`, so buttons and inputs change height as well as
padding. Choose `soft` for generous rounding or `sharp` for square containers. `edgy` is a stylesheet alias for the
sharp radius pack.

```css
@import '@ecopages/radiant-ui/tokens/spacing/compact';
@import '@ecopages/radiant-ui/tokens/radius/soft';
```

## Compose the packs you need

Layer a spacing or radius pack after the foundation when a product needs a distinct density or shape. Select only the
packs the product needs rather than starting from a named full preset.

```css
@import '@ecopages/radiant-ui/themes/default';
@import '@ecopages/radiant-ui/tokens/spacing/compact';
@import '@ecopages/radiant-ui/tokens/radius/soft';
@import '@ecopages/radiant-ui/styles.css';
```

## Build a custom colour theme

Define semantic colour roles in a stylesheet loaded after the base token packs. Components consume these roles (`bg-primary`,
`text-on-surface`, …), not palette steps such as `night-sky-500`.

Override the roles your product needs. A complete list, with live swatches, is on the [Tokens](/docs/getting-started/tokens)
page.

```css
:root {
  --primary: oklch(52% 0.19 264);
  --on-primary: oklch(100% 0 0);
  --primary-container: oklch(93% 0.04 264);
  --on-primary-container: oklch(30% 0.11 264);

  --background: oklch(98.2% 0.004 265);
  --on-background: oklch(22% 0.008 265);
  --surface: oklch(96% 0.006 265);
  --on-surface: var(--on-background);
  --border: oklch(74% 0.012 265);
  --focus-ring: var(--primary);
}
```

Dark mode remaps colour roles only. Spacing, radius, elevation, typography, and motion stay mode-independent unless a
theme documents otherwise. Toggle dark mode in the docs header to preview the current profile's dark remaps.

See [Tokens](/docs/getting-started/tokens) for the spacing scale, radius scale, and every semantic colour role.