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### `UTheme` (scoped overrides)
209 
210Override theme for a section of the component tree without affecting the rest of the app. Renders no DOM element — uses `provide`/`inject`:
211 
212```vue
213<UTheme :ui="{ button: { slots: { base: 'rounded-full' } } }">
214  <UButton label="Rounded" />
215  <UButton label="Also rounded" />
216</UTheme>
217```
218 
219### Global `defaultVariants`
220 
221Override default `size` and `color` for **all** components at once:
222 
223```ts
224// nuxt.config.ts
225export default defineNuxtConfig({
226  ui: {
227    theme: {
228      defaultVariants: {
229        size: 'lg',
230        color: 'neutral'
231      }
232    }
233  }
234})
235```
236 
237### `theme.transitions`
238 
239Controls whether interactive components get `transition-colors`. Enabled by default.
240 
241```ts
242// nuxt.config.ts — disable transitions
243export default defineNuxtConfig({
244  ui: {
245    theme: {
246      transitions: false
247    }
248  }
249})
250```
251 
252### `theme.prefix`
253 
254When using Tailwind CSS with a prefix, configure the same prefix in Nuxt UI so component classes match:
255 
256```ts
257// nuxt.config.ts
258export default defineNuxtConfig({
259  ui: {
260    theme: {
261      prefix: 'tw'
262    }
263  }
264})
265```
266 
267```css
268/* app/assets/css/main.css */
269@import "tailwindcss" prefix(tw);
270@import "@nuxt/ui";
271```
272 
273### Tree-shaking with `experimental.componentDetection`
274 
275Enable automatic component detection to only generate CSS for components you actually use:
276 
277```ts
278// nuxt.config.ts
279export default defineNuxtConfig({
280  ui: {
281    experimental: {
282      componentDetection: true
283    }
284  }
285})
286```
287 
288For dynamic components (e.g., `<component :is="...">`), pass an array of component names to guarantee they're included:
289 
290```ts
291componentDetection: ['Modal', 'Dropdown', 'Popover']
292```
293 
294## CSS `@theme` customization
295 
296Customize Tailwind design tokens in `main.css`:
297 
298### Fonts
299 
300```css
301@theme {
302  --font-sans: 'Public Sans', system-ui, sans-serif;
303  --font-mono: 'JetBrains Mono', monospace;
304}
305```
306 
307In Nuxt, fonts defined here are automatically loaded by `@nuxt/fonts`.
308 
309### Breakpoints
310 
311```css
312@theme {
313  --breakpoint-3xl: 1920px;
314}
315```
316 
317## CSS variables
318 
319Nuxt UI exposes CSS variables you can override in `main.css`:
320 
321```css
322:root {
323  --ui-radius: 0.25rem;
324  --ui-container: 80rem;
325  --ui-header-height: 4rem;
326}
327```
328 
329### Color shade overrides
330 
331Each semantic color defaults to shade 500 in light mode, 400 in dark mode. Override per-mode:
332 
333```css
334:root {
335  --ui-primary: var(--ui-color-primary-700);
336}
337.dark {
338  --ui-primary: var(--ui-color-primary-200);
339}
340```
341 
342You 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).
343 
344### Black/white as primary
345 
346`black` and `white` have no shades, so they can't be used in config. Set them directly:
347 
348```css
349:root {
350  --ui-primary: black;
351}
352.dark {
353  --ui-primary: white;
354}
355```
356