Home
cd ../playbooks
Developer ToolsBeginner

Nuxt UI Component Guidance

Build interfaces correctly with @nuxt/ui v4 — five core rules (UApp wrapper, semantic colors, reading generated theme files for real slot names, override priority, icon naming), a task-to-focus-area routing table, the Nuxt UI MCP server for live component API lookups, and full installation for both Nuxt and standalone Vue.

5 minutes
By NuxtSource
#nuxt#vue#tailwind-css#ui-components#nuxt-ui#frontend

Styling a Nuxt UI component with text-gray-500 instead of the semantic text-muted works fine in light mode and silently breaks dark mode — Nuxt UI's whole theming system is built on semantic color tokens, and reaching for familiar raw Tailwind palette classes out of habit is the single most common way to fight the library instead of using it.

Who it's for: Vue and Nuxt developers building UIs with @nuxt/ui v4, teams choosing between Modal and Slideover or Select and SelectMenu and unsure which fits, developers customizing Nuxt UI's theme or brand colors, anyone hitting an unexpected component style override and needing to know the actual priority order

Example

"Build a settings page with Nuxt UI" → Focus areas identified from the routing table (conventions plus form validation and field layout patterns), a UApp-wrapped app confirmed, semantic color tokens used throughout instead of raw Tailwind grays, and the Nuxt UI MCP server queried for the exact props/slots of whichever form components are needed

CLAUDE.md Template

New here? 3-minute setup guide → | Already set up? Copy the template below.

Or install from your terminal:
npx ccplaybooks add nuxt-ui
# Nuxt UI

Build interfaces with `@nuxt/ui` v4 — a Vue component library with 125+ accessible components, built on Reka UI + Tailwind CSS + Tailwind Variants. Works with Nuxt, Vue (Vite), Laravel (Vite + Inertia), and AdonisJS (Vite + Inertia).

## Core Rules (Always Apply)

1. **Always wrap the app in `UApp`** — required for toasts, tooltips, and programmatic overlays. Accepts a `locale` prop for i18n.
2. **Always use semantic colors** — `text-default`, `bg-elevated`, `border-muted`, etc. Never use raw Tailwind palette colors like `text-gray-500`.
3. **Read generated theme files for slot names.** Nuxt: `.nuxt/ui/<component>.ts`; Vue: `node_modules/.nuxt-ui/ui/<component>.ts`. These show every slot, variant, and default class for any component — the fastest way to know a component's real API.
4. **Override priority** (highest wins): `ui` prop / `class` prop → global config → theme defaults.
5. **Icons use `i-{collection}-{name}` format** — `lucide` is the default collection. Browse at icones.js.org.

Get new playbooks like this one

One email a week with new Claude Code workflows. Free, like everything here.

No spam. Unsubscribe anytime.

README.md

What This Does

A working-guide for @nuxt/ui v4 — the 125+ component Vue library built on Reka UI, Tailwind CSS, and Tailwind Variants — that separates two different needs: when to use which component and how to build well (this playbook) versus what a specific component's props and slots are (the official Nuxt UI MCP server, added with one claude mcp add command). Five core rules anchor everything: always wrap the app in UApp for toasts/tooltips/overlays to work at all, always use semantic color tokens (text-default, bg-elevated) instead of raw Tailwind palette classes so dark mode and theming actually work, read the generated theme file (.nuxt/ui/<component>.ts or node_modules/.nuxt-ui/ui/<component>.ts) for a component's real slot names instead of guessing, respect the override priority (ui/class prop → global config → theme defaults), and use the i-{collection}-{name} icon format.

A task-to-focus-area routing table tells you what to pay attention to for common jobs — a dashboard needs component-selection decisions like Modal vs. Slideover or Select vs. SelectMenu plus dashboard layout patterns; a login form needs form validation and field-layout conventions; theming work needs only the semantic-color rules. Complete installation instructions cover both a Nuxt project (module registration, CSS imports, the UApp root wrapper) and a standalone Vue + Vite setup (the Vite plugin, the Vue plugin registration, router wiring, and the Inertia-specific router option).

Quick Start

Step 1: Create a Project Folder

mkdir nuxt-ui-project && cd nuxt-ui-project

Step 2: Download the Template

Click Download above, then:

mv ~/Downloads/CLAUDE.md ./

Step 3: Build With Nuxt UI

claude

Ask Claude to build a page, form, dashboard, or component with Nuxt UI. It will apply the semantic-color and UApp-wrapper rules by default, pick the right component for the interaction (checking the routing table for what matters most to the current task), and add the Nuxt UI MCP server when it needs exact prop/slot details for a specific component.

Tips & Best Practices

  • Add the Nuxt UI MCP server early in a project (claude mcp add --transport http nuxt-ui https://ui.nuxt.com/mcp) — component APIs change across releases, and the MCP's live documentation beats relying on training-data knowledge of prop names.
  • When a component doesn't look right, check the generated theme file for its real slot names before reaching for a class override — most "the CSS isn't applying" issues come from styling the wrong slot.
  • For component-choice decisions (Modal vs. Slideover, Select vs. SelectMenu, Toast vs. Alert), consult the component-selection guidance for the current task rather than picking by familiarity — Nuxt UI's components have overlapping but distinct intended use cases.

Limitations

  • This playbook is guidance on when and how, not a full prop/slot/event reference — always pair it with the Nuxt UI MCP server (or the library's own docs) for exact component APIs.
  • Works with Nuxt, Vue+Vite, Laravel+Inertia, and AdonisJS+Inertia specifically; other Vue meta-frameworks aren't covered by the installation steps here.
  • Assumes Tailwind CSS is the styling foundation — a project on a different CSS approach would need to adopt Tailwind first.

$Related Playbooks

Developer Tools

Reshape PR Commits

Turn a branch's messy WIP/fixup commit history into a clean, logically-grouped set of commits before review — proposed regrouping with explicit approval, git reset --soft plus staged re-commits instead of interactive rebase, and hard guardrails (feature branches only, force-with-lease only, never touch another author's commits).

5 minutes
Intermediate
Developer Tools

Simplicity First Code Gate

A hard correctness gate against over-complex or oversized code — one ordering principle (human readability first, agent traceability second), five enforceable rules, and a pre-finish checklist that treats unnecessary complexity as a bug, not a style opinion.

2 minutes
Beginner
Developer Tools

Slidev Presentation Builder

Build developer-focused presentations with Slidev — Markdown-driven slides with live code, syntax highlighting, Monaco editor embeds, Mermaid/PlantUML diagrams, LaTeX math, click-based animations, and presenter notes, plus a quick-reference table for the exact syntax each feature needs.

5 minutes
Beginner
Developer Tools

Technical Writing Style Guide

Write docstrings, READMEs, commit messages, and PR descriptions that read like human technical documentation instead of LLM output — six concrete 'tells' with before/after rewrites, a smoothness diagnostic for prose that sounds authoritative while stating one fact three times, and industry-metaphor substitution tables ('surfaces' to 'raises/returns/logs', 'wired through' to 'passed as a parameter').

5 minutes
Intermediate
Developer Tools

Three.js Scroll World Builder

Build a scroll-controlled real-time Three.js experience as one persistent 3D world instead of stacked sections — a scene-ledger data model for authoring chapters, native-scroll-to-deterministic-state mapping with separate exact and smoothed progress, cinematic camera composition, a measurable per-device performance budget, and mandatory reduced-motion and WebGL-failure fallbacks.

20 minutes
Advanced
Developer Tools

Visual Explainer HTML Pages

Have Claude Code explain architectures, diffs and plans as self-contained HTML pages with labeled Mermaid diagrams and a deliberate design pass, instead of walls of chat text, terminal ASCII or generic AI-looking pages.

5 minutes
Intermediate
Developer Tools

Web Animation Design Principles

Design web animations that feel natural and purposeful — a decision-first easing blueprint (ease-out for entrances, ease-in-out for movement, ease for hover), duration and frequency rules, spring configuration, the GPU-only performance rule, and mandatory prefers-reduced-motion accessibility patterns with working CSS and Framer Motion code.

5 minutes
Intermediate
Developer Tools

Web Technique to Skill Extractor

Turn a one-off web visual or interaction technique into a reusable, well-scoped skill — the one-sentence mechanism test that separates a real technique from mere styling, a mechanism-vs-staging sort for what belongs in the skill versus the demo, rules anchored to named failures instead of adjectives, and a demo craft bar that treats the acceptance reference as a target, not inspiration.

10 minutes
Advanced
Developer Tools

Planning with Files

Persistent, file-based planning for multi-step AI-agent work — task_plan.md, findings.md, and progress.md on disk, a 2-action rule for capturing multimodal findings before they're lost, a 3-strike error protocol, and a 5-question reboot test to verify state survives a compaction.

5 minutes
Intermediate
Developer Tools

Secret Scan and Rotation

Find committed credentials in a repository's working tree and full history, triage real secrets from test fixtures, and drive rotation-first remediation — with an absolute rule against ever printing a secret's actual value, even during the scan itself.

5 minutes
Intermediate
Developer Tools

Self-Improvement Loop Design

Design systems where the harness itself is the optimization target — an optimization ladder from prompt to context to workflow to harness code, a two-split empirical acceptance gate, an outside-the-loop invariant for the evaluator, and a catalog of documented reward-hacking and collapse failure modes.

10 minutes
Advanced
Developer Tools

Skill Security Inspector

Review an AI agent skill before installing it using two independent lines — static scanner evidence plus source-aware semantic judgment — checking purpose fit, permission fit, sensitive access, external transmission, execution risk, and persistence, down to a clear APPROVE, CAUTION, or REJECT verdict.

10 minutes
Intermediate

Browse all Developer Tools playbooks →