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:

• fuse-ai-pilot:explore-codebase - Analyze existing components and patterns

• fuse-ai-pilot:research-expert - Verify latest shadcn/ui docs via Context7/Exa

• 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

• NEVER create components manually - Always install with bunx --bun shadcn@latest add

• TanStack Form only - NOT React Hook Form for all form implementations

• Radix UI primitives - Components built on Radix (NOT Base UI)

• Lucide icons - Default icon library, NOT Remix icons or others

• Field pattern - Use Field, FieldLabel, FieldError for form fields

• 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 for complete MCP setup.

Component Categories

Category Components Primary Reference

Setup Init, configuration, theming, icons installation.md

Forms Button, Input, Field, Select, Checkbox, Switch, Slider field-patterns.md

Overlay Dialog, Sheet, Drawer, Popover, Tooltip, HoverCard dialog.md

Feedback Alert, Toast (Sonner), Progress, Skeleton, Spinner toast.md

Data Display Table, Badge, Avatar, Calendar, Chart, Carousel table.md

Navigation Breadcrumb, DropdownMenu, Command, Sidebar, Tabs sidebar.md

Layout Card, Accordion, Separator, ScrollArea, Resizable card.md

Best Practices

• Field components - Use new Field pattern for consistent form field structure

• Server Components default - Add 'use client' only when interactivity needed

• Sonner for toasts - Modern toast notifications over legacy toast

• MCP tools first - Use mcp__shadcn__* to explore before implementing

• Theming via CSS variables - Customize colors in globals.css :root

• Accessibility - Rely on Radix UI keyboard navigation and ARIA

Reference Guide

Need Reference

Initial setup installation.md, configuration.md

Form patterns field-patterns.md, form-examples.md

Theme customization theming.md

Data tables table.md

Modal dialogs dialog.md, alert-dialog.md

Navigation sidebar.md, navigation-menu.md