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/css-variables-reference.md

View on GitHub
# CSS Variables Reference - Nuxt UI v4

Complete reference for all CSS variables in Nuxt UI v4 and how to use them for custom styling.

---

## Overview

Nuxt UI v4 uses CSS variables for theming, enabling:
- **Runtime customization** without recompilation
- **Dark mode** automatic adaptation
- **Semantic naming** for consistent design
- **Direct CSS usage** in custom components

All variables automatically adjust for light/dark color modes.

---

## Semantic Color Variables

### Primary, Secondary, and Semantic Colors

These map to your configured theme colors and adjust between light/dark modes.

**Light Mode:**
```css
:root {
  --ui-primary: var(--ui-color-primary-500);
  --ui-secondary: var(--ui-color-secondary-500);
  --ui-success: var(--ui-color-success-500);
  --ui-info: var(--ui-color-info-500);
  --ui-warning: var(--ui-color-warning-500);
  --ui-error: var(--ui-color-error-500);
  --ui-neutral: var(--ui-color-neutral-500);
}
```

**Dark Mode:**
```css
.dark {
  --ui-primary: var(--ui-color-primary-400);
  --ui-secondary: var(--ui-color-secondary-400);
  --ui-success: var(--ui-color-success-400);
  --ui-info: var(--ui-color-info-400);
  --ui-warning: var(--ui-color-warning-400);
  --ui-error: var(--ui-color-error-400);
  --ui-neutral: var(--ui-color-neutral-400);
}
```

**Note:** Dark mode shifts from 500 → 400 for better contrast on dark backgrounds.

### Usage in Custom CSS

```css
/* Custom button using semantic colors */
.my-custom-button {
  background-color: var(--ui-primary);
  color: white;
  border: 1px solid var(--ui-primary);
}

.my-custom-button:hover {
  background-color: color-mix(in srgb, var(--ui-primary) 90%, black);
}

/* Success state */
.success-badge {
  background-color: var(--ui-success);
  color: white;
}

/* Error message */
.error-text {
  color: var(--ui-error);
}
```

---

## Text Color Variables

Used for typography with semantic naming based on emphasis level.

### Complete Text Variable List

**Light Mode:**
```css
:root {
  --ui-text-highlighted: var(--ui-color-neutral-900);
  --ui-text: var(--ui-color-neutral-700);
  --ui-text-toned: var(--ui-color-neutral-600);
  --ui-text-muted: var(--ui-color-neutral-500);
  --ui-text-dimmed: var(--ui-color-neutral-400);
  --ui-text-inverted: white;
}
```

**Dark Mode:**
```css
.dark {
  --ui-text-highlighted: white;
  --ui-text: var(--ui-color-neutral-200);
  --ui-text-toned: var(--ui-color-neutral-300);
  --ui-text-muted: var(--ui-color-neutral-400);
  --ui-text-dimmed: var(--ui-color-neutral-500);
  --ui-text-inverted: var(--ui-color-neutral-900);
}
```

### Utility Class Mapping

| CSS Variable | Utility Class | Use Case |
|--------------|---------------|----------|
| `--ui-text-highlighted` | `text-highlighted` | Primary headings, emphasized text |
| `--ui-text` | `text-default` | Body text, default paragraphs |
| `--ui-text-toned` | `text-toned` | Slightly subdued text |
| `--ui-text-muted` | `text-muted` | Secondary information |
| `--ui-text-dimmed` | `text-dimmed` | Tertiary info, placeholders |
| `--ui-text-inverted` | `text-inverted` | Text on dark backgrounds |

### Usage Examples

```vue
<template>
  <!-- Using utility classes -->
  <h1 class="text-highlighted">Main Heading</h1>
  <p class="text-default">Body paragraph text.</p>
  <span class="text-muted">Secondary info</span>
  <small class="text-dimmed">Helper text</small>

  <!-- Using CSS variables directly -->
  <div :style="{ color: 'var(--ui-text-muted)' }">
    Custom styled text
  </div>
</template>

<style scoped>
/* Custom component using variables */
.my-label {
  color: var(--ui-text);
  font-weight: 500;
}

.my-description {
  color: var(--ui-text-muted);
  font-size: 0.875rem;
}

.my-placeholder {
  color: var(--ui-text-dimmed);
}
</style>
```

---

## Background Color Variables

Used for surfaces, cards, and container backgrounds.

### Complete Background Variable List

**Light Mode:**
```css
:root {
  --ui-bg: white;
  --ui-bg-elevated: var(--ui-color-neutral-50);
  --ui-bg-muted: var(--ui-color-neutral-50);
  --ui-bg-accented: var(--ui-color-neutral-100);
  --ui-bg-inverted: var(--ui-color-neutral-900);
}
```

**Dark Mode:**
```css
.dark {
  --ui-bg: var(--ui-color-neutral-950);
  --ui-bg-elevated: var(--ui-color-neutral-900);
  --ui-bg-muted: var(--ui-color-neutral-900);
  --ui-bg-accented: var(--ui-color-neutral-800);
  --ui-bg-inverted: white;
}
```

### Utility Class Mapping

| CSS Variable | Utility Class | Use Case |
|--------------|---------------|----------|
| `--ui-bg` | `bg-default` | Page background |
| `--ui-bg-elevated` | `bg-elevated` | Cards, modals (higher elevation) |
| `--ui-bg-muted` | `bg-muted` | Subtle backgrounds |
| `--ui-bg-accented` | `bg-accented` | More prominent backgrounds |
| `--ui-bg-inverted` | `bg-inverted` | Inverse backgrounds |

### Additional Background Variables

```css
:root {
  --ui-bg-overlay: rgba(0, 0, 0, 0.5);     /* Modal/dialog overlays */
  --ui-bg-disabled: var(--ui-color-neutral-100);
}

.dark {
  --ui-bg-overlay: rgba(0, 0, 0, 0.75);
  --ui-bg-disabled: var(--ui-color-neutral-800);
}
```

### Usage Examples

```vue
<template>
  <!-- Using utility classes -->
  <div class="bg-default">Page container</div>
  <div class="bg-elevated">Card with elevation</div>
  <div class="bg-accented">Highlighted section</div>
</template>

<style scoped>
/* Custom card component */
.custom-card {
  background-color: var(--ui-bg-elevated);
  padding: 1.5rem;
  border-radius: var(--ui-radius);
}

/* Hover state */
.custom-card:hover {
  background-color: var(--ui-bg-accented);
}

/* Modal overlay */
.modal-backdrop {
  background-color: var(--ui-bg-overlay);
}
</style>
```

---

## Border Color Variables

Used for borders, dividers, and outlines.

### Complete Border Variable List

**Light Mode:**
```css
:root {
  --ui-border: var(--ui-color-neutral-200);
  --ui-border-muted: var(--ui-color-neutral-200);
  --ui-border-accented: var(--ui-color-neutral-300);
  --ui-border-inverted: var(--ui-color-neutral-900);
}
```

**Dark Mode:**
```css
.dark {
  --ui-border: var(--ui-color-neutral-800);
  --ui-border-muted: var(--ui-color-neutral-800);
  --ui-border-accented: var(--ui-color-neutral-700);
  --ui-border-inverted: white;
}
```

### Utility Class Mapping

| CSS Variable | Utility Class | Use Case |
|--------------|---------------|----------|
| `--ui-border` | `border-default` | Standard borders |
| `--ui-border-muted` | `border-muted` | Subtle dividers |
| `--ui-border-accented` | `border-accented` | Emphasized borders |
| `--ui-border-inverted` | `border-inverted` | Inverse borders |

### Usage Examples

```vue
<template>
  <!-- Using utility classes -->
  <div class="border border-default">Default border</div>
  <hr class="border-t border-muted" />
  <div class="border-2 border-accented">Emphasized</div>
</template>

<style scoped>
/* Custom divider */
.section-divider {
  border-top: 1px solid var(--ui-border-muted);
  margin: 2rem 0;
}

/* Input with border */
.custom-input {
  border: 1px solid var(--ui-border);
  border-radius: var(--ui-radius);
}

.custom-input:focus {
  border-color: var(--ui-primary);
  outline: none;
}
</style>
```

---

## Border Radius System

Nuxt UI v4 uses a single radius variable that scales across all components.

### Radius Variable

```css
:root {
  --ui-radius: 0.375rem;  /* 6px - default */
}
```

### Radius Multipliers

All `rounded-*` utilities scale from `--ui-radius`:

```css
.rounded-sm  { border-radius: calc(var(--ui-radius) * 0.5); }   /* 3px */
.rounded     { border-radius: var(--ui-radius); }                /* 6px */
.rounded-md  { border-radius: calc(var(--ui-radius) * 1.33); }  /* 8px */
.rounded-lg  { border-radius: calc(var(--ui-radius) * 2); }     /* 12px */
.rounded-xl  { border-radius: calc(var(--ui-radius) * 3); }     /* 18px */
.rounded-2xl { border-radius: calc(var(--ui-radius) * 4); }     /* 24px */
.rounded-3xl { border-radius: calc(var(--ui-radius) * 6); }     /* 36px */
.rounded-full{ border-radius: 9999px; }
```

### Customizing Global Radius

**Method 1: CSS (Tailwind v4)**
```css
/* app.vue <style> */
@import "tailwindcss";
@import "@nuxt/ui";

@theme {
  --ui-radius: 0.5rem;  /* 8px - more rounded */
}
```

**Method 2: app.config.ts (if supported)**
```typescript
export default defineAppConfig({
  ui: {
    theme: {
      radius: '0.5rem'
    }
  }
})
```

### Usage Examples

```vue
<template>
  <!-- Using utility classes -->
  <div class="rounded">Standard radius</div>
  <div class="rounded-lg">Large radius</div>
  <div class="rounded-full">Circular</div>
</template>

<style scoped>
/* Custom component using radius variable */
.custom-card {
  border-radius: var(--ui-radius);
}

/* Slightly more rounded */
.custom-button {
  border-radius: calc(var(--ui-radius) * 1.5);
}
</style>
```

---

## Layout Variables

Used for consistent spacing and sizing across the application.

### Container Width

```css
:root {
  --ui-container: 80rem;  /* 1280px - default max width */
}
```

**Usage:**
```css
.container {
  max-width: var(--ui-container);
  margin-inline: auto;
}
```

### Header Height

```css
:root {
  --ui-header-height: 4rem;  /* 64px - default header height */
}
```

**Usage:**
```css
.main-content {
  /* Account for fixed header */
  padding-top: var(--ui-header-height);
}

.sticky-header {
  height: var(--ui-header-height);
  position: sticky;
  top: 0;
}
```

### Spacing Variables

Tailwind CSS v4 spacing uses CSS variables:

```css
:root {
  --spacing-1: 0.25rem;   /* 4px */
  --spacing-2: 0.5rem;    /* 8px */
  --spacing-3: 0.75rem;   /* 12px */
  --spacing-4: 1rem;      /* 16px */
  --spacing-6: 1.5rem;    /* 24px */
  --spacing-8: 2rem;      /* 32px */
  --spacing-12: 3rem;     /* 48px */
  --spacing-16: 4rem;     /* 64px */
  /* ... and more */
}
```

---

## Ring (Focus) Variables

Used for focus rings and outlines.

```css
:root {
  --ui-ring: var(--ui-primary);
  --ui-ring-offset: white;
}

.dark {
  --ui-ring: var(--ui-primary);
  --ui-ring-offset: var(--ui-color-neutral-950);
}
```

**Usage:**
```css
.custom-input:focus {
  outline: 2px solid var(--ui-ring);
  outline-offset: 2px;
}

/* Or with Tailwind utilities */
.focus\:ring {
  box-shadow: 0 0 0 3px var(--ui-ring);
}
```

---

## Shadow Variables

```css
:root {
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
}
```

---

## Complete Variable Usage Example

```vue
<template>
  <div class="custom-component">
    <div class="custom-header">
      <h2>Component Title</h2>
    </div>

    <div class="custom-body">
      <p>Component content</p>
    </div>

    <div class="custom-footer">
      <button class="custom-button">Action</button>
    </div>
  </div>
</template>

<style scoped>
.custom-component {
  /* Layout */
  max-width: var(--ui-container);
  margin: 0 auto;

  /* Background */
  background-color: var(--ui-bg-elevated);

  /* Border */
  border: 1px solid var(--ui-border);
  border-radius: var(--ui-radius);

  /* Shadow */
  box-shadow: var(--shadow-md);
}

.custom-header {
  /* Background (slightly different) */
  background-color: var(--ui-bg-accented);

  /* Border bottom */
  border-bottom: 1px solid var(--ui-border-muted);

  /* Spacing */
  padding: var(--spacing-4) var(--spacing-6);
}

.custom-header h2 {
  /* Text */
  color: var(--ui-text-highlighted);
  margin: 0;
}

.custom-body {
  padding: var(--spacing-6);
  color: var(--ui-text);
}

.custom-footer {
  padding: var(--spacing-4) var(--spacing-6);
  border-top: 1px solid var(--ui-border-muted);
  background-color: var(--ui-bg-muted);
}

.custom-button {
  /* Colors */
  background-color: var(--ui-primary);
  color: white;

  /* Border and radius */
  border: none;
  border-radius: var(--ui-radius);

  /* Spacing */
  padding: var(--spacing-2) var(--spacing-4);

  /* Cursor */
  cursor: pointer;
}

.custom-button:hover {
  /* Darken primary color on hover */
  background-color: color-mix(in srgb, var(--ui-primary) 90%, black);
}

.custom-button:focus {
  /* Focus ring */
  outline: 2px solid var(--ui-ring);
  outline-offset: 2px;
}
</style>
```

---

## Dark Mode Behavior

All CSS variables automatically update when dark mode is enabled.

**Automatic Updates:**
```vue
<template>
  <!-- Same code works in both modes -->
  <div class="bg-elevated border border-default">
    <p class="text-default">This text adapts automatically</p>
  </div>
</template>
```

**Light Mode Result:**
- `bg-elevated` → `white` or `neutral-50`
- `border-default` → `neutral-200`
- `text-default` → `neutral-700`

**Dark Mode Result:**
- `bg-elevated` → `neutral-900`
- `border-default` → `neutral-800`
- `text-default` → `neutral-200`

---

## Customizing CSS Variables

### Global Customization (Tailwind v4)

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

@theme {
  /* Override radius */
  --ui-radius: 0.5rem;

  /* Override container width */
  --ui-container: 90rem;

  /* Add custom variables */
  --my-custom-spacing: 2.5rem;
}
```

### Runtime Customization (JavaScript)

```vue
<script setup lang="ts">
onMounted(() => {
  // Change global radius at runtime
  document.documentElement.style.setProperty('--ui-radius', '0.75rem')

  // Change container width
  document.documentElement.style.setProperty('--ui-container', '100rem')
})
</script>
```

---

## Best Practices

### 1. Use Semantic Variables

```css
/* ✅ GOOD: Semantic meaning */
.error-message {
  color: var(--ui-error);
}

/* ❌ AVOID: Direct color values */
.error-message {
  color: var(--ui-color-red-500);
}
```

### 2. Prefer Utility Classes

```vue
<!-- ✅ GOOD: Utility classes -->
<div class="bg-elevated border border-default">

<!-- ⚠️ OK but verbose: Inline styles -->
<div :style="{
  backgroundColor: 'var(--ui-bg-elevated)',
  border: '1px solid var(--ui-border)'
}">
```

### 3. Use Variables for Custom Components

```css
/* ✅ GOOD: Variables for consistency */
.custom-card {
  background: var(--ui-bg-elevated);
  border: 1px solid var(--ui-border);
  border-radius: var(--ui-radius);
}

/* ❌ AVOID: Hardcoded values */
.custom-card {
  background: white;
  border: 1px solid #e5e7eb;
  border-radius: 6px;
}
```

### 4. Dark Mode is Automatic

Don't write manual dark mode selectors when using CSS variables:

```css
/* ✅ GOOD: Automatic dark mode */
.my-component {
  background: var(--ui-bg-elevated);
  color: var(--ui-text);
}

/* ❌ AVOID: Manual dark mode (unnecessary) */
.my-component {
  background: white;
  color: #374151;
}

.dark .my-component {
  background: #1f2937;
  color: #e5e7eb;
}
```

---

## Resources

- **Tailwind CSS v4 Docs**: https://tailwindcss.com/docs/v4-beta
- **Nuxt UI Theming**: https://ui.nuxt.com/getting-started/theme
- **CSS Variables MDN**: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties

---

**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