Tokens
Radiant UI tokens are CSS custom properties in three tiers. Components consume semantic roles and geometry roles. Palette steps exist so colour presets can remap those roles; they are not a component API.
Click a swatch to copy the CSS variable name. Colour, spacing, and radius swatches follow the live docs preview (colour profile, spacing pack, radius pack, and light or dark). Change packs on Theming.
Token tiers
| Tier | What it is | Public contract |
|---|---|---|
| 1. Packs | Raw scales: colour palettes, --space-*, --border-radius-*, elevation, type, motion | Import a pack stylesheet. Do not target palette steps from component CSS. |
| 2. Semantic | --primary, --surface, --error, … plus the Tailwind @theme bridge (bg-primary) | This is what components use. |
| 3. System | Absolute colours (--color-black, --color-white), border widths, focus ring geometry, opacity, z-index, control sizes | Shared by every theme; not a mood pack. |
A theme file is only an import graph. The default foundation loads palettes, default spacing, default radius, elevation, typography, motion, system tokens, and semantic roles.
Colour roles
These are the roles components consume. Tailwind utilities map from the same names: --primary → bg-primary,
text-on-primary, border-primary. Pair chips show the on-* colour as text on the fill.
destructive is an alias of error (--color-destructive: var(--error)). Use error for status surfaces and
destructive for destructive actions such as buttons.
Tertiary has fill and container roles only. It does not ship --tertiary-light or --tertiary-dark.
Brand
Primary, secondary, and tertiary families. Components consume these roles, not palette steps.
Status
Notification and validation families. destructive aliases error.
Surfaces
Page and container backgrounds with matching on-colours.
Supporting
Chrome, focus, links, overlays, and code surfaces.
| Family | CSS variables |
|---|---|
| Brand | --primary, --on-primary, --primary-container, --on-primary-container, --primary-light, --primary-dark, --secondary, --on-secondary, --secondary-container, --on-secondary-container, --secondary-light, --secondary-dark, --tertiary, --on-tertiary, --tertiary-container, --on-tertiary-container |
| Status | --error, --on-error, --error-container, --on-error-container, --error-light, --error-dark, --success, --on-success, --success-container, --on-success-container, --success-light, --success-dark, --info, --on-info, --info-container, --on-info-container, --info-light, --info-dark, --warning, --on-warning, --warning-container, --on-warning-container, --warning-light, --warning-dark |
| Surfaces | --background, --on-background, --surface, --on-surface, --surface-container-lowest, --on-surface-container-lowest, --surface-container-low, --on-surface-container-low, --surface-container, --on-surface-container, --surface-container-high, --on-surface-container-high, --surface-container-highest, --on-surface-container-highest |
| Supporting | --border, --focus-ring, --link, --overlay, --neutral, --background-code, --on-background-code |
Gray scale
--gray-50 through --gray-950 are the only numeric colour scale exposed as Tailwind utilities (bg-gray-50, …).
Presets remap this scale onto a pack's neutrals (Glacier White, Pale Sky, Basalt, …).
Source palettes
Palette files put raw scales on :root. Colour presets then assign those steps to semantic roles. Component CSS must
not reference palette steps such as --color-night-sky-500 or --color-havelock-blue-800.
All three packs load together via @ecopages/radiant-ui/tokens/colors/palettes. Every named hue ships steps
50–975. --color-black and --color-white are system tokens, not a hue pack. The gray utility scale above is a
separate contract (50–950, remapped per colour profile).
Glacier
@ecopages/radiant-ui/tokens/colors/glacier
Aurora
@ecopages/radiant-ui/tokens/colors/aurora
Basalt
@ecopages/radiant-ui/tokens/colors/basalt
Spacing
Spacing packs set --space-1 through --space-16 and five roles. Bars show the live computed size, so compact and
wide change the preview.
Roles are what component CSS should use for control padding and stack rhythm:
| Token | Default | Compact | Wide | Tailwind @theme |
|---|---|---|---|---|
--space-1 | 0.25rem | 0.125rem | 0.375rem | --spacing-1 |
--space-2 | 0.5rem | 0.25rem | 0.625rem | --spacing-2 |
--space-3 | 0.75rem | 0.5rem | 0.875rem | --spacing-3 |
--space-4 | 1rem | 0.75rem | 1.25rem | --spacing-4 |
--space-5 | 1.25rem | 1rem | 1.5rem | --spacing-5 |
--space-6 | 1.5rem | 1.25rem | 1.875rem | --spacing-6 |
--space-8 | 2rem | 1.5rem | 2.5rem | --spacing-8 |
--space-10 | 2.5rem | 2rem | 3rem | not bridged |
--space-12 | 3rem | 2.5rem | 3.75rem | not bridged |
--space-16 | 4rem | 3rem | 5rem | not bridged |
--space-control-x | --space-3 | --space-3 | --space-4 | --spacing-control-x |
--space-control-y | --space-2 | --space-2 | --space-3 | --spacing-control-y |
--space-inline | --space-2 | --space-2 | --space-3 | --spacing-inline |
--space-stack | --space-4 | --space-3 | --space-6 | --spacing-stack |
--space-inset | --space-4 | --space-4 | --space-6 | --spacing-inset |
Important: --space-10, --space-12, and --space-16 exist as CSS variables but are not mapped in the spacing
@theme bridge. p-10 is not the Radiant pack step; use var(--space-10) or a role token when the value must follow
compact or wide.
@import '@ecopages/radiant-ui/tokens/spacing/compact';Radius
Radius packs set --border-radius-* and three roles: --radius-control, --radius-container, --radius-pill.
The @theme bridge exposes rounded-sm, rounded-control, rounded-container, and rounded-pill. rounded-button
aliases --radius-control.
| Pack | Import |
|---|---|
| Default | @ecopages/radiant-ui/tokens/radius/default |
| Soft | @ecopages/radiant-ui/tokens/radius/soft |
| Sharp | @ecopages/radiant-ui/tokens/radius/sharp (edgy is the same pack) |
Elevation
| Token | Use |
|---|---|
--shadow-control | Resting controls |
--shadow-overlay | Popovers, menus, dropdowns |
--shadow-modal | Dialogs |
The flat pack sets all three shadows to none: @ecopages/radiant-ui/tokens/elevation/flat.
Typography
Size tokens plus --font-sans, --font-mono, --leading-*, --weight-*, and --tracking-wide. Default pack:
@ecopages/radiant-ui/tokens/typography/default.
| Token | Default |
|---|---|
--text-xs | 0.75rem |
--text-sm | 0.875rem |
--text-body | 1rem |
--text-label | 0.875rem |
--text-control | 0.875rem |
--text-lg | 1.125rem |
--text-xl | 1.25rem |
--text-2xl | 1.5rem |
--text-3xl | 1.875rem |
--text-4xl | 2.25rem |
Motion
| Token | Default | Snappy |
|---|---|---|
--duration-fast | 150ms | 100ms |
--duration-normal | 200ms | 150ms |
--duration-slow | 300ms | 200ms |
--ease-standard | cubic-bezier(0.4, 0, 0.2, 1) | same |
--ease-out | cubic-bezier(0, 0, 0.2, 1) | same |
@import '@ecopages/radiant-ui/tokens/motion/snappy';System
Shared structural tokens from @ecopages/radiant-ui/tokens/system. Not a swappable mood pack. Absolute black and
white live here so colour presets can reference them without depending on the Aurora pack.
| Token | Value |
|---|---|
--color-black | oklch(0% 0 0) |
--color-white | oklch(100% 0 0) |
--border-width-hairline | 1px |
--border-width-thin | 1px |
--border-width-thick | 2px |
--focus-ring-width | 2px |
--focus-ring-offset | 2px |
--opacity-disabled | 0.5 |
--opacity-muted | 0.6 |
--z-dropdown | 10 |
--z-popover | 20 |
--z-overlay | 30 |
--z-modal | 40 |
--z-toast | 50 |
--size-control-sm | 2rem |
--size-control-md | 2.5rem |
--size-control-lg | 3rem |
--size-icon-sm | 1rem |
--size-icon-md | 1.25rem |
Compose packs in the application stylesheet. See Theming.