home / skills / nuxt / ui / contributing

contributing skill

safe

This skill guides you through Nuxt UI component contribution, including structure, theming, testing, and documentation to streamline development.

npx playbooks add skill nuxt/ui --skill contributing

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

4.7 KB

---
name: contributing
description: Guide for contributing to Nuxt UI. Provides component structure patterns, Tailwind Variants theming, Vitest testing conventions, and MDC documentation guidelines. Use when creating new components, reviewing component PRs, modifying existing components, writing tests, or creating documentation in this codebase.
---

# 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):

```bash
npm link
```

Then use it to create new components:

```bash
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](references/component-structure.md)** | Vue component file patterns, props/slots/emits interfaces, script setup |
| **[references/theme-structure.md](references/theme-structure.md)** | Tailwind Variants theme files, slots, variants, compoundVariants |
| **[references/testing.md](references/testing.md)** | Vitest patterns, snapshot testing, accessibility testing |
| **[references/documentation.md](references/documentation.md)** | Component docs structure, MDC syntax, examples |

## Loading Files

**Load reference files based on your task:**

- [ ] [references/component-structure.md](references/component-structure.md) - if creating/modifying Vue components
- [ ] [references/theme-structure.md](references/theme-structure.md) - if working on component theming
- [ ] [references/testing.md](references/testing.md) - if writing or reviewing tests
- [ ] [references/documentation.md](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

```bash
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](https://ui.nuxt.com/getting-started/contribution)
- [Nuxt UI GitHub](https://github.com/nuxt/ui)

Overview

This skill is a concise contributor guide for Nuxt UI that helps maintain consistent component design, theming, testing, and documentation. It bundles the recommended project structure, CLI scaffolding, component creation checklist, PR review criteria, and common commands. Use it to onboard contributors and speed up safe, standards-compliant contributions. It focuses on Vue components, Tailwind Variants theming, Vitest conventions, and MDC-style docs.

How this skill works

The guide inspects your task and points you to the single most relevant reference (component structure, theme structure, testing, or documentation) instead of loading everything at once. It provides a step-by-step component creation workflow and a PR review checklist to validate patterns, tests, semantic theming, and docs. It also lists code conventions and useful npm/pnpm commands to run locally before opening a PR.

When to use it

When creating a new Vue component or scaffolding with the provided CLI.
When modifying an existing component or updating its theme file.
When writing or reviewing Vitest unit and snapshot tests for components.
When drafting or reviewing component documentation using MDC guidelines.
When performing a PR review to ensure code, theme, tests, and docs comply.

Best practices

Scaffold components with the CLI (nuxt-ui make component) and follow the provided checklist from implementation through docs and tests.
Keep theme files in src/theme as kebab-case and use semantic color tokens (text-default, bg-elevated) not raw Tailwind palette classes.
Write reactive theming with computed(() => tv(...)) and merge UI context via useComponentUI(name, props).
Follow testing patterns in references/testing.md: cover props, slots, accessibility, and include snapshots where useful.

Example use cases

Scaffold a new button component, implement it in src/runtime/components, add a theme in src/theme, export types, write tests, and add docs and playground.
Review a component PR to verify semantic theming, test coverage for accessibility, and proper documentation sections (Usage, Examples, API).
Update a component theme to add a new variant using Tailwind Variants compoundVariants and ensure computed tv usage.
Write Vitest tests for a form component that uses useFormField and ensure forwarded props and emits behave correctly.
Create a documentation page using MDC syntax with clear examples and API reference.

FAQ

Which reference should I load for a specific task?

Load only the relevant file: component-structure for components, theme-structure for theming, testing for tests, and documentation for docs. Do not load all files at once.

What commands should I run before opening a PR?

Run lint, typecheck, and tests: pnpm run lint, pnpm run typecheck, and pnpm run test. Also run pnpm run dev:prepare after install to generate type stubs.