Theming

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.

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.

@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. It uses data-rui-colors to switch profiles at runtime so you can compare combinations. 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. Compact preserves control heights for touch and keyboard usability; it tightens rhythm and padding rather than shrinking hit areas. Choose soft for generous rounding or sharp for square containers. edgy is a stylesheet alias for the sharp radius pack.

@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.

@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 page.

: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 for the spacing scale, radius scale, and every semantic colour role.