Design System

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

Tailwind CSS

Tailwind CSS uses a CSS-first configuration, letting you define your design tokens with the @theme directive directly in your CSS. This makes your theme portable, maintainable and easy to customize.

app/assets/css/main.css

@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  /* Your custom design tokens go here */
}

Check the Tailwind CSS documentation for all available theme variable customization options.

Fonts

Use the --font-* theme variables to customize the font family utilities in your project.

app/assets/css/main.css

@theme {
  --font-sans: 'Public Sans', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

Fonts defined here are automatically loaded and optimized by the @nuxt/fonts module.

Colors

Use the --color-* theme variables to customize your colors or override default colors.

app/assets/css/main.css

@theme {
  /* Override default green color */
  --color-green-50: #EFFDF5;
  --color-green-100: #D9FBE8;
  --color-green-200: #B3F5D1;
  --color-green-300: #75EDAE;
  --color-green-400: #00DC82;
  --color-green-500: #00C16A;
  --color-green-600: #00A155;
  --color-green-700: #007F45;
  --color-green-800: #016538;
  --color-green-900: #0A5331;
  --color-green-950: #052E16;

  /* Define new custom color */
  --color-brand-50: #fef2f2;
  --color-brand-100: #fee2e2;
  --color-brand-200: #fecaca;
  --color-brand-300: #fca5a5;
  --color-brand-400: #f87171;
  --color-brand-500: #ef4444;
  --color-brand-600: #dc2626;
  --color-brand-700: #b91c1c;
  --color-brand-800: #991b1b;
  --color-brand-900: #7f1d1d;
  --color-brand-950: #450a0a;
}

When adding custom colors, make sure to define all shades from 50 to 950 for each color.

Breakpoints

Use the --breakpoint-* theme variables to customize your breakpoints.

app/assets/css/main.css

@theme {
  --breakpoint-3xl: 1920px;
  --breakpoint-4xl: 2560px;
  --breakpoint-5xl: 3840px;
}

Color system

Nuxt UI's color system is designed around semantic naming rather than specific color values. This approach makes your UI more maintainable and allows for easy theme switching.

Semantic colors

Nuxt UI provides semantic color aliases that describe the purpose of the color. Each alias is defined based on a color from your @theme configuration, which can be any color you define in addition to the default Tailwind CSS palette.

Color	Default	Description
`primary`	`green`	Main CTAs, active navigation, brand elements, important links
`secondary`	`blue`	Secondary buttons, alternative actions, complementary UI elements
`success`	`green`	Success messages, completed states, positive confirmations
`info`	`blue`	Info alerts, tooltips, help text, neutral notifications
`warning`	`yellow`	Warning messages, pending states, attention-needed items
`error`	`red`	Error messages, validation errors, destructive actions
`neutral`	`slate`	Text, borders, backgrounds, disabled states

These semantic colors are available in the color prop of Nuxt UI components:

color

<template>
  <UButton color="primary">Save Changes</UButton>
</template>

Try the theme picker in the header to instantly see how different color schemes affect the entire UI!

Runtime configuration

You can configure these colors at runtime in your app.config.ts file under the ui.colors key, allowing for dynamic theme customization without restarting the server:

app.config.ts

export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      neutral: 'zinc'
    }
  }
})

You can configure these colors at runtime in your vite.config.ts file under the ui.colors key, allowing for dynamic theme customization:

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        colors: {
          primary: 'blue',
          secondary: 'purple',
          neutral: 'zinc'
        }
      }
    })
  ]
})

You can only use colors that exist in your theme. Either:

Use Tailwind's default colors (like blue, green, zinc)
Define custom colors first using the @theme directive (like brand in our example above)

Extend colors

You may want to define extra semantic colors beyond the defaults, such as adding a tertiary color:

First, register the new color in your nuxt.config.ts under the ui.theme.colors key:

nuxt.config.ts

export default defineNuxtConfig({
  ui: {
    theme: {
      colors: [
        'primary',
        'secondary',
        'tertiary',
        'info',
        'success',
        'warning',
        'error'
      ]
    }
  }
})

Then, assign it in your app.config.ts under the ui.colors key:

app.config.ts

export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      tertiary: 'indigo'
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      theme: {
        colors: [
          'primary',
          'secondary',
          'tertiary',
          'info',
          'success',
          'warning',
          'error'
        ]
      },
      ui: {
        colors: {
          primary: 'blue',
          secondary: 'purple',
          tertiary: 'indigo'
        }
      }
    })
  ]
})

Finally, use this new color in components that support the color prop or as a class:

<UButton color="tertiary">
  Special Action
</UButton>

Contribution

A comprehensive guide on contributing to Nuxt UI, including project structure, development workflow, and best practices.

CSS Variables

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