CSS Variables

Nuxt UI uses CSS variables as design tokens for flexible, consistent theming with built-in light and dark mode support.

Colors

Nuxt UI provides Tailwind CSS utility classes for each semantic color you define, allowing you to use class names like text-error or bg-success:

PrimarySecondarySuccessInfoWarningError

<template>
  <span class="text-primary">Primary</span>
  <span class="text-secondary">Secondary</span>
  <span class="text-success">Success</span>
  <span class="text-info">Info</span>
  <span class="text-warning">Warning</span>
  <span class="text-error">Error</span>
</template>

Each utility class uses a CSS variable to set its color for light and dark modes:

:root {
  --ui-primary: var(--ui-color-primary-500);
  --ui-secondary: var(--ui-color-secondary-500);
  --ui-success: var(--ui-color-success-500);
  --ui-info: var(--ui-color-info-500);
  --ui-warning: var(--ui-color-warning-500);
  --ui-error: var(--ui-color-error-500);
}
You can adjust which shade each utility class uses for light and dark mode in your main.css file:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-primary: var(--ui-color-primary-700);
}

.dark {
  --ui-primary: var(--ui-color-primary-200);
}
You can't use primary: 'black' in your config because black doesn't have multiple shades. To use solid black or white as your primary color, set it directly in your main.css file:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-primary: black;
}

.dark {
  --ui-primary: white;
}

Text

Nuxt UI provides Tailwind CSS utility classes for text colors, allowing you to use class names like text-dimmed or text-muted:

DimmedMutedTonedTextHighlightedInverted

<template>
  <span class="text-dimmed">Dimmed</span>
  <span class="text-muted">Muted</span>
  <span class="text-toned">Toned</span>
  <span class="text-default">Text</span>
  <span class="text-highlighted">Highlighted</span>
  <span class="text-inverted bg-inverted">Inverted</span>
</template>

Each utility class uses a CSS variable to set its color for light and dark modes:

:root {
  --ui-text-dimmed: var(--ui-color-neutral-400);
  --ui-text-muted: var(--ui-color-neutral-500);
  --ui-text-toned: var(--ui-color-neutral-600);
  --ui-text: var(--ui-color-neutral-700);
  --ui-text-highlighted: var(--ui-color-neutral-900);
  --ui-text-inverted: var(--color-white);
}
You can customize these CSS variables in your main.css file:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-text: var(--ui-color-neutral-900);
}

.dark {
  --ui-text: var(--color-white);
}

Background

Nuxt UI provides Tailwind CSS utility classes for background colors, allowing you to use class names like bg-default or bg-muted:

DefaultMutedElevatedAccentedInverted

<template>
  <div class="bg-default">Default</div>
  <div class="bg-muted">Muted</div>
  <div class="bg-elevated">Elevated</div>
  <div class="bg-accented">Accented</div>
  <div class="bg-inverted text-inverted">Inverted</div>
</template>

Each utility class uses a CSS variable to set its color for light and dark modes:

:root {
  --ui-bg: var(--color-white);
  --ui-bg-muted: var(--ui-color-neutral-50);
  --ui-bg-elevated: var(--ui-color-neutral-100);
  --ui-bg-accented: var(--ui-color-neutral-200);
  --ui-bg-inverted: var(--ui-color-neutral-900);
}
You can customize these CSS variables in your main.css file:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-bg: var(--ui-color-neutral-50);
}

.dark {
  --ui-bg: var(--ui-color-neutral-950);
}

Border

Nuxt UI provides Tailwind CSS utility classes for border colors, allowing you to use class names like border-default or border-muted:

DefaultMutedAccentedInverted

<template>
  <div class="border border-default">Default</div>
  <div class="border border-muted">Muted</div>
  <div class="border border-accented">Accented</div>
  <div class="border border-inverted">Inverted</div>
</template>

Each utility class uses a CSS variable to set its color for light and dark modes:

:root {
  --ui-border: var(--ui-color-neutral-200);
  --ui-border-muted: var(--ui-color-neutral-200);
  --ui-border-accented: var(--ui-color-neutral-300);
  --ui-border-inverted: var(--ui-color-neutral-900);
}
You can customize these CSS variables in your main.css file:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-border: var(--ui-color-neutral-100);
}

.dark {
  --ui-border: var(--ui-color-neutral-900);
}

Radius

Nuxt UI overrides Tailwind CSS's default rounded-* utilities with a unified border radius system, allowing you to use regular border radius utilities like rounded-xs or rounded-2xl:

xssmmdlgxl2xl3xl

<template>
  <div class="rounded-xs">xs</div>
  <div class="rounded-sm">sm</div>
  <div class="rounded-md">md</div>
  <div class="rounded-lg">lg</div>
  <div class="rounded-xl">xl</div>
  <div class="rounded-2xl">2xl</div>
  <div class="rounded-3xl">3xl</div>
</template>

These utility classes are calculated based on a global --ui-radius CSS variable, which defines the base radius value applied across all components for a consistent look.

:root {
  --ui-radius: 0.25rem;
}
You can customize the base radius value in your main.css file:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-radius: 0.5rem;
}
Try the theme picker in the header above to change the base radius value.

Container

Nuxt UI provides a --ui-container CSS variable that controls the maximum width of the Container component.

:root {
  --ui-container: var(--container-7xl);
}
You can customize this value in your main.css file to adjust container widths consistently throughout your application:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  --container-8xl: 90rem;
}

:root {
  --ui-container: var(--container-8xl);
}

Header

Nuxt UI provides a --ui-header-height CSS variable that controls the height of the Header component.

:root {
  --ui-header-height: --spacing(16);
}
You can customize this value in your main.css to adjust header height consistently throughout your application:
app/assets/css/main.css
@import "tailwindcss";
@import "@nuxt/ui";

:root {
  --ui-header-height: --spacing(24);
}

Body

Nuxt UI applies default classes on the <body> element of your app for consistent theming across light and dark modes:

body {
  @apply antialiased text-default bg-default scheme-light dark:scheme-dark;
}

Design System

Nuxt UI's design system uses Tailwind CSS for simple theming and easy customization.

Components

Learn how to customize Nuxt UI components with the Tailwind Variants API for advanced, flexible, and maintainable styling.