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 pagesCLI for Scaffolding
Link the CLI first (one-time setup):
npm linkThen 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 testPR 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