Theming

We use and recommend CSS variables for theming.

This gives you semantic theme tokens like background, foreground, and primary that components use by default. Override those tokens in your CSS to change the look of your app without rewriting component classes.

Copy<div className="bg-background text-foreground" />

To use CSS variables for theming, set tailwind.cssVariables to true in your components.json file. This is the default.

Copy{
  "style": "dots",
  "rsc": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  }
}

Tailwind maps these tokens into utilities like bg-background, text-foreground, border-border, and ring-ring.

Dark mode works by overriding the same tokens inside a .dark selector. See the dark mode docs for adding a theme provider and toggling the .dark class.

Token Convention#

We use semantic background and foreground pairs. The base token controls the surface color and the -foreground token controls the text and icon color that sits on that surface.

Given the following CSS variables:

Copy--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);

The background color of the following component will be var(--primary) and the foreground color will be var(--primary-foreground).

Copy<div className="bg-primary text-primary-foreground">Hello</div>

Theme Tokens#

These tokens live in your CSS file under :root and .dark.

Radius Scale#

--radius is the base radius token for your theme.

We derive a small radius scale from it so components can use consistent corner sizes while still sharing a single source of truth.

Copy@theme inline {
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}

This means:

• radius-lg is the base value.
• Smaller radii scale down from --radius.
• Larger radii scale up from --radius.
• Changing --radius updates the entire radius scale.

Adding New Tokens#

To add a new token, define it under :root and .dark, then expose it to Tailwind with @theme inline.

Copy:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}
 
.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}
 
@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

You can now use bg-warning and text-warning-foreground in your components.

Copy<div className="text-warning-foreground bg-warning" />

The Dots Palette#

init writes the Dots palette into your CSS file: the tokens above under :root and .dark, plus the extra tokens Dots components use (warning, track, glass and the --dots-shadow-* shadows) with their @theme inline mappings. The palette is monochrome: primary is the foreground and background inverted, and colour is kept for destructive and warning.

tailwind.baseColor in components.json is always neutral. The CLI records it, but the Dots palette overrides every token it defines. To see the exact values, open your CSS file after init or request the preset at /init.

Without CSS Variables#

If you do not want to use CSS variables, the CLI can generate components with inline Tailwind color utilities instead.

pnpmnpmyarnbun
pnpm dlx shadcn@latest init --no-css-variables
Copy

This sets tailwind.cssVariables to false in your components.json file.

Copy<div className="bg-zinc-950 text-zinc-50 dark:bg-white dark:text-zinc-950" />