home / skills / fusengine / agents / nextjs-shadcn
This skill helps you implement accessible shadcn/ui components in Next.js App Router, with TanStack Form patterns and SOLID architecture.
npx playbooks add skill fusengine/agents --skill nextjs-shadcnReview the files below or copy the command above to add this skill to your agents.
---
name: nextjs-shadcn
description: shadcn/ui for Next.js App Router with TanStack Form. Use when building UI components, forms, dialogs, tables, toasts, or accessible components.
versions:
shadcn-ui: 3.8.0
nextjs: 16
tailwindcss: 4
user-invocable: true
references: references/installation.md, references/configuration.md, references/theming.md, references/button.md, references/input.md, references/label.md, references/textarea.md, references/card.md, references/select.md, references/checkbox.md, references/switch.md, references/radio-group.md, references/slider.md, references/toggle.md, references/toggle-group.md, references/input-otp.md, references/dialog.md, references/alert-dialog.md, references/sheet.md, references/drawer.md, references/popover.md, references/tooltip.md, references/hover-card.md, references/context-menu.md, references/collapsible.md, references/toast.md, references/alert.md, references/skeleton.md, references/progress.md, references/spinner.md, references/table.md, references/tabs.md, references/accordion.md, references/badge.md, references/avatar.md, references/separator.md, references/scroll-area.md, references/aspect-ratio.md, references/resizable.md, references/carousel.md, references/chart.md, references/dropdown.md, references/command.md, references/breadcrumb.md, references/navigation-menu.md, references/menubar.md, references/sidebar.md, references/pagination.md, references/calendar.md, references/field-patterns.md, references/form-examples.md
related-skills: nextjs-16, nextjs-tanstack-form, tailwindcss, solid-nextjs
---
# shadcn/ui for Next.js
Beautiful, accessible components built on Radix UI with Tailwind CSS styling.
## Agent Workflow (MANDATORY)
Before ANY implementation, use `TeamCreate` to spawn 3 agents:
1. **fuse-ai-pilot:explore-codebase** - Analyze existing components and patterns
2. **fuse-ai-pilot:research-expert** - Verify latest shadcn/ui docs via Context7/Exa
3. **mcp__shadcn__*** - Search registry for component availability
After implementation, run **fuse-ai-pilot:sniper** for validation.
---
## Overview
### When to Use
- Building UI components for Next.js App Router applications
- Need accessible, customizable form components (inputs, selects, checkboxes)
- Implementing dialogs, sheets, drawers, or overlay patterns
- Creating data tables with sorting, filtering, and pagination
- Building navigation menus, sidebars, or command palettes
- Need toast notifications or alert feedback components
### Why shadcn/ui
| Feature | Benefit |
|---------|---------|
| Copy/paste model | Components copied to your project, full ownership |
| Radix UI foundation | Accessibility built-in, unstyled primitives |
| Tailwind CSS styling | Utility-first, easy customization |
| TanStack Form ready | Modern form library with Field pattern |
| Server Components | RSC-compatible, optimal bundle size |
| Lucide icons | Consistent, customizable icon set |
---
## Critical Rules
1. **NEVER create components manually** - Always install with `bunx --bun shadcn@latest add`
2. **TanStack Form only** - NOT React Hook Form for all form implementations
3. **Radix UI primitives** - Components built on Radix (NOT Base UI)
4. **Lucide icons** - Default icon library, NOT Remix icons or others
5. **Field pattern** - Use Field, FieldLabel, FieldError for form fields
6. **SOLID paths** - Components at `@/modules/cores/shadcn/components/ui/`
---
## Architecture
### Component Foundation
- **Radix UI** - Headless, accessible primitives (Dialog, Select, Popover, Tabs)
- **Tailwind CSS v4** - Styling via utility classes, CSS-first config
- **class-variance-authority** - Variant management for component styles
- **clsx + tailwind-merge** - Conditional class composition via `cn()` utility
### Project Structure
Components installed to `@/modules/cores/shadcn/components/ui/` following SOLID architecture. Utils at `@/modules/cores/lib/utils.ts` with `cn()` helper function.
---
## MCP Server Integration
Create `.mcp.json` at project root for Claude Code integration with shadcn registry.
### Available MCP Tools
- `mcp__shadcn__search_items_in_registries` - Search available components
- `mcp__shadcn__view_items_in_registries` - View component source code
- `mcp__shadcn__get_item_examples_from_registries` - Get usage examples
- `mcp__shadcn__get_add_command_for_items` - Get installation commands
See [installation.md](references/installation.md) for complete MCP setup.
---
## Component Categories
| Category | Components | Primary Reference |
|----------|------------|-------------------|
| Setup | Init, configuration, theming, icons | [installation.md](references/installation.md) |
| Forms | Button, Input, Field, Select, Checkbox, Switch, Slider | [field-patterns.md](references/field-patterns.md) |
| Overlay | Dialog, Sheet, Drawer, Popover, Tooltip, HoverCard | [dialog.md](references/dialog.md) |
| Feedback | Alert, Toast (Sonner), Progress, Skeleton, Spinner | [toast.md](references/toast.md) |
| Data Display | Table, Badge, Avatar, Calendar, Chart, Carousel | [table.md](references/table.md) |
| Navigation | Breadcrumb, DropdownMenu, Command, Sidebar, Tabs | [sidebar.md](references/sidebar.md) |
| Layout | Card, Accordion, Separator, ScrollArea, Resizable | [card.md](references/card.md) |
---
## Best Practices
1. **Field components** - Use new Field pattern for consistent form field structure
2. **Server Components default** - Add `'use client'` only when interactivity needed
3. **Sonner for toasts** - Modern toast notifications over legacy toast
4. **MCP tools first** - Use `mcp__shadcn__*` to explore before implementing
5. **Theming via CSS variables** - Customize colors in `globals.css` `:root`
6. **Accessibility** - Rely on Radix UI keyboard navigation and ARIA
---
## Reference Guide
| Need | Reference |
|------|-----------|
| Initial setup | [installation.md](references/installation.md), [configuration.md](references/configuration.md) |
| Form patterns | [field-patterns.md](references/field-patterns.md), [form-examples.md](references/form-examples.md) |
| Theme customization | [theming.md](references/theming.md) |
| Data tables | [table.md](references/table.md) |
| Modal dialogs | [dialog.md](references/dialog.md), [alert-dialog.md](references/alert-dialog.md) |
| Navigation | [sidebar.md](references/sidebar.md), [navigation-menu.md](references/navigation-menu.md) |
This skill provides shadcn/ui integration tailored for Next.js App Router projects, delivering accessible Radix-based components styled with Tailwind and ready for TanStack Form. It codifies an agent-driven workflow for discovery, verification, and post-implementation validation. Use it to add copy/paste-ready UI components while preserving ownership and accessibility.
Before implementing components, spawn three agents via TeamCreate: an explorer for the codebase, a research expert to validate shadcn/ui docs, and an MCP search agent to check registry availability. The skill installs components into a SOLID path, ensures Radix primitives and Tailwind styling are used, and enforces TanStack Form Field patterns. After implementation, run the fuse-ai-pilot:sniper agent to validate integration and accessibility.
Do I ever create shadcn components by hand?
No. Always use the official add command to install components into the project; manual creation is prohibited by this workflow.
Which form library must I use?
TanStack Form is required. React Hook Form is not permitted for implementations covered by this skill.
Where should components live in the repo?
Place all shadcn components under @/modules/cores/shadcn/components/ui/ following SOLID paths.
How do I validate my implementation?
Run the fuse-ai-pilot:sniper agent after implementation to perform automated validation and accessibility checks.