Radix Themes

---
name: radix-themes
description: Apply the Radix Themes visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Radix Themes, mentions Radix, Radix UI Themes, Radix Colors, or describes 12-step color scales with per-step roles, indigo/slate default palette, steps 9-10 solid, 11 text, 12 high-contrast — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Radix Themes Design System

The open-source theme layer over Radix Primitives: 12-step color scales (indigo accent + slate gray by default) where each step has a defined job, automatic light/dark fidelity, translucent panels, a 9-size type scale on a system font stack, and accessibility inherited from headless primitives — the quiet, engineered look behind much of the modern React ecosystem.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values come from the officially published token set. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Radix Themes.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (Radix, Radix UI Themes, Radix Colors, radix-ui), or describes its traits: 12-step color scales with per-step roles; indigo/slate default palette; steps 9-10 solid, 11 text, 12 high-contrast; translucent panel backgrounds; system font stack; medium radius (6-8px) components.

## Design tokens

### Color palette

- color-background — Radix Themes light page background (panels use slate translucents): `#ffffff` (--color-bg)
- slate-2 — subtle background / solid panel equivalent: `#f9f9fb` (--color-surface)
- slate-12 — high-contrast text: `#1c2024` (--color-text)
- slate-11 — low-contrast text: `#60646c` (--color-text-muted)
- indigo-9 — the solid accent step (default accentColor is indigo): `#3e63dd` (--color-accent)
- indigo-10 — hovered solid: `#3358d4` (--color-accent-hover)
- indigo-11 — accent-colored text on light backgrounds: `#3a5bc7` (--color-accent-text)
- indigo-3 — tinted component backgrounds (soft variant): `#edf2fe` (--color-accent-bg)
- slate-6 — subtle component borders (7 for interactive borders): `#d9d9e0` (--color-border)
- indigo-8 — focus ring color (--focus-8): `#8da4ef` (--color-focus)

### Dark mode overrides

When building dark mode, override these roles (all other tokens stay the same):

- slate-1 dark — app background: `#111113` (--color-bg)
- slate-2 dark: `#18191b` (--color-surface)
- slate-12 dark: `#edeef0` (--color-text)
- slate-11 dark: `#b0b4ba` (--color-text-muted)
- indigo-9 dark — solid step intentionally identical to light: `#3e63dd` (--color-accent)
- indigo-10 dark: `#5472e4` (--color-accent-hover)
- indigo-11 dark — brightened for dark-background legibility: `#9eb1ff` (--color-accent-text)
- indigo-3 dark: `#182449` (--color-accent-bg)
- slate-6 dark: `#363a3f` (--color-border)
- indigo-8 dark: `#435db1` (--color-focus)

### Typography

- Display / headings: system-ui (fallback: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, sans-serif)
- Body: system-ui (fallback: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica Neue, sans-serif)
- Mono / data: Menlo (fallback: Consolas, Bitstream Vera Sans Mono, monospace)
- Type scale: 1.2 ratio, base 16px — computed steps: 16px / 19px / 23px / 28px / 33px / 40px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 700, line-height 1.3, letter-spacing -0.01em
- Body: line-height 1.5, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 4, 8, 12, 16, 24, 32, 40, 48, 64 — Nine space tokens (space-1 4px … space-9 64px) multiplied by the global scaling factor (90–110%); component sizes 1–3 (and 4 for buttons) shift padding coherently, so density is a theme prop, not a redesign.
- Border radius: radius-1 3px, radius-2 4px, radius-3 6px, radius-4 8px, radius-5 12px, radius-6 16px, full 9999px — Default theme radius is 'medium'; the radius prop (none/small/medium/large/full) rescales these factors globally, and 'full' pills buttons without distorting cards.
- Border treatment: 1px solid #d9d9e0 — Step 6 for subtle borders, step 7 (#cdced6) for interactive component borders, step 8 for stronger edges and focus rings — the scale prescribes exactly which step borders use.

### Shadows

- shadow-2: `0 0 0 1px rgba(28, 32, 36, 0.08), 0 1px 3px rgba(28, 32, 36, 0.06)` — Simplified approximation of --shadow-2 — cards and low panels (actual token is a longer multi-layer stack)
- shadow-4: `0 8px 20px -4px rgba(28, 32, 36, 0.12), 0 2px 6px rgba(28, 32, 36, 0.08)` — Approximation of --shadow-4 — popovers, dropdown menus
- shadow-6: `0 24px 40px -12px rgba(28, 32, 36, 0.2), 0 4px 12px rgba(28, 32, 36, 0.1)` — Approximation of --shadow-6 — dialogs and modal panels

### Layout

- Max content width: 1136px
- Container component sizes 1–4 cap content at 448/688/880/1136px
- Layout is delegated to Flex/Grid/Section/Box primitives with space-token props rather than custom CSS
- Section component rhythms vertical padding at sizes 1–3 (24/40/64px)
- Panels (Card, Dialog, Popover) float on translucent backgrounds with backdrop blur when panelBackground='translucent' (default)

### Effects

- Translucent panel backgrounds with backdrop blur (default panelBackground) give a barely-there glass feel
- Alpha variants of every scale step (indigoA/slateA) let tints composite correctly on any background

### Motion

- Easing: cubic-bezier(0.16, 1, 0.3, 1); durations 100ms / 200ms / 300ms
- Primitives animate open/close with quick fades and 2–4px slides (popovers, tooltips, dialogs)
- No decorative motion in the theme layer itself; components feel instant
- Respects prefers-reduced-motion out of the box

## CSS variables (drop-in)

```css
:root {
  --color-bg: #ffffff;
  --color-surface: #f9f9fb;
  --color-text: #1c2024;
  --color-text-muted: #60646c;
  --color-accent: #3e63dd;
  --color-accent-hover: #3358d4;
  --color-accent-text: #3a5bc7;
  --color-accent-bg: #edf2fe;
  --color-border: #d9d9e0;
  --color-focus: #8da4ef;
  --radius-radius-1: 3px;
  --radius-radius-2: 4px;
  --radius-radius-3: 6px;
  --radius-radius-4: 8px;
  --radius-radius-5: 12px;
  --radius-radius-6: 16px;
  --radius-full: 9999px;
  --shadow-shadow-2: 0 0 0 1px rgba(28, 32, 36, 0.08), 0 1px 3px rgba(28, 32, 36, 0.06);
  --shadow-shadow-4: 0 8px 20px -4px rgba(28, 32, 36, 0.12), 0 2px 6px rgba(28, 32, 36, 0.08);
  --shadow-shadow-6: 0 24px 40px -12px rgba(28, 32, 36, 0.2), 0 4px 12px rgba(28, 32, 36, 0.1);
  --border-default: 1px solid #d9d9e0;
  --font-display: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
  --font-body: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
  --font-mono: Menlo, Consolas, "Bitstream Vera Sans Mono", monospace;
  --text-base: 16px;
  --leading-heading: 1.3;
  --leading-body: 1.5;
  --tracking-heading: -0.01em;
  --tracking-body: 0;
  --ease: cubic-bezier(0.16, 1, 0.3, 1);
  --duration-fast: 100ms;
  --duration-base: 200ms;
  --duration-slow: 300ms;
}
```

All fonts are system fonts — nothing to load.

## Component recipes

- **Nav:** Radix Themes ships no app-shell; typical usage is a slate-1 sidebar of ghost buttons with indigo-3 selected tints, or a top bar of Text links in slate-11 that darken to slate-12
- **Hero:** Docs-style hero: large 700-weight heading in slate-12, subtitle in slate-11, indigo-9 solid Button beside a soft indigo-3 secondary — all on plain background 1
- **Card:** Card component: background panel tint, radius-4, shadow within a 1px slate-6 ring; inset variant swaps shadow for a plain border; hover lifts to step-3 background when interactive
- **Button (primary):** solid variant: indigo-9 fill, white text, radius factor medium (6px at size 2), 32px tall; hover indigo-10; focus ring 2px focus-8 offset 2px
- **Button (secondary):** soft variant: indigo-3 fill with indigo-11 text (hover indigo-4); outline and ghost variants use indigo-7/8 borders or bare text
- **Form fields:** TextField: surface variant with slate-1 background, 1px slate-7 border, radius-2, 32px tall; focus swaps border to focus-8 ring; size and radius follow theme props

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The 12-step scale contract: step 1 app background, 3 hovered component, 6 borders, 9 solid accent, 11 low-contrast text, 12 high-contrast text — a palette API so predictable that dark mode is just swapping scales. Spend boldness here; keep everything else quiet.

## Do

- Follow the step contract religiously — 1-2 backgrounds, 3-5 component states, 6-8 borders, 9-10 solids, 11-12 text
- Let grayColor='auto' pair the accent with its designed gray (indigo→slate) instead of forcing pure gray
- Change look via Theme props (accentColor, radius, scaling) before writing CSS overrides
- Use alpha scale variants when layering tints over non-white backgrounds

## Don't

- Don't use step 9 for text — it's the one step designed for solid fills with white text, not for legibility on white
- Don't hand-mix scales from outside Radix Colors; the P3/APCA-tuned steps don't interpolate cleanly with arbitrary hexes
- Don't disable the focus ring or swap it below step 8
- Don't treat dark mode as a filter — swap to the dark scales, which are re-drawn, not inverted

## Accessibility notes

- Scale steps encode contrast guarantees: step 11 is designed for low-contrast text that still passes 4.5:1, step 12 for high contrast; solid step 9 (indigo #3e63dd ≈ 5:1 on white) is specified to carry white text
- Underlying Radix Primitives provide WAI-ARIA roles, focus management, and keyboard behavior, so the theme's visual layer sits on accessible semantics by default
- Focus rings use accent step 8 at 2px with offset — visible on both light and dark scales

## Reference sites

- Radix Themes: https://www.radix-ui.com/themes
- Radix Colors (scale values): https://www.radix-ui.com/colors
- radix-ui/colors on GitHub: https://github.com/radix-ui/colors

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip radix-themes.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/radix-themes.json

Settings → Capabilities → Skills → Upload skill → radix-themes.zip