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

contributing