Nuxt UI Development

Guidelines for contributing to the Nuxt UI component library.

Project Structure

src/ ├── runtime/ │ ├── components/ # Vue components (PascalCase.vue) │ ├── composables/ # Composables (use*.ts) │ ├── types/ # TypeScript types │ └── utils/ # Utility functions ├── theme/ # Tailwind Variants themes (kebab-case.ts) └── module.ts test/ ├── components/ # Component tests (.spec.ts) │ └── snapshots/ # Auto-generated snapshots └── component-render.ts docs/ └── content/docs/2.components/ # Documentation (.md) playgrounds/ └── nuxt/app/pages/components/ # Playground pages

CLI for Scaffolding

Link the CLI first (one-time setup):

npm link

Then use it to create new components:

nuxt-ui make component <name> [options]

Options:

• --primitive

• Primitive component (uses Reka UI Primitive)

• --prose

• Prose/typography component

• --content

• Content component

• --template

• Generate specific template only (playground , docs , test , theme , component )

Available Guidance

File Topics

references/component-structure.md Vue component file patterns, props/slots/emits interfaces, script setup

references/theme-structure.md Tailwind Variants theme files, slots, variants, compoundVariants

references/testing.md Vitest patterns, snapshot testing, accessibility testing

references/documentation.md Component docs structure, MDC syntax, examples

Loading Files

Load reference files based on your task:

• references/component-structure.md - if creating/modifying Vue components

• references/theme-structure.md - if working on component theming

• references/testing.md - if writing or reviewing tests

• references/documentation.md - if writing component docs

DO NOT load all files at once. Load only what's relevant.

Component Creation Workflow

Copy this checklist and track progress when creating a new component:

Component: [name] Progress:

• 1. Scaffold with CLI: nuxt-ui make component <name>
• 2. Implement component in src/runtime/components/
• 3. Create theme in src/theme/
• 4. Export types from src/runtime/types/index.ts
• 5. Write tests in test/components/
• 6. Create docs in docs/content/docs/2.components/
• 7. Add playground page
• 8. Run pnpm run lint
• 9. Run pnpm run typecheck
• 10. Run pnpm run test

PR Review Checklist

When reviewing component PRs, verify:

PR Review:

• Component follows existing patterns (see references/)
• Theme uses semantic colors, not Tailwind palette
• Tests cover props, slots, and accessibility
• Documentation includes Usage, Examples, and API sections
• Conventional commit message format
• All checks pass (lint, typecheck, test)

Code Conventions

Convention Description

Type imports Always separate: import type { X } on its own line

Props defaults Use withDefaults() for runtime, JSDoc @defaultValue for docs

Template slots Add data-slot="name" attributes on all elements

Computed ui Always use computed(() => tv(...)) for reactive theming

Theme support Use useComponentUI(name, props) to merge Theme context with component ui prop

Semantic colors Use text-default , bg-elevated , etc. - never Tailwind palette

Reka UI props Use reactivePick

• useForwardPropsEmits to forward props

Form components Use useFormField and useFieldGroup composables

Commands

pnpm run dev:prepare # Generate type stubs (run after install) pnpm run dev # Nuxt playground pnpm run dev:vue # Vue playground pnpm run docs # Documentation site pnpm run lint # Check linting pnpm run lint:fix # Fix linting pnpm run typecheck # Type checking pnpm run test # Run tests

Resources

• Contribution Guide

• Nuxt UI GitHub