---
system: radix
category: design-md
topic: DESIGN.md
content_type: design-md
status: latest
version_label: "Radix Themes 3.x"
retrieved: 2026-05-13
unofficial: true
derived_from:
  - guidance/foundations/color-system@2026-05-12.md
  - guidance/foundations/typography@2026-05-12.md
  - guidance/foundations/design-tokens@2026-05-12.md
  - guidance/foundations/spacing@2026-05-13.md
  - guidance/foundations/radius@2026-05-13.md
  - implementation/getting-started@2026-05-12.md
source_url: https://www.radix-ui.com/themes/docs
---

> **This is a community-generated DESIGN.md derived from Radix Themes' public documentation. It is not an official document published by WorkOS or the Radix team.**

---

colors:
  accent: indigo
  accent-solid: "#3E63DD"
  accent-solid-hover: "#3358D4"
  accent-text: "#3451B2"
  accent-subtle: "#EEF2FF"
  accent-surface: "#F5F8FF"
  accent-contrast: "#FFFFFF"
  gray: slate
  background: "#FFFFFF"
  panel-solid: "#FFFFFF"
  panel-translucent: "rgba(255,255,255,0.85)"
  surface: "#FFFFFF"
  overlay: "rgba(0,0,0,0.5)"

typography:
  font-family: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
  font-family-heading: inherit
  font-family-code: "'Menlo', 'Consolas', monospace"
  font-family-em: "'Times New Roman', Times, serif"
  scale:
    1: { size: "12px", line-height: "16px", letter-spacing: "0.0025em" }
    2: { size: "14px", line-height: "20px", letter-spacing: "0em" }
    3: { size: "16px", line-height: "24px", letter-spacing: "0em" }
    4: { size: "18px", line-height: "26px", letter-spacing: "-0.0025em" }
    5: { size: "20px", line-height: "28px", letter-spacing: "-0.005em" }
    6: { size: "24px", line-height: "30px", letter-spacing: "-0.00625em" }
    7: { size: "28px", line-height: "36px", letter-spacing: "-0.0075em" }
    8: { size: "35px", line-height: "40px", letter-spacing: "-0.01em" }
    9: { size: "60px", line-height: "60px", letter-spacing: "-0.025em" }
  weights:
    light: 300
    regular: 400
    medium: 500
    bold: 700

spacing:
  1: "4px"
  2: "8px"
  3: "12px"
  4: "16px"
  5: "24px"
  6: "32px"
  7: "40px"
  8: "48px"
  9: "64px"

radius:
  theme-default: medium
  none: "0px"
  small: "~2–4px contextual"
  medium: "~4–8px contextual"
  large: "~8–16px contextual"
  full: "9999px (pill)"
  tokens:
    radius-1: "var(--radius-1)"
    radius-2: "var(--radius-2)"
    radius-3: "var(--radius-3)"
    radius-4: "var(--radius-4)"
    radius-5: "var(--radius-5)"
    radius-6: "var(--radius-6)"

components:
  button-solid:
    background: "var(--accent-9)"
    color: "var(--accent-contrast)"
    border-radius: "var(--radius-2)"
  button-soft:
    background: "var(--accent-3)"
    color: "var(--accent-11)"
    border-radius: "var(--radius-2)"
  button-ghost:
    background: "transparent"
    color: "var(--accent-11)"
    border-radius: "var(--radius-2)"
  button-surface:
    background: "var(--color-surface)"
    color: "var(--accent-11)"
    border: "1px solid var(--accent-7)"
    border-radius: "var(--radius-2)"
  button-outline:
    background: "transparent"
    color: "var(--accent-11)"
    border: "1px solid var(--accent-8)"
    border-radius: "var(--radius-2)"

---

## Overview

Radix Themes is a pre-styled React component library built on Radix Primitives. The visual language is config-first: the entire theme is derived from a small set of props on the `<Theme>` component rather than manually specified tokens. All values are CSS custom properties scoped to `.radix-themes`, making them accessible for custom component styling.

The default theme uses Indigo as the accent with Slate as the gray — a clean, neutral palette suited to productivity applications, dashboards, and developer tools. The system font stack is used by default (no custom font loading required).

## Colors

Two-axis color model: accent color × gray color. Setting `accentColor` and `grayColor` on the `<Theme>` component drives the full palette.

Each color is a 12-step scale with documented step semantics:

- Steps 1–2: Page and component backgrounds
- Steps 3–5: Interactive backgrounds (hover, active states)
- Steps 6–8: Borders and separators
- Steps 9–10: Solid fills — the primary brand steps (buttons, badges)
- Steps 11–12: Accessible text
- `--accent-contrast`: foreground for text on step-9 backgrounds

Every step has an alpha variant (e.g. `--indigo-a9`) for use over non-white surfaces. Alpha colors are used automatically within Radix Themes components.

**Semantic surface tokens:**
- `--color-background`: page background
- `--color-panel-solid` / `--color-panel-translucent`: card and popup surfaces
- `--color-surface`: form component backgrounds
- `--color-overlay`: dialog/modal overlays

**Focus colors:** `--focus-1` through `--focus-12` — automatically matched to the component's active accent. Most components use `--focus-8` for focus outlines.

**Dark mode:** `appearance="dark"` on `<Theme>` — all Radix Colors scales include dark values; no separate stylesheet needed.

## Typography

9-step size scale from 12px to 60px. Each step pairs a font size with coordinated line height and letter spacing. Larger sizes use negative letter-spacing to compensate for optical spread at display scale.

Default font families by role:
- Text: OS system font stack (no loading latency)
- Code: `'Menlo', 'Consolas'` monospace stack
- Em / Quote: `'Times New Roman', serif`

Custom fonts are applied by overriding `--default-font-family` and role-specific variables (`--heading-font-family`, `--code-font-family`, `--strong-font-family`, `--em-font-family`, `--quote-font-family`) via CSS after the Radix stylesheet.

For `next/font` integration: use the `variable` option to define a CSS variable, then map it to `--default-font-family` in CSS.

Font weights are customizable via CSS: `--font-weight-light`, `--font-weight-regular`, `--font-weight-medium`, `--font-weight-bold`.

Advanced heading tokens available: `--heading-font-size-adjust`, `--heading-leading-trim-start`, `--heading-leading-trim-end`, `--heading-letter-spacing`.

## Layout

9-step spacing scale from 4px to 64px on a 4px base grid. Applied via layout component props (`m`, `p`, `gap`) rather than CSS classes. All layout components (`Box`, `Flex`, `Grid`, `Container`, `Section`) accept responsive breakpoint values on all props.

Breakpoints: `initial` (mobile-first), `xs`, `sm`, `md`, `lg`, `xl`.

The `scaling` prop (`"90%"` to `"110%"`) applies a global multiplier to spacing, font size, and line height — the primary mechanism for UI density control. Custom components can participate via `calc(Npx * var(--scaling))`.

## Elevation & Depth

Panels use `--color-panel-translucent` by default for subtle surface hierarchy without explicit shadows. Shadow tokens (`--shadow-1` through `--shadow-6`) are available for custom elevation. Dialog overlays use `--color-overlay`.

## Shapes

Radius configured globally via the `radius` prop on `<Theme>`: `none`, `small`, `medium` (default), `large`, `full`. All components derive their corner radius from `--radius-1` through `--radius-6` CSS variables, which are recalculated when the prop changes. The resulting radius is contextual per component — `full` makes buttons pill-shaped but leaves checkboxes with moderate rounding.

`--radius-factor`, `--radius-full`, and `--radius-thumb` are also available for custom component use.

Many components expose a per-instance `radius` prop for local overrides; panel components (Card, Dialog, Popover) inherit from the theme only.

## Components

All Radix Themes components share a consistent variant vocabulary:

- `classic` — most prominent, elevated treatment
- `solid` — solid accent fill, high emphasis (use `--accent-9` / `--accent-contrast`)
- `soft` — tinted background (accent-3), medium emphasis
- `surface` — white/panel background with border
- `outline` — transparent with border
- `ghost` — no background or border, lowest emphasis

This system enables a consistent hierarchy across all component types using a single `variant` prop.

## Do's and Don'ts

**Do:**
- Use `<Theme>` props as the primary configuration surface — avoid per-component overrides when a theme prop achieves the same result
- Use `--accent-9` for solid brand fills and `--accent-contrast` for text on those fills
- Use `--accent-11` / `--accent-12` for accessible text colors — not step 9
- Use the `highContrast` prop for emphasis rather than manually picking darker token steps
- Apply custom styles after `@radix-ui/themes/styles.css` so overrides take precedence
- Use CSS variable overrides for custom colors so dark mode and scaling remain consistent
- Use `var(--space-N)` tokens and `var(--radius-N)` tokens in custom components so they respond to theme scaling and radius settings

**Don't:**
- Don't hardcode hex values in component styles — always reference CSS variables so the theme system stays coherent
- Don't use `--accent-9` for text — it is designed for solid fills, not legibility
- Don't use `ThemePanel` in production
- Don't skip the CSS import — without `@radix-ui/themes/styles.css`, no styles apply
- Don't override spacing or radius with hardcoded values in custom components when CSS variable tokens are available