1# Design System
2 
3## Semantic colors
4 
5Nuxt UI uses 7 semantic colors. Never use raw Tailwind palette colors in components — always use these semantic names.
6 
7| Color | Default | When to use |
8|---|---|---|
9| `primary` | green | CTAs, active states, brand accent, links |
10| `secondary` | blue | Secondary actions, complementary highlights |
11| `success` | green | Success messages, confirmations, positive states |
12| `info` | blue | Informational alerts, tips, neutral highlights |
13| `warning` | yellow | Warnings, caution states, pending actions |
14| `error` | red | Errors, destructive actions, validation failures |
15| `neutral` | slate | Text, borders, backgrounds, disabled states, chrome |
16 
17### Choosing colors for components
18 
19- **Primary action** on a page (submit, save, confirm) → `color="primary"`
20- **Secondary actions** (cancel, back, alternative) → `color="neutral"` with `variant="outline"` or `"ghost"`
21- **Destructive actions** (delete, remove) → `color="error"`
22- **Status indicators** → match the semantic meaning: `success`, `warning`, `error`, `info`
23- **Navigation and chrome** → `color="neutral"`
24 
25### Configuring colors
26 
27```ts
28// Nuxt — app.config.ts
29export default defineAppConfig({
30  ui: {
31    colors: {
32      primary: 'indigo',
33      secondary: 'violet',
34      success: 'emerald',
35      error: 'rose',
36      neutral: 'zinc'
37    }
38  }
39})
40```
41 
42```ts
43// Vue — vite.config.ts
44ui({
45  ui: {
46    colors: { primary: 'indigo', secondary: 'violet', neutral: 'zinc' }
47  }
48})
49```
50 
51Only colors that exist in your theme work — either Tailwind's defaults or custom colors defined with `@theme`.
52 
53Available color palettes:
54- **Standard Tailwind**: red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose
55- **Neutral palettes** (for `neutral` key — pick one that matches the aesthetic):
56  - `slate` — cool blue-gray, professional (default)
57  - `gray` — true neutral, clean
58  - `zinc` — slightly cool, modern, techy
59  - `neutral` — perfectly balanced
60  - `stone` — warm gray, earthy
61  - `taupe` — warm brown-gray, sophisticated
62  - `mauve` — purple-tinted gray, elegant
63  - `mist` — soft blue-gray, airy
64  - `olive` — green-tinted gray, natural
65 
66### Adding custom brand colors
67 
681. Define all 11 shades in CSS:
69 
70```css
71/* app/assets/css/main.css */
72@theme static {
73  --color-brand-50: #fef2f2;
74  --color-brand-100: #fee2e2;
75  --color-brand-200: #fecaca;
76  --color-brand-300: #fca5a5;
77  --color-brand-400: #f87171;
78  --color-brand-500: #ef4444;
79  --color-brand-600: #dc2626;
80  --color-brand-700: #b91c1c;
81  --color-brand-800: #991b1b;
82  --color-brand-900: #7f1d1d;
83  --color-brand-950: #450a0a;
84}
85```
86 
872. Assign it: `ui: { colors: { primary: 'brand' } }`
88 
89### Extending with new semantic color names
90 
91To add a color beyond the 7 defaults (e.g., `tertiary`), register it in `theme.colors`:
92 
93```ts
94// nuxt.config.ts
95export default defineNuxtConfig({
96  ui: {
97    theme: {
98      colors: ['primary', 'secondary', 'tertiary', 'info', 'success', 'warning', 'error']
99    }
100  }
101})
102```
103 
104## Semantic utility classes
105 
106Use these everywhere instead of raw palette colors:
107 
108### Text
109- `text-default` — primary body text
110- `text-muted` — secondary text (descriptions, hints)
111- `text-toned` — medium-emphasis text (between muted and default)
112- `text-dimmed` — tertiary text (placeholders, disabled)
113- `text-highlighted` — emphasized text (headings, important labels)
114- `text-inverted` — text on inverted backgrounds (pair with `bg-inverted`)
115 
116### Backgrounds
117- `bg-default` — page background
118- `bg-muted` — subtle backgrounds (hover states, alternating rows)
119- `bg-elevated` — raised surfaces (cards, dropdowns)
120- `bg-accented` — accent backgrounds (active states, selected items)
121- `bg-inverted` — inverse background (dark on light, light on dark)
122 
123### Borders
124- `border-default` — standard borders
125- `border-muted` — subtle borders (dividers, separators)
126- `border-accented` — accent borders (active states)
127- `border-inverted` — inverse borders
128 
129## Variants
130 
131Most components accept a `variant` prop. Choose based on visual weight:
132 
133| Variant | Weight | When to use |
134|---|---|---|
135| `solid` | Highest | Primary actions, main CTAs |
136| `outline` | Medium | Secondary actions, form fields |
137| `soft` | Medium-low | Tags, badges, subtle buttons |
138| `subtle` | Low | Background highlights, less prominent actions |
139| `ghost` | Lowest | Inline actions, icon buttons, navigation items |
140| `link` | Lowest | Text-only links inside content |
141 
142### Rules
143 
144- **One solid primary button per view** — everything else should be lower weight
145- **Destructive buttons** use `color="error"` but not necessarily `variant="solid"` — use `variant="soft"` or `"outline"` unless it's the primary action on a confirmation dialog
146- **Button groups** should use consistent variants — don't mix `solid` and `outline` siblings
147 
148## Customizing components
149 
150### `ui` prop
151 
152Override theme **slots** on a single instance — wins over global config and variants.
153 
154```vue
155<UButton :ui="{ base: 'font-bold', trailingIcon: 'size-3 rotate-90' }" />
156<UCard :ui="{ header: 'bg-muted', body: 'p-8' }" />
157```
158 
159Rules for `ui` overrides:
160- **Prefer `defaultVariants`** over slot class overrides when possible (e.g., changing default button variant/size).
161- **Don't duplicate default classes** — check the generated theme file first to see what's already there.
162- Border radius defaults come from `--ui-radius`, but you can override with `rounded-*` classes in `ui` or `class` when you need a specific radius on a component.
163 
164### `class` prop
165 
166Override the **root** (or `base`) slot only — simpler than `ui` for single-slot changes.
167 
168```vue
169<UButton class="font-bold" />
170```
171 
172### Finding slot names
173 
174Read the generated theme file for any component:
175- **Nuxt**: `.nuxt/ui/<component>.ts`
176- **Vue**: `node_modules/.nuxt-ui/ui/<component>.ts`
177 
178These files show every available slot name, variant combination, and default class.
179 
180### Global config
181 
182Override `slots`, `variants`, `compoundVariants`, and `defaultVariants` globally in `app.config.ts` (Nuxt) or `vite.config.ts` (Vue):
183 
184```ts
185// Nuxt — app.config.ts
186export default defineAppConfig({
187  ui: {
188    button: {
189      slots: {
190        base: 'font-bold'
191      },
192      compoundVariants: [{
193        color: 'neutral',
194        variant: 'outline',
195        class: 'ring-default hover:bg-accented'
196      }],
197      defaultVariants: {
198        color: 'neutral',
199        variant: 'outline'
200      }
201    }
202  }
203})
204```
205 
206Tailwind Variants uses `tailwind-merge` under the hood — conflicting classes are resolved automatically.
207 
208### Replace instead of merge
209 
210Classes from the `ui` prop, the `class` prop, and global config are merged onto the component defaults. To replace a slot's defaults entirely instead, set it to a function in the `ui` prop or global config. It receives the resolved default classes as its argument, so you can reuse part of them.
211 
212```vue
213<UButton :ui="{ label: () => 'text-base font-bold' }" />
214```
215 
216```ts
217// app.config.ts, applies to every instance
218export default defineAppConfig({
219  ui: {
220    button: {
221      slots: {
222        label: () => 'text-base font-bold'
223      }
224    }
225  }
226})
227```
228 
229### Theme component
230 
231Override theme for a section of the component tree without affecting the rest of the app. Renders no DOM element — uses `provide`/`inject`:
232 
233```vue
234<UTheme :ui="{ button: { slots: { base: 'rounded-full' } } }">
235  <UButton label="Rounded" />
236  <UButton label="Also rounded" />
237</UTheme>
238```
239 
240### Global `defaultVariants`
241 
242Override default `size` and `color` for **all** components at once:
243 
244```ts
245// nuxt.config.ts
246export default defineNuxtConfig({
247  ui: {
248    theme: {
249      defaultVariants: {
250        size: 'lg',
251        color: 'neutral'
252      }
253    }
254  }
255})
256```
257 
258### `theme.transitions`
259 
260Controls whether interactive components get `transition-colors`. Enabled by default.
261 
262```ts
263// nuxt.config.ts — disable transitions
264export default defineNuxtConfig({
265  ui: {
266    theme: {
267      transitions: false
268    }
269  }
270})
271```
272 
273### `theme.prefix`
274 
275When using Tailwind CSS with a prefix, configure the same prefix in Nuxt UI so component classes match:
276 
277```ts
278// nuxt.config.ts
279export default defineNuxtConfig({
280  ui: {
281    theme: {
282      prefix: 'tw'
283    }
284  }
285})
286```
287 
288```css
289/* app/assets/css/main.css */
290@import "tailwindcss" prefix(tw);
291@import "@nuxt/ui";
292```
293 
294### Tree-shaking with `experimental.componentDetection`
295 
296Enable automatic component detection to only generate CSS for components you actually use:
297 
298```ts
299// nuxt.config.ts
300export default defineNuxtConfig({
301  ui: {
302    experimental: {
303      componentDetection: true
304    }
305  }
306})
307```
308 
309For dynamic components (e.g., `<component :is="...">`), pass an array of component names to guarantee they're included:
310 
311```ts
312componentDetection: ['Modal', 'Dropdown', 'Popover']
313```
314 
315## CSS `@theme` customization
316 
317Customize Tailwind design tokens in `main.css`:
318 
319### Fonts
320 
321```css
322@theme {
323  --font-sans: 'Public Sans', system-ui, sans-serif;
324  --font-mono: 'JetBrains Mono', monospace;
325}
326```
327 
328In Nuxt, fonts defined here are automatically loaded by `@nuxt/fonts`.
329 
330### Breakpoints
331 
332```css
333@theme {
334  --breakpoint-3xl: 1920px;
335}
336```
337 
338## CSS variables
339 
340Nuxt UI exposes CSS variables you can override in `main.css`:
341 
342```css
343:root {
344  --ui-radius: 0.25rem;
345  --ui-container: 80rem;
346  --ui-header-height: 4rem;
347}
348```
349 
350### Color shade overrides
351 
352Each semantic color defaults to shade 500 in light mode, 400 in dark mode. Override per-mode:
353 
354```css
355:root {
356  --ui-primary: var(--ui-color-primary-700);
357}
358.dark {
359  --ui-primary: var(--ui-color-primary-200);
360}
361```
362 
363You can use `var(--ui-color-<name>-<shade>)` to reference shades from the active palette (e.g., `var(--ui-color-neutral-800)` maps to whichever neutral palette is configured).
364 
365### Black/white as primary
366 
367`black` and `white` have no shades, so they can't be used in config. Set them directly:
368 
369```css
370:root {
371  --ui-primary: black;
372}
373.dark {
374  --ui-primary: white;
375}
376```
377