---
title: Tokens
description: Theme-aware color, spacing, radius, and supporting token scales used by Radiant UI components.
---

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

export const config = {
	dependencies: {
		components: [
			DesignTokenPanel,
			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 and geometry roles. Each
	complete theme supplies the palette and shape values behind those roles.
</p>

Click a swatch to copy its CSS variable. Values follow the selected complete theme and light/dark mode. Choose a
theme from the button beside the mode toggle, or use the gallery below.

## Theme gallery

Each theme brings its own palette and component treatment. Choose one here to preview its tokens and components across
this page, then open the [Theming guide](/docs/getting-started/theming) for package imports and the Radiant Default
color controls.

<DesignTokenPanel />

Available themes include Radiant Default, GitHub, Cloudflare, VS Code, Vercel, Material Design, High Contrast, Windows 95, Mac OS
Classic, macOS, and Zed. Each complete theme also has an individually exported compact variant, such as
`@ecopages/radiant-themes/github/compact`.

## 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. Radiant Default sets its own sizes; other packs alias the spacing scale. |

`themes/default.css` is the default import graph. It loads the Radiant Default palette, spacing and radius, elevation,
typography, motion, system tokens, and semantic roles. `tokens/foundation.css` contains the shared foundation tokens.

## 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` (`45%`), `--rui-track-fill`; optional `--rui-track-color` |

## Gray scale

`--gray-50` through `--gray-950` are the neutral scale exposed as Tailwind utilities (`bg-gray-50`, …). Each theme
maps this scale to its own neutral family; Radiant UI's default uses Radiant Default.

<GrayScaleSwatches />

## Source palettes

Palette files put raw colors on `:root`. Theme role files assign them to semantic roles. Component CSS must not
reference palette values such as `--color-carbon-blue-500` or `--color-github-blue`.

The Radiant Default scales are derived from OKLCH seed variables in `@ecopages/radiant-ui/themes/default`. Optional
palettes such as GitHub, Cloudflare, VS Code, Vercel, Material Design, High Contrast, Windows 95, Mac OS Classic, macOS, and Zed are provided by
`@ecopages/radiant-themes`. Hue scales that include step 975
ship steps 50–975; Vercel gray and the semantic gray scale end at 950. `--color-black` and `--color-white` are system
tokens, not a hue pack.

<PaletteSwatches />

## Spacing

Spacing uses `--space-1` through `--space-16` and five roles. Bars show the live computed size for the selected theme.
Radiant Default scales with its density control; each Radiant Themes compact export composes a denser spacing scale
while preserving the theme's own color, shape, and typography.

<SpacingSwatches />

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

<SpacingRoleSwatches />

| Token | Radiant Default | Tailwind `@theme` |
| --- | --- | --- |
| `--space-1` | 0.1875rem | `--spacing-1` |
| `--space-2` | 0.375rem | `--spacing-2` |
| `--space-3` | 0.625rem | `--spacing-3` |
| `--space-4` | 0.8125rem | `--spacing-4` |
| `--space-5` | 1rem | `--spacing-5` |
| `--space-6` | 1.25rem | `--spacing-6` |
| `--space-8` | 1.75rem | `--spacing-8` |
| `--space-10` | 2rem | not bridged |
| `--space-12` | 2.5rem | not bridged |
| `--space-16` | 3.25rem | not bridged |
| `--space-control-x` | `--space-3` | `--spacing-control-x` |
| `--space-control-y` | `--space-2` | `--spacing-control-y` |
| `--space-inline` | `--space-2` | `--spacing-inline` |
| `--space-stack` | `--space-4` | `--spacing-stack` |
| `--space-inset` | `--space-4` | `--spacing-inset` |

`--size-control-sm`, `--size-control-md`, and `--size-control-lg` are 1.75rem, 2rem, and 2.25rem (28, 32, and 36px) in
Radiant Default and follow `--rui-density`, so density affects button and input height as well as `--space-control-x`
padding. The `compact`, `comfortable`, and `wide` packs alias `--space-8`, `--space-10`, and `--space-12` instead.
Radiant Default also sets `--text-control` to 0.8125rem.

`--space-10`, `--space-12`, and `--space-16` exist as CSS variables but are not mapped in the spacing `@theme` bridge.
Use `var(--space-10)` or a role token when a value should follow the selected theme's density.

## Radius

Radius tokens 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`. Complete themes
provide their own shape values; only Radiant Default exposes `--rui-radius-scale` as a tuning input. `rounded-button`
aliases `--radius-control`.

<RadiusSwatches />

<RadiusRoleSwatches />

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

The shared type scale includes size, leading, weight, and tracking tokens. Complete themes provide `--font-sans`,
`--font-heading`, and `--font-mono`; the selected theme controls those stacks. Load the shared scale with
`@ecopages/radiant-ui/tokens/typography/default`, or import a complete theme to get its matching font families too.

<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-in` | `cubic-bezier(0.4, 0, 1, 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 theme roles can reference them without depending on a palette 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` | `45%` |
| `--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` | 1.75rem in Radiant Default; other packs alias `var(--space-8)` |
| `--size-control-md` | 2rem in Radiant Default; other packs alias `var(--space-10)` |
| `--size-control-lg` | 2.5rem in Radiant Default; other packs alias `var(--space-12)` |
| `--size-icon-sm` | 1rem |
| `--size-icon-md` | 1.25rem |

`accessibility.css` is part of the default foundation. It adds a base visible focus outline that component themes can
customize, honors `prefers-reduced-motion`, strengthens borders when `prefers-contrast: more` is enabled, and maps semantic colors to system colors under
`forced-colors: active`. High Contrast is available from [Theming](/docs/getting-started/theming) and targets AAA
contrast for the published semantic text pairs in light and dark modes.

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