---
title: Theming
description: Start with Radiant UI's accessible default theme or add curated themes from Radiant Themes.
---

import { DesignTokenPanel } from '@/components/design-token-panel/design-token-panel';
import { RuiAlert, RuiAlertDescription, RuiAlertTitle } from '@ecopages/radiant-ui/alert';
import { RuiButton } from '@ecopages/radiant-ui/button';

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

# Theming

<p class="docs-lede">
	Radiant UI ships one accessible, carefully tuned default. The optional Radiant Themes package adds complete visual
	presets, each with its own palette, typography, spacing, shape, and component styling.
</p>

<DesignTokenPanel />

Try every theme on all components at once, pick fonts, and copy the install command and CSS for your choice in the [theme lab](/themes).

## Start with Radiant Default

Import the default theme and the component stylesheet in the application entry stylesheet. The default uses a cool,
soft neutral palette, near-Zed spacing (28, 32, and 36px controls), restrained corners, flat controls, and visible translucent borders.

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

## Install a complete theme

Install `@ecopages/radiant-ui` and `@ecopages/radiant-themes` to use GitHub, Cloudflare, VS Code, Vercel, Material Design,
High Contrast, Windows 95, Mac OS Classic, macOS, or Zed. Each theme owns its component shape, typography, spacing, colors,
and any component-specific details.

```sh
pnpm add @ecopages/radiant-ui @ecopages/radiant-themes
```

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

Compact entries are named per optional theme, such as `github/compact` and `windows95/compact`. For Radiant Default,
import `@ecopages/radiant-ui/tokens/spacing/compact` after `@ecopages/radiant-ui/themes/default`. Optional theme
entries reuse that theme's layer composition internally and apply the compact spacing preset; shared density changes
do not alter a branded theme's shape.

```css
@import 'tailwindcss';
@import '@ecopages/radiant-themes/material/compact';
@import '@ecopages/radiant-ui/styles.css';
```

The [theme lab](/themes) previews every full theme across all components. Theme, mode, fonts, and Radiant Default
tuner values are saved in the browser and can be shared with `rui-theme`, `rui-mode`, `rui-font-sans`,
`rui-font-heading`, `rui-font-mono`, and `rui-*` tuning query parameters. URL parameters override saved values, so
reloading a shared link keeps the same appearance. The seven tuner parameters are `rui-primary-hue`, `rui-secondary-offset`, `rui-neutral-hue`, `rui-neutral-tint`, `rui-density`,
`rui-radius`, and `rui-border-alpha`. Each theme import sets its own `--font-sans`, `--font-heading`, and `--font-mono`
stacks. Radiant does not bundle font files;
to use a custom licensed font, load it in your app and override those three variables:

```css
@font-face {
	font-family: 'Product Sans';
	src: url('/fonts/product-sans.woff2') format('woff2');
	font-display: swap;
}

:root {
	--font-sans: 'Product Sans', system-ui, sans-serif;
	--font-heading: var(--font-sans);
	--font-mono: ui-monospace, monospace;
}
```

High Contrast targets AAA contrast for published semantic text pairs and strengthens focus indicators. The default
also responds to reduced-motion, increased-contrast, and Windows forced-colors preferences. Check the whole interface
after custom role overrides, especially non-text boundaries and content supplied by your application.

## Tune Radiant Default

<RuiAlert class="unstyled" variant="info" layout="banner">
	<RuiAlertTitle>Customize Radiant Default in the theme lab</RuiAlertTitle>
	<RuiAlertDescription>
		{'Adjust hues, density, corner radius, border opacity, and fonts with live previews, then copy the CSS.'}
	</RuiAlertDescription>
	<RuiButton class="mt-3 self-start" href="/themes" variant="outline" size="sm">
		Open the theme lab
	</RuiButton>
</RuiAlert>

## Make a custom theme

Define semantic color roles in a stylesheet loaded after the base theme. Components consume semantic roles such as
`--primary` and `--on-surface`, not raw palette steps.

```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 / 20%);
	--focus-ring: var(--primary);
}
```

Dark mode changes theme colors and semantic role mappings. Every theme switches to dark when an ancestor has the
`dark` class, usually `<html class="dark">`; it does not follow `prefers-color-scheme` by itself, so set the class from
the user's preference in the app. A `.dark` section inside a light page restyles the components inside it. Toggle light/dark mode in the docs header to inspect every
theme in both schemes. See [Tokens](/docs/getting-started/tokens) for the semantic roles and scales.
