Skip to content

secondsky/claude-skills / plugins/nuxt-ui-v4/skills/nuxt-ui-v4

nuxt-ui-v4

Verified

Nuxt UI v4 component library for building Nuxt v4 applications. 125+ accessible components with Tailwind v4, Reka UI, dark mode, theming. Use for dashboards, forms, overlays, editors, page layouts, pricing pages, or encountering component, theming, or TypeScript errors.

FileKindSize
SKILL.mdskill md13.0 KB
references/COMMON_ERRORS_DETAILED.mdmarkdown24.7 KB
references/accessibility-patterns.mdmarkdown822 B
references/ai-sdk-v5-integration.mdmarkdown6.4 KB
references/auth-form.mdmarkdown6.4 KB
references/chat-components.mdmarkdown13.2 KB
references/chat-reasoning.mdmarkdown3.0 KB
references/chat-shimmer.mdmarkdown1.6 KB
references/chat-tool.mdmarkdown3.6 KB
references/command-palette-setup.mdmarkdown1.1 KB
references/common-components.mdmarkdown1.2 KB
references/component-theming-guide.mdmarkdown13.2 KB
references/composables-guide.mdmarkdown908 B
references/content-components.mdmarkdown7.3 KB
references/css-variables-reference.mdmarkdown14.9 KB
references/dark-mode-guide.mdmarkdown10.9 KB
references/dashboard-components.mdmarkdown8.1 KB
references/data-display-components.mdmarkdown11.7 KB
references/design-system-guide.mdmarkdown16.1 KB
references/editor-components.mdmarkdown7.9 KB
references/feedback-components-reference.mdmarkdown11.4 KB
references/form-advanced-patterns.mdmarkdown1.7 KB
references/form-components-reference.mdmarkdown14.0 KB
references/form-validation-patterns.mdmarkdown6.4 KB
references/i18n-integration.mdmarkdown12.8 KB
references/icon-system-guide.mdmarkdown14.5 KB
references/layout-components-reference.mdmarkdown9.5 KB
references/loading-feedback-patterns.mdmarkdown1.0 KB
references/navigation-components-reference.mdmarkdown8.8 KB
references/nuxt-content-integration.mdmarkdown15.7 KB
references/nuxt-v4-features.mdmarkdown8.0 KB
references/overlay-decision-guide.mdmarkdown1.3 KB
references/page-layout-components.mdmarkdown8.4 KB
references/performance-optimization.mdmarkdown12.8 KB
references/pricing-components.mdmarkdown7.7 KB
references/responsive-patterns.mdmarkdown795 B
references/semantic-color-system.mdmarkdown1.3 KB
references/tailwind-prefix-guide.mdmarkdown7.6 KB
references/typescript-setup.mdmarkdown10.8 KB
scripts/check-versions.shexecutablescript1.3 KB
templates/app.config.tsscript2.5 KB
templates/app.vueother1.1 KB
templates/components/ui-avatar-badge.vueother7.7 KB
templates/components/ui-card-layouts.vueother5.9 KB
templates/components/ui-carousel-gallery.vueother1.4 KB
templates/components/ui-chat-full.vueother3.4 KB
templates/components/ui-chat-interface.vueother8.8 KB
templates/components/ui-command-palette.vueother1.8 KB
templates/components/ui-content-prose.vueother7.2 KB
templates/components/ui-dark-mode-toggle.vueother7.4 KB
templates/components/ui-data-table.vueother7.1 KB
templates/components/ui-drawer-mobile.vueother5.2 KB
templates/components/ui-dropdown-menu.vueother6.3 KB
templates/components/ui-empty-state.vueother5.2 KB
templates/components/ui-feedback-states.vueother6.2 KB
templates/components/ui-form-example.vueother4.5 KB
templates/components/ui-input-date.vueother5.2 KB
templates/components/ui-input-time.vueother5.8 KB
templates/components/ui-modal-dialog.vueother8.0 KB
templates/components/ui-navigation-tabs.vueother7.2 KB
templates/components/ui-popover-tooltip.vueother2.6 KB
templates/components/ui-toast-notifications.vueother8.9 KB
templates/composables/useAIChat.tsscript2.9 KB
templates/composables/useI18nForm.tsscript9.6 KB
templates/composables/useNuxtUITheme.tsscript2.4 KB
templates/layouts/dashboard.vueother3.7 KB
templates/nuxt.config.tsscript1.3 KB
templates/pages/landing.vueother5.9 KB

references/design-system-guide.md

View on GitHub
# Design System Guide - Nuxt UI v4

Complete guide to the Nuxt UI v4 design system, covering semantic colors, Tailwind v4 integration, and design token customization.

---

## Overview

Nuxt UI v4's design system is built on three interconnected layers:

1. **Design Tokens** → Raw color values, spacing, typography
2. **CSS Variables** → Semantic mappings that adapt to light/dark modes
3. **Component Theming** → Component-specific styling using tokens and variables

This layered approach enables:
- **Runtime customization** without rebuilds
- **Automatic dark mode** adaptation
- **Semantic naming** for consistent design
- **Type-safe configuration** with full TypeScript support

---

## Semantic Color System

Nuxt UI v4 uses **7 semantic color aliases** that map to Tailwind color scales:

| Semantic Alias | Default Mapping | Purpose |
|---------------|----------------|---------|
| `primary` | `blue` | Primary actions, links, focus states |
| `secondary` | `gray` or `neutral` | Secondary actions, supporting UI |
| `success` | `green` | Success messages, positive states |
| `info` | `blue` or `sky` | Informational messages |
| `warning` | `yellow` or `amber` | Warning messages, cautionary states |
| `error` | `red` | Error messages, destructive actions |
| `neutral` | `gray` or `zinc` | Neutral backgrounds, borders, text |

---

## Runtime Color Configuration

### Nuxt Configuration (app.config.ts)

For **Nuxt applications**, configure colors in `app.config.ts`:

```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      success: 'green',
      info: 'sky',
      warning: 'amber',
      error: 'red',
      neutral: 'zinc'
    }
  }
})
```

**Available Tailwind Colors:**
- `slate`, `gray`, `zinc`, `neutral`, `stone`
- `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`
- `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`

### Vue Configuration (vite.config.ts)

For **Vue-only applications** (no Nuxt), configure in `vite.config.ts`:

```typescript
// 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: 'indigo',
          secondary: 'purple',
          success: 'green',
          error: 'red'
        }
      }
    })
  ]
})
```

---

## Extending the Color System

### Adding Custom Semantic Colors

You can add custom semantic colors beyond the default 7:

**Step 1: Extend theme colors in nuxt.config.ts**
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],

  ui: {
    theme: {
      colors: [
        'primary',
        'secondary',
        'tertiary',    // ← New custom color
        'brand',       // ← New custom color
        'info',
        'success',
        'warning',
        'error',
        'neutral'
      ]
    }
  }
})
```

**Step 2: Map custom colors in app.config.ts**
```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'blue',
      secondary: 'purple',
      tertiary: 'indigo',    // ← Map to Tailwind color
      brand: 'violet',       // ← Map to Tailwind color
      success: 'green',
      info: 'sky',
      warning: 'amber',
      error: 'red',
      neutral: 'zinc'
    }
  }
})
```

**Step 3: Use in components**
```vue
<template>
  <!-- New semantic colors work everywhere -->
  <UButton color="tertiary">Tertiary Action</UButton>
  <UButton color="brand">Brand Action</UButton>

  <UAlert color="brand" title="Brand Message" />

  <UBadge color="tertiary">Tertiary Badge</UBadge>
</template>
```

---

## Tailwind CSS v4 Integration

Nuxt UI v4 uses **Tailwind CSS v4** with CSS-first configuration via the `@theme` directive.

### Basic Tailwind v4 Setup

**app.vue or global CSS:**
```vue
<style>
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  /* Custom design tokens here */
}
</style>
```

### Custom Font Configuration

```css
@theme {
  /* Sans-serif font stack */
  --font-sans: 'Public Sans', 'Inter', system-ui, -apple-system, sans-serif;

  /* Monospace font stack */
  --font-mono: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;

  /* Serif font (if needed) */
  --font-serif: 'Merriweather', 'Georgia', serif;
}
```

Fonts automatically apply to Nuxt UI components and can be controlled via `@nuxt/fonts` module.

### Custom Spacing Tokens

```css
@theme {
  /* Override default spacing */
  --spacing-18: 4.5rem;     /* Add custom 18 unit */
  --spacing-22: 5.5rem;     /* Add custom 22 unit */

  /* Custom named spacing */
  --spacing-sidebar: 16rem;
  --spacing-header: 4rem;
}
```

**Usage:**
```vue
<template>
  <div class="mt-18">  <!-- 4.5rem margin-top -->
  <div class="p-22">   <!-- 5.5rem padding -->
</template>
```

### Custom Breakpoints

```css
@theme {
  /* Add custom breakpoints */
  --breakpoint-3xl: 1920px;
  --breakpoint-4xl: 2560px;
}
```

**Usage:**
```vue
<template>
  <div class="grid grid-cols-1 md:grid-cols-2 3xl:grid-cols-4">
</template>
```

---

## Color Customization with CSS

### Override Tailwind Color Shades

Use `@theme static` to override specific color shades:

```css
@theme static {
  /* Override green shades for custom success color */
  --color-green-50: #EFFDF5;
  --color-green-100: #D9FBE8;
  --color-green-200: #B3F5D1;
  --color-green-300: #75EDAE;
  --color-green-400: #00DC82;  /* Nuxt green */
  --color-green-500: #00C16A;
  --color-green-600: #00A155;
  --color-green-700: #007F45;
  --color-green-800: #016538;
  --color-green-900: #0A5331;
  --color-green-950: #052E16;
}
```

**Note:** When customizing colors, you must provide **all 11 shades** (50-950) for proper light/dark mode adaptation.

### Add Brand Colors

```css
@theme static {
  /* Add custom brand 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;  /* Main brand color */
  --color-brand-600: #DC2626;
  --color-brand-700: #B91C1C;
  --color-brand-800: #991B1B;
  --color-brand-900: #7F1D1D;
  --color-brand-950: #450A0A;
}
```

Then map it to a semantic color:

```typescript
// app.config.ts
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'brand'  // Use custom brand color as primary
    }
  }
})
```

---

## Typography Tokens

### Font Size Scale

Tailwind v4 provides these font sizes as CSS variables:

```css
--font-size-xs: 0.75rem;      /* 12px */
--font-size-sm: 0.875rem;     /* 14px */
--font-size-base: 1rem;       /* 16px */
--font-size-lg: 1.125rem;     /* 18px */
--font-size-xl: 1.25rem;      /* 20px */
--font-size-2xl: 1.5rem;      /* 24px */
--font-size-3xl: 1.875rem;    /* 30px */
--font-size-4xl: 2.25rem;     /* 36px */
--font-size-5xl: 3rem;        /* 48px */
--font-size-6xl: 3.75rem;     /* 60px */
--font-size-7xl: 4.5rem;      /* 72px */
--font-size-8xl: 6rem;        /* 96px */
--font-size-9xl: 8rem;        /* 128px */
```

### Custom Typography

```css
@theme {
  /* Override base font size */
  --font-size-base: 1.0625rem;  /* 17px instead of 16px */

  /* Add custom sizes */
  --font-size-xxs: 0.625rem;    /* 10px */
}
```

### Line Heights

```css
--line-height-none: 1;
--line-height-tight: 1.25;
--line-height-snug: 1.375;
--line-height-normal: 1.5;
--line-height-relaxed: 1.625;
--line-height-loose: 2;
```

---

## Using Semantic Tokens in Templates

Semantic color tokens work across all Nuxt UI components:

### Text Colors

```vue
<template>
  <!-- Semantic text colors -->
  <p class="text-primary">Primary text</p>
  <p class="text-secondary">Secondary text</p>
  <p class="text-success">Success text</p>
  <p class="text-info">Info text</p>
  <p class="text-warning">Warning text</p>
  <p class="text-error">Error text</p>

  <!-- Neutral text levels -->
  <p class="text-highlighted">Highest emphasis</p>
  <p class="text-default">Default text</p>
  <p class="text-muted">Muted text</p>
  <p class="text-dimmed">Lowest emphasis</p>
</template>
```

### Background Colors

```vue
<template>
  <!-- Semantic backgrounds -->
  <div class="bg-primary text-white">Primary background</div>
  <div class="bg-success text-white">Success background</div>
  <div class="bg-error text-white">Error background</div>

  <!-- Surface backgrounds -->
  <div class="bg-default">Page background</div>
  <div class="bg-elevated">Card background</div>
  <div class="bg-accented">Highlighted background</div>
</template>
```

### Border Colors

```vue
<template>
  <!-- Semantic borders -->
  <div class="border border-primary">Primary border</div>
  <div class="border border-success">Success border</div>
  <div class="border border-error">Error border</div>

  <!-- Neutral borders -->
  <div class="border border-default">Default border</div>
  <div class="border border-muted">Muted border</div>
</template>
```

---

## Design Token Interconnections

Understanding how the three layers work together:

```
┌─────────────────────────────────────────────────────────┐
│ LAYER 1: Design Tokens (Tailwind Color Scale)          │
│ --color-blue-500: #3B82F6                              │
│ --color-blue-400: #60A5FA                              │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│ LAYER 2: CSS Variables (Semantic Mapping)              │
│ Light: --ui-primary: var(--color-blue-500)             │
│ Dark:  --ui-primary: var(--color-blue-400)             │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│ LAYER 3: Component Theming                             │
│ UButton uses: background-color: var(--ui-primary)      │
│ Adapts automatically to light/dark mode                │
└─────────────────────────────────────────────────────────┘
```

### Flow Example

**Configuration:**
```typescript
// app.config.ts
ui: {
  colors: {
    primary: 'indigo'  // Step 1: Choose Tailwind color
  }
}
```

**Generated CSS Variables:**
```css
/* Light mode */
--ui-primary: var(--color-indigo-500);  /* Step 2: Map to shade 500 */

/* Dark mode */
.dark {
  --ui-primary: var(--color-indigo-400);  /* Automatically shifts to 400 */
}
```

**Component Usage:**
```vue
<!-- Step 3: Components use the variable -->
<UButton>Primary Action</UButton>
<!-- Button background uses var(--ui-primary) -->
<!-- Automatically blue-500 (light) or blue-400 (dark) -->
```

---

## Auto-Adaptation for Light/Dark Modes

All design tokens automatically adapt between color modes:

### Color Shifts

**Semantic Colors:**
- Light mode: Uses `*-500` shade
- Dark mode: Uses `*-400` shade (lighter for contrast)

**Text Colors:**
- Light mode: `neutral-700` to `neutral-900`
- Dark mode: `neutral-200` to `white`

**Backgrounds:**
- Light mode: `white` to `neutral-100`
- Dark mode: `neutral-950` to `neutral-800`

**Borders:**
- Light mode: `neutral-200` to `neutral-300`
- Dark mode: `neutral-800` to `neutral-700`

### Example: Button Adaptation

```vue
<template>
  <UButton color="primary">Click Me</UButton>
</template>
```

**Light Mode:**
- Background: `blue-500` (vibrant)
- Text: `white`
- Border: `blue-500`

**Dark Mode:**
- Background: `blue-400` (lighter, more visible)
- Text: `neutral-900` (dark text on light background)
- Border: `blue-400`

No manual dark mode selectors needed!

---

## Complete Customization Example

Create a fully custom design system:

**app.config.ts:**
```typescript
export default defineAppConfig({
  ui: {
    colors: {
      primary: 'violet',
      secondary: 'fuchsia',
      success: 'emerald',
      info: 'cyan',
      warning: 'amber',
      error: 'rose',
      neutral: 'slate'
    },
    theme: {
      defaultVariants: {
        Button: {
          size: 'lg',
          rounded: 'full'  // All buttons rounded-full by default
        },
        Input: {
          size: 'lg',
          variant: 'outline'
        }
      }
    }
  }
})
```

**app.vue:**
```vue
<style>
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  /* Custom fonts */
  --font-sans: 'Sora', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom radius */
  --ui-radius: 0.75rem;  /* More rounded */

  /* Custom container */
  --ui-container: 90rem;  /* Wider */

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;
}

@theme static {
  /* Custom violet shades for primary */
  --color-violet-50: #FAF5FF;
  --color-violet-100: #F3E8FF;
  --color-violet-200: #E9D5FF;
  --color-violet-300: #D8B4FE;
  --color-violet-400: #C084FC;
  --color-violet-500: #A855F7;  /* Main violet */
  --color-violet-600: #9333EA;
  --color-violet-700: #7E22CE;
  --color-violet-800: #6B21A8;
  --color-violet-900: #581C87;
  --color-violet-950: #3B0764;
}
</style>
```

**Result:**
- Primary color: Violet
- All buttons: Large + fully rounded
- Custom fonts throughout
- Wider container (1440px)
- Custom breakpoint at 1920px

---

## Best Practices

### 1. Use Semantic Colors

```vue
<!-- ✅ GOOD: Semantic -->
<UButton color="primary">Save</UButton>
<UButton color="error">Delete</UButton>

<!-- ❌ AVOID: Direct colors -->
<UButton color="blue">Save</UButton>
<UButton color="red">Delete</UButton>
```

### 2. Configure at Runtime

```typescript
// ✅ GOOD: Runtime config
// app.config.ts
ui: {
  colors: {
    primary: 'indigo'
  }
}

// ❌ AVOID: Hardcoded in components
```

### 3. Use @theme for Global Changes

```css
/* ✅ GOOD: Global tokens */
@theme {
  --ui-radius: 0.5rem;
}

/* ❌ AVOID: Component-by-component overrides */
```

### 4. Provide All Color Shades

When adding custom colors with `@theme static`, **always provide all 11 shades** (50-950):

```css
/* ✅ GOOD: Complete scale */
@theme static {
  --color-brand-50: #...;
  --color-brand-100: #...;
  /* ... all the way to ... */
  --color-brand-950: #...;
}

/* ❌ INCOMPLETE: Missing shades breaks dark mode */
@theme static {
  --color-brand-500: #EF4444;  /* Only one shade */
}
```

### 5. Test Both Color Modes

Always test your design system in both light and dark modes:

```vue
<script setup lang="ts">
const { toggleColorMode } = useColorMode()
</script>

<template>
  <UButton @click="toggleColorMode">
    Toggle Mode (Test Design)
  </UButton>
</template>
```

---

## Troubleshooting

### Semantic Color Not Working

**Problem:** `color="tertiary"` doesn't work on components.

**Solution:** Add to theme colors array:
```typescript
// nuxt.config.ts
ui: {
  theme: {
    colors: ['primary', 'secondary', 'tertiary', ...]
  }
}
```

### Custom Font Not Applying

**Problem:** Font specified in `@theme` doesn't apply.

**Solution 1:** Ensure font is imported:
```css
@import url('https://fonts.googleapis.com/css2?family=Sora:wght@400;500;600;700&display=swap');

@theme {
  --font-sans: 'Sora', system-ui, sans-serif;
}
```

**Solution 2:** Use `@nuxt/fonts` module:
```typescript
// nuxt.config.ts
modules: ['@nuxt/ui', '@nuxt/fonts']
```

### Dark Mode Colors Look Wrong

**Problem:** Colors don't look good in dark mode.

**Solution:** Dark mode automatically uses lighter shades (400 instead of 500). If still bad, choose a different base color that has better dark mode shades.

---

## Resources

- **Tailwind CSS v4**: https://tailwindcss.com/docs/v4-beta
- **Tailwind Colors**: https://tailwindcss.com/docs/customizing-colors
- **Nuxt UI Theming**: https://ui.nuxt.com/getting-started/theme
- **@nuxt/fonts**: https://fonts.nuxt.com/

---

**Last Updated**: 2025-01-09
**Nuxt UI Version**: 4.0.0
**Tailwind CSS Version**: 4.0.0
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall