1# Theming
2 
3## Semantic Colors
4 
5| Color       | Default | Purpose                                     |
6| ----------- | ------- | ------------------------------------------- |
7| `primary`   | green   | CTAs, active states, brand, important links |
8| `secondary` | blue    | Secondary buttons, alternatives             |
9| `success`   | green   | Success messages, positive states           |
10| `info`      | blue    | Info alerts, help text                      |
11| `warning`   | yellow  | Warnings, pending states                    |
12| `error`     | red     | Errors, destructive actions                 |
13| `neutral`   | slate   | Text, borders, disabled states              |
14 
15## Configuring Colors
16 
17### Nuxt (app.config.ts)
18 
19```ts
20// app.config.ts
21export default defineAppConfig({
22  ui: {
23    colors: {
24      primary: 'indigo',
25      secondary: 'violet',
26      success: 'emerald',
27      error: 'rose'
28    }
29  }
30})
31```
32 
33### Vue (vite.config.ts)
34 
35```ts
36ui({
37  ui: {
38    colors: {
39      primary: 'indigo',
40      secondary: 'violet'
41    }
42  }
43})
44```
45 
46## Adding Custom Colors
47 
481. Register in theme config:
49 
50```ts
51// nuxt.config.ts
52export default defineNuxtConfig({
53  ui: {
54    theme: {
55      colors: ['primary', 'secondary', 'tertiary'] // Add new color
56    }
57  }
58})
59```
60 
612. Define in CSS (all 11 shades required):
62 
63```css
64@theme {
65  --color-tertiary-50: #fef2f2;
66  --color-tertiary-100: #fee2e2;
67  --color-tertiary-200: #fecaca;
68  --color-tertiary-300: #fca5a5;
69  --color-tertiary-400: #f87171;
70  --color-tertiary-500: #ef4444;
71  --color-tertiary-600: #dc2626;
72  --color-tertiary-700: #b91c1c;
73  --color-tertiary-800: #991b1b;
74  --color-tertiary-900: #7f1d1d;
75  --color-tertiary-950: #450a0a;
76}
77```
78 
793. Assign and use:
80 
81```ts
82// app.config.ts
83export default defineAppConfig({
84  ui: { colors: { tertiary: 'tertiary' } }
85})
86```
87 
88```vue
89<UButton color="tertiary">Custom Color</UButton>
90```
91 
92## CSS Variables
93 
94### Text Utilities
95 
96| Class              | Light | Dark | Use                       |
97| ------------------ | ----- | ---- | ------------------------- |
98| `text-dimmed`      | 400   | 500  | Placeholders, hints       |
99| `text-muted`       | 500   | 400  | Secondary text            |
100| `text-toned`       | 600   | 300  | Subtitles                 |
101| `text-default`     | 700   | 200  | Body text                 |
102| `text-highlighted` | 900   | 100  | Headings, emphasis        |
103| `text-inverted`    | 50    | 950  | On dark/light backgrounds |
104 
105### Background Utilities
106 
107| Class         | Light | Dark | Use               |
108| ------------- | ----- | ---- | ----------------- |
109| `bg-default`  | white | 900  | Page background   |
110| `bg-muted`    | 50    | 800  | Subtle sections   |
111| `bg-elevated` | white | 800  | Cards, modals     |
112| `bg-accented` | 100   | 700  | Hover states      |
113| `bg-inverted` | 900   | 100  | Inverted sections |
114 
115### Border Utilities
116 
117| Class             | Light | Dark |
118| ----------------- | ----- | ---- |
119| `border-default`  | 200   | 800  |
120| `border-muted`    | 100   | 800  |
121| `border-accented` | 200   | 700  |
122| `border-inverted` | 900   | 100  |
123 
124### Global Variables
125 
126```css
127:root {
128  --ui-radius: 0.25rem; /* Base border radius */
129  --ui-container: 80rem; /* Container max-width */
130  --ui-header-height: 4rem; /* Header height */
131}
132```
133 
134## Custom CSS Variables
135 
136```css
137/* assets/css/main.css */
138:root {
139  --ui-primary: var(--ui-color-primary-700);
140  --ui-radius: 0.5rem;
141}
142.dark {
143  --ui-primary: var(--ui-color-primary-200);
144}
145```
146 
147## Solid Colors (Black/White)
148 
149Can't use `primary: 'black'` - set in CSS:
150 
151```css
152:root {
153  --ui-primary: black;
154}
155.dark {
156  --ui-primary: white;
157}
158```
159 
160## Tailwind Variants Override
161 
162### Global Override (app.config.ts)
163 
164```ts
165export default defineAppConfig({
166  ui: {
167    button: {
168      slots: {
169        base: 'font-bold rounded-full'
170      },
171      variants: {
172        size: {
173          md: { base: 'px-6 py-3' }
174        }
175      },
176      compoundVariants: [{
177        color: 'neutral',
178        variant: 'outline',
179        class: { base: 'ring-2' }
180      }],
181      defaultVariants: {
182        color: 'neutral',
183        variant: 'outline'
184      }
185    }
186  }
187})
188```
189 
190### Per-Component Override
191 
192```vue
193<!-- ui prop overrides slots -->
194<UButton :ui="{ base: 'font-mono' }">Custom</UButton>
195 
196<!-- class prop overrides root/base slot -->
197<UButton class="rounded-none">Square</UButton>
198```
199 
200## Matching Theme Structure in app.config
201 
202**CRITICAL**: Components have two theme structure patterns. Your app.config MUST match the component's theme structure.
203 
204### Pattern 1: Slots-Based Themes (Most Components)
205 
206Components like Button, Card, Input, Select use `slots:` in their theme:
207 
208```ts
209// Component theme (Button, Card, etc.)
210export default {
211  slots: {
212    base: '...',
213    root: '...',
214    icon: '...'
215  }
216}
217```
218 
219**app.config usage**:
220 
221```ts
222ui: {
223  button: {
224    slots: { base: 'font-bold' }  // ✅ Match slots structure
225  }
226}
227```
228 
229### Pattern 2: Flat Base Themes (Container, Skeleton, etc.)
230 
231Components like Container, Skeleton, Form, Main use flat `base:` in their theme:
232 
233```ts
234// Component theme (Container, Skeleton, etc.)
235export default {
236  base: 'w-full max-w-container'
237}
238```
239 
240**app.config usage**:
241 
242```ts
243ui: {
244  container: {
245    base: 'max-w-lg'  // ✅ Match flat structure
246  }
247}
248```
249 
250### Common Mistake
251 
252```ts
253// ❌ WRONG - Don't use slots for flat-base components
254ui: {
255  container: {
256    slots: { base: 'max-w-lg' }  // TypeScript error!
257  }
258}
259 
260// ❌ WRONG - Don't use flat for slots-based components
261ui: {
262  button: {
263    base: 'font-bold'  // Won't work correctly
264  }
265}
266```
267 
268### How to Check Component Structure
269 
2701. Check component docs: https://ui.nuxt.com/components/[component]
2712. Look at "Theme" section - shows the structure
2723. Match that structure in your app.config
273 
274## Component Theme Structure
275 
276```ts
277// Each component has slots, variants, compoundVariants, defaultVariants
278export default {
279  slots: {
280    root: 'relative',
281    base: 'px-4 py-2',
282    icon: 'size-5'
283  },
284  variants: {
285    color: {
286      primary: { base: 'bg-primary text-inverted' },
287      neutral: { base: 'bg-neutral text-default' }
288    },
289    size: {
290      sm: { base: 'text-sm', icon: 'size-4' },
291      md: { base: 'text-base', icon: 'size-5' },
292      lg: { base: 'text-lg', icon: 'size-6' }
293    }
294  },
295  defaultVariants: {
296    color: 'primary',
297    size: 'md'
298  }
299}
300```
301 
302## Dark Mode
303 
304Handled by `@nuxtjs/color-mode`. Access via:
305 
306```ts
307const colorMode = useColorMode()
308colorMode.preference = 'dark' // 'light', 'dark', 'system'
309```
310 
311```vue
312<UColorModeButton /> <!-- Toggle button -->
313<UColorModeSelect /> <!-- Dropdown select -->
314```
315 
316## Best Practices
317 
318| Do                                     | Don't                         |
319| -------------------------------------- | ----------------------------- |
320| Use semantic colors                    | Hardcode hex values           |
321| Override via app.config                | Modify source theme files     |
322| Use CSS variables for custom colors    | Skip dark mode variants       |
323| Define all 11 shades for custom colors | Use partial shade definitions |
324