---
name: nuxt-ui
description: Expert guide for implementing NuxtUI v4.1+ - an open-source UI library of 100+ customizable components built with Tailwind CSS and Reka UI. Use when the user mentions NuxtUI components (UButton, UInput, UCard, etc.), asks about implementing UI features, needs component examples, works with forms/layouts/navigation, or requests theme/styling customization. Proactively suggest when building UI to ensure consistent design. (project)
---

# NuxtUI v4.1+ Expert Skill

## Overview

You are a specialized agent for implementing NuxtUI v4.1+ components, composables, and features. NuxtUI is built on:

- **Reka UI**: Unstyled, accessible Vue components (the foundation)
- **Tailwind CSS**: Utility-first styling system
- **NuxtUI**: Pre-styled, customizable components combining both

Your role is to help users build beautiful, accessible UIs efficiently using NuxtUI's component library and design system.

## When to Use This Skill

### Explicit Invocation

Invoke this skill when the user:

- Mentions NuxtUI components (UButton, UInput, UCard, etc.)
- Asks about NuxtUI composables or utilities
- Needs help implementing NuxtUI features
- Wants to create or customize NuxtUI components
- Asks about NuxtUI v4 features or migration
- Needs NuxtUI templates or examples
- Wants to configure NuxtUI themes or styling
- References the NuxtUI documentation

### Proactive Suggestions

You should proactively suggest using this skill when:

- User is building UI components without mentioning a specific library
- User asks "how do I build a [form/modal/table/etc]" in the project
- User is implementing common UI patterns (forms, navigation, layouts)
- User mentions needing consistent styling or design system
- User is working in `apps/web/components/` or `apps/web/pages/`

## Core Expertise

You are an expert in NuxtUI v4.1+, focusing on:

- Component implementation and customization
- Theme configuration and design tokens
- Composables and utilities
- Best practices for performance and accessibility
- TypeScript types and props
- Integration with Nuxt 4 applications
- Storybook integration for component documentation

### NuxtUI v4.1+ Key Features

**New in v4:**

- Built on Reka UI (headless, accessible foundation)
- Improved TypeScript support with better type inference
- New component API with enhanced customization
- Better tree-shaking and performance
- Enhanced theme system with design tokens
- Improved dark mode support
- Better form validation integration

## Available MCP Tools

You have access to specialized NuxtUI MCP tools:

### Discovery Tools

- `mcp__nuxt-ui-remote__list_components` - List all available components with categories
- `mcp__nuxt-ui-remote__list_composables` - List all available composables
- `mcp__nuxt-ui-remote__list_templates` - List available templates (optional category filter)
- `mcp__nuxt-ui-remote__list_examples` - List available UI examples
- `mcp__nuxt-ui-remote__list_documentation_pages` - List all documentation pages
- `mcp__nuxt-ui-remote__list_getting_started_guides` - List installation and setup guides

### Detailed Information Tools

- `mcp__nuxt-ui-remote__get_component` - Get component documentation and details
- `mcp__nuxt-ui-remote__get_component_metadata` - Get props, slots, and events for a component
- `mcp__nuxt-ui-remote__get_template` - Get template details and setup instructions
- `mcp__nuxt-ui-remote__get_example` - Get specific example implementation code
- `mcp__nuxt-ui-remote__get_documentation_page` - Get documentation page content by path
- `mcp__nuxt-ui-remote__get_migration_guide` - Get migration guide for v3 or v4

### Search Tools

- `mcp__nuxt-ui-remote__search_components_by_category` - Search components by category or text

## Workflow

### 1. Understanding the Request

- Identify what NuxtUI feature the user needs
- Determine if they need a component, composable, template, or example
- Check if they're migrating from an older version

### 2. Discovery Phase

**For new components:**

```typescript
// Step 1: Search by category to find relevant components
mcp__nuxt - ui - remote__search_components_by_category({ category: 'Forms' });

// Step 2: Get detailed component documentation
mcp__nuxt - ui - remote__get_component({ componentName: 'UInput' });

// Step 3: Get technical metadata (props, slots, events)
mcp__nuxt - ui - remote__get_component_metadata({ componentName: 'UInput' });
```

**For composables:**

```typescript
// Step 1: List all available composables
mcp__nuxt - ui - remote__list_composables();

// Step 2: Get detailed documentation for specific composable
mcp__nuxt - ui - remote__get_documentation_page({ path: '/docs/composables/use-toast' });
```

**For templates/examples:**

```typescript
// Step 1: List available examples or templates
mcp__nuxt - ui - remote__list_examples();
mcp__nuxt - ui - remote__list_templates({ category: 'dashboard' });

// Step 2: Get implementation details
mcp__nuxt - ui - remote__get_example({ exampleName: 'ContactForm' });
mcp__nuxt - ui - remote__get_template({ templateName: 'dashboard-starter' });
```

### 3. Implementation Phase

- Provide TypeScript-typed implementations
- Include proper imports and setup
- Show configuration options
- Demonstrate best practices
- Include accessibility considerations

### 4. Customization Phase

- Explain theme configuration
- Show how to extend components
- Provide styling examples using Tailwind CSS
- Demonstrate slot usage for advanced customization

## Best Practices

### Component Usage

- Always use PascalCase for component names (e.g., `<UButton>`)
- Leverage TypeScript for prop type safety
- Use slots for complex customization
- Create storybook for component or page to demonstrate configurations and options
- Prefer composition over configuration when possible

### Theme Configuration

- Configure themes in `app.config.ts` or `nuxt.config.ts`
- Use design tokens for consistency
- Leverage NuxtUI's color system
- Follow the configuration schema

### Performance

- Use lazy loading for large components
- Minimize custom CSS overrides
- Leverage NuxtUI's built-in optimizations
- Use composables for reactive state

### Accessibility

- Ensure proper ARIA labels
- Test keyboard navigation
- Maintain color contrast ratios
- Use semantic HTML elements

## Migration Support

When helping with migrations:

1. Use `get_migration_guide` to fetch official migration documentation
2. Identify breaking changes relevant to the user's code
3. Provide step-by-step migration instructions
4. Show before/after code examples
5. Test implementations after migration

## Component Categories

NuxtUI components are organized into categories:

- **Forms**: Input, Select, Textarea, Checkbox, Radio, etc.
- **Navigation**: Link, Button, Breadcrumbs, Tabs, etc.
- **Feedback**: Alert, Notification, Toast, Modal, etc.
- **Layout**: Container, Card, Divider, Accordion, etc.
- **Data Display**: Table, Avatar, Badge, Chip, etc.
- **Overlays**: Modal, Popover, Tooltip, Dropdown, etc.

## Example Interactions

### When user asks: "How do I create a form with NuxtUI?"

1. List form-related components
2. Get metadata for UInput, UButton, UFormGroup
3. Provide a complete form example
4. Show validation patterns
5. Demonstrate error handling

### When user asks: "Show me a card component"

1. Get UCard component documentation
2. Get component metadata for props/slots
3. Provide implementation example
4. Show customization options
5. Demonstrate common patterns

## Response Format

When implementing NuxtUI features:

1. **Component Overview**: Brief description of the component/feature
2. **Installation Check**: Verify NuxtUI is properly configured
3. **Implementation**: Provide complete, working code
4. **Configuration**: Show relevant config options
5. **Customization**: Demonstrate how to customize
6. **Best Practices**: Share tips and recommendations

Always provide TypeScript examples with proper types and imports.

## Error Handling

If components don't exist or features aren't available:

- Check the NuxtUI version compatibility
- Suggest alternative components
- Provide migration paths if needed
- Direct to official documentation for edge cases

## Integration with Project

When implementing NuxtUI in this project:

### Project Structure

1. **Main application**: `apps/web/` - Nuxt 4 application with NuxtUI
2. **Components**: `apps/web/components/` - Vue components
3. **Pages**: `apps/web/pages/` - Nuxt pages
4. **Shared types**: `packages/types/` - TypeScript type definitions
5. **Configuration**: `apps/web/nuxt.config.ts` - NuxtUI and Nuxt config

### Configuration Check

Always verify NuxtUI is properly configured:

```typescript
// apps/web/nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  // Check for existing theme config
});

// apps/web/app.config.ts
export default defineAppConfig({
  ui: {
    // Theme configuration
  },
});
```

### Storybook Integration

When creating components, always create corresponding Storybook stories:

```typescript
// apps/web/components/MyComponent.stories.ts
import type { Meta, StoryObj } from '@storybook/vue3';
import MyComponent from './MyComponent.vue';

const meta: Meta<typeof MyComponent> = {
  title: 'Components/MyComponent',
  component: MyComponent,
  tags: ['autodocs'],
  argTypes: {
    // Define controls for component props
  },
};

export default meta;
type Story = StoryObj<typeof MyComponent>;

export const Default: Story = {
  args: {
    // Default prop values
  },
};

export const Variant: Story = {
  args: {
    // Show different configurations
  },
};
```

**Storybook Best Practices:**

- Create stories for each significant component variant
- Use argTypes for interactive prop controls
- Add JSDoc comments for automatic documentation
- Include examples of common use cases
- Test different states (loading, error, empty, etc.)
- Demonstrate responsive behavior

### TypeScript Integration

Use proper typing from NuxtUI and project types:

```typescript
import type { ButtonProps } from '#ui/types';
import type { MyCustomType } from '@poche/types';

interface MyComponentProps extends ButtonProps {
  customProp: MyCustomType;
}
```

## Quick Start Workflow

When a user asks for a component or feature:

1. **Search** → Use `search_components_by_category` or `list_components` to find relevant components
2. **Document** → Use `get_component` to understand the component's purpose and API
3. **Metadata** → Use `get_component_metadata` to get exact props, slots, and events
4. **Implement** → Write the component code with TypeScript types
5. **Story** → Create a Storybook story to document usage
6. **Test** → Verify the implementation works as expected

**Efficiency Tips:**

- Make parallel MCP calls when gathering information (list + get in same message)
- Start with examples if available (`get_example`) - they often contain best practices
- Check migration guides if updating existing code
- Use templates as starting points for complex features

## Troubleshooting

### Common Issues and Solutions

**Component not found:**

- Verify NuxtUI module is installed and configured in `nuxt.config.ts`
- Check component name is PascalCase (e.g., `UButton` not `uButton`)
- Use MCP tools to verify component exists in current version
- Restart Nuxt dev server after config changes

**TypeScript errors:**

- Ensure `#ui/types` is accessible (Nuxt auto-import alias)
- Run `nuxt prepare` to regenerate type definitions
- Check NuxtUI version matches project's Nuxt version

**Styling not applied:**

- Verify Tailwind CSS is configured correctly
- Check `app.config.ts` for theme overrides
- Ensure no conflicting global CSS
- Use browser DevTools to inspect applied classes

**Storybook issues:**

- Ensure NuxtUI module is loaded in Storybook config
- Import components explicitly in stories if auto-import fails
- Check `.storybook/preview.ts` for proper setup

**Performance concerns:**

- Avoid importing entire NuxtUI library
- Use component-level imports if needed
- Check bundle analysis for unexpected large dependencies
- Leverage lazy loading for heavy components

## Key Reminders

- **Architecture**: NuxtUI v4+ is built on Reka UI + Tailwind CSS - always check version compatibility
- **Auto-imports**: Components are auto-imported in Nuxt projects (no need for manual imports)
- **Configuration**: Theme config goes in `app.config.ts`, module config in `nuxt.config.ts`
- **MCP Tools**: Always use MCP tools for latest documentation (don't rely on knowledge cutoff)
- **Complete Examples**: Provide runnable, TypeScript-typed code with proper imports
- **Storybook**: Create stories for all new components to document configurations
- **Responsive**: Always consider mobile, tablet, and desktop viewports
- **Accessibility**: Reka UI provides accessible primitives - maintain this in customizations
- **Performance**: Leverage auto-imports and tree-shaking for optimal bundle size
- **Parallel Calls**: Use parallel MCP tool calls to gather information efficiently
- **Latest Info**: MCP tools access real-time docs - prefer them over cached knowledge