CSS Variables Reference for Nuxt UI Themes

Nuxt UI v4 exposes its design system through CSS custom properties (variables). These tokens control colors, border radius, typography, and more - and you can override any of them for fine-grained theming.

Color Variables

Every semantic color role generates a set of shade variables:

/* Primary color shades */
--ui-color-primary-50: /* ... */;
--ui-color-primary-100: /* ... */;
--ui-color-primary-200: /* ... */;
--ui-color-primary-300: /* ... */;
--ui-color-primary-400: /* ... */;
--ui-color-primary-500: /* ... */;
--ui-color-primary-600: /* ... */;
--ui-color-primary-700: /* ... */;
--ui-color-primary-800: /* ... */;
--ui-color-primary-900: /* ... */;
--ui-color-primary-950: /* ... */;

The same pattern applies to secondary, success, warning, error, and neutral.

Overriding Color Shades

To override a specific shade, set the variable in your CSS:

:root {
  /* Override primary-500 with a custom brand color */
  --ui-color-primary-500: oklch(0.585 0.233 277.117);
}

/* Dark mode overrides */
.dark {
  --ui-color-primary-500: oklch(0.705 0.213 265.117);
}

Use OKLCH color values for perceptual uniformity across shades.

Border Radius Variables

One variable sets the base radius, and Nuxt UI derives Tailwind's whole radius scale from it:

:root {
  --ui-radius: 0.25rem; /* Default */
}

Utility	Value	Default (`0.25rem`)
`rounded-xs`	`calc(var(--ui-radius) * 0.5)`	2px
`rounded-sm`	`var(--ui-radius)`	4px
`rounded-md`	`calc(var(--ui-radius) * 1.5)`	6px
`rounded-lg`	`calc(var(--ui-radius) * 2)`	8px
`rounded-xl`	`calc(var(--ui-radius) * 3)`	12px
`rounded-2xl`	`calc(var(--ui-radius) * 4)`	16px
`rounded-3xl`	`calc(var(--ui-radius) * 6)`	24px

Buttons and inputs use rounded-md and cards use rounded-lg, so changing --ui-radius rescales them all. See Change the Border Radius Everywhere in Nuxt UI.

Typography Variables

Font family tokens control the typeface across the entire UI:

:root {
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
}

Override these to apply your chosen font pairing.

Using Variables in Your CSS

You can reference these tokens in your own components:

.custom-card {
  background-color: var(--ui-color-primary-50);
  border: 1px solid var(--ui-color-primary-200);
  border-radius: var(--ui-radius);
  font-family: var(--font-sans);
}

.dark .custom-card {
  background-color: var(--ui-color-primary-950);
  border-color: var(--ui-color-primary-800);
}

Using Variables in Tailwind Classes

Tailwind CSS v4 can consume CSS variables directly:

<div
  class="bg-(--ui-color-primary-50) border border-(--ui-color-primary-200) rounded-(--ui-radius)"
>
  Content
</div>

Variable Naming Convention

All Nuxt UI variables follow a consistent pattern:

--ui-{category}-{role}-{shade}
--ui-{property}

Examples:

--ui-color-primary-500 - primary color, shade 500
--ui-color-neutral-100 - neutral color, shade 100
--ui-radius - base border radius
--ui-bg - background color token

Export Variables from the Theme Builder

The Nuxt UI Theme Builder can export your entire theme as CSS variables. Use the CSS export format to get a ready-to-paste stylesheet with all your customizations.

Need a variable in a different color format? The Color Converter converts between HEX, RGB, HSL, and OKLCH.

Next Steps

How to Customize Nuxt UI Theme Colors - configure color roles
Nuxt UI Color Palette Reference - browse available palettes
Tailwind CSS v4 Theming: What Changed - understand the new variable-based system