---
title: Tokens
description: Colour, spacing, radius, and supporting token scales that Radiant UI components consume.
group: Getting started
---

import {
	AbsoluteColorSwatches,
	ElevationSwatches,
	GrayScaleSwatches,
	PaletteSwatches,
	RadiusRoleSwatches,
	RadiusSwatches,
	SemanticColorSwatches,
	SpacingRoleSwatches,
	SpacingSwatches,
	TypographySwatches,
} from '@/components/token-swatches/token-swatches';

export const config = {
	dependencies: {
		components: [
			AbsoluteColorSwatches,
			ElevationSwatches,
			GrayScaleSwatches,
			PaletteSwatches,
			RadiusRoleSwatches,
			RadiusSwatches,
			SemanticColorSwatches,
			SpacingRoleSwatches,
			SpacingSwatches,
			TypographySwatches,
		],
		scripts: ['./tokens.script.ts'],
	},
};

# Tokens

<p class="docs-lede">
	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.
</p>

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](/docs/getting-started/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 and icon sizes | Shared by every theme; not a mood pack. `--size-control-*` aliases the spacing scale. |

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

<SemanticColorSwatches />

| 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`, `--on-focus-ring`, `--link`, `--overlay`, `--neutral`, `--background-code`, `--on-background-code` |
| Range tracks | `--rui-track-mix` (`22%`), `--rui-track-fill`; optional `--rui-track-color` |

## 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, …).

<GrayScaleSwatches />

## 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).

<PaletteSwatches />

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

<SpacingSwatches />

Roles are what component CSS should use for control padding and stack rhythm:

<SpacingRoleSwatches />

| 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` |

`--size-control-sm`, `--size-control-md`, and `--size-control-lg` alias `--space-8`, `--space-10`, and `--space-12`, so
compact and wide change button and input height on the block axis as well as `--space-control-x` padding.

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.

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

<RadiusSwatches />

<RadiusRoleSwatches />

| 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

<ElevationSwatches />

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

<TypographySwatches />

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

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

<AbsoluteColorSwatches />

| 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 |
| `--rui-track-mix` | `22%` |
| `--rui-track-fill` | `color-mix` of `--on-background` at `--rui-track-mix` |
| `--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` | `var(--space-8)` (2rem / 1.5rem / 2.5rem) |
| `--size-control-md` | `var(--space-10)` (2.5rem / 2rem / 3rem) |
| `--size-control-lg` | `var(--space-12)` (3rem / 2.5rem / 3.75rem) |
| `--size-icon-sm` | 1rem |
| `--size-icon-md` | 1.25rem |

Compose packs in the application stylesheet. See [Theming](/docs/getting-started/theming).