ui: Instructions file for Codex

AGENTS.md

This file provides guidance for AI coding agents working on the Nuxt UI repository.

Project Overview

Nuxt UI is a component library built on Reka UI, Tailwind CSS, and Tailwind Variants. It provides accessible, themeable components for both Nuxt and Vue applications.

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/
├── bundle/             # Bundle size fixtures (`pnpm run size`)
├── 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

Commands

pnpm run dev:prepare  # Generate type stubs (run after install)
pnpm run dev          # Nuxt playground
pnpm run dev:vue      # Vue playground
pnpm run repl         # REPL 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
pnpm run size         # Build test/bundle apps and print their JS/CSS sizes

CLI for Scaffolding

Use the CLI to create new components:

pnpm cli 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)

Key Conventions

• Conventional commits: All commit messages must follow conventional commits (e.g. fix(Button): resolve hover state, feat(Modal): add fullscreen prop).
• Semantic colors: Use text-default, bg-elevated, etc. — never raw Tailwind palette colors like text-gray-500.
• Soon badge on docs headings: PRs that introduce a new feature or fix often add :badge{label="Soon" class="align-text-top"} to the relevant docs heading. This is intentional: the docs site redeploys on merge, but the feature only ships on the next npm release — the badge bridges that gap. Do NOT flag this as inconsistent in reviews. See documentation.md for details.
• Two build adapters: Build-side changes (templates, auto-imports, icons, component detection, build plugins) must be checked against both adapters: src/module.ts for Nuxt, src/unplugin.ts and src/plugins/* for Vue. Shared logic belongs in src/utils/. In code that runs from the published build, only the two entry files may resolve paths from import.meta.url, since bundled files can land in any output chunk. Everything else anchors on runtimeDir.