stack/packages/mosaic/framework/skills/shadcn-ui/references/learn.md

shadcn/ui Learning Guide

This guide helps you learn shadcn/ui from basics to advanced patterns.

Learning Path

1. Understanding the Philosophy

shadcn/ui is different from traditional component libraries:

• Copy-paste components: Components are copied into your project, not installed as packages
• Full customization: You own the code and can modify it freely
• Built on Radix UI: Provides accessibility primitives
• Styled with Tailwind: Uses utility classes for consistent styling

2. Core Concepts to Master

Class Variance Authority (CVA)

Most components use CVA for variant management:

const buttonVariants = cva('base-classes', {
  variants: {
    variant: {
      default: 'variant-classes',
      destructive: 'destructive-classes',
    },
    size: {
      default: 'size-classes',
      sm: 'small-classes',
    },
  },
  defaultVariants: {
    variant: 'default',
    size: 'default',
  },
});

cn Utility Function

The cn function combines classes and resolves conflicts:

import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

3. Installation Checklist

• Initialize a new project (Next.js, Vite, or Remix)
• Install Tailwind CSS
• Run npx shadcn@latest init
• Configure CSS variables
• Install first component: npx shadcn@latest add button

4. Essential Components to Learn First

1. Button - Learn variants and sizes
2. Input - Form inputs with labels
3. Card - Container components
4. Form - Form handling with React Hook Form
5. Dialog - Modal windows
6. Select - Dropdown selections
7. Toast - Notifications

5. Common Patterns

Form Pattern

Every form follows this structure:

1. Define Zod schema
2. Create form with useForm
3. Wrap with Form component
4. Add FormField for each input
5. Handle submission

Component Customization Pattern

To customize a component:

1. Copy component to your project
2. Modify the variants
3. Add new props if needed
4. Update types

6. Best Practices

• Always use TypeScript
• Follow the existing component structure
• Use semantic HTML when possible
• Test with screen readers for accessibility
• Keep components small and focused

7. Advanced Topics

• Creating custom components from scratch
• Building complex forms with validation
• Implementing dark mode
• Optimizing for performance
• Testing components

Practice Exercises

Exercise 1: Basic Setup

1. Create a new Next.js project
2. Set up shadcn/ui
3. Install and customize a Button component
4. Add a new variant "gradient"

Exercise 2: Form Building

1. Create a contact form with:
   • Name input (required)
   • Email input (email validation)
   • Message textarea (min length)
   • Submit button with loading state

Exercise 3: Component Combination

1. Build a settings page using:
   • Card for layout
   • Sheet for mobile menu
   • Select for dropdowns
   • Switch for toggles
   • Toast for notifications

Exercise 4: Custom Component

1. Create a custom Badge component
2. Support variants: default, secondary, destructive, outline
3. Support sizes: sm, default, lg
4. Add icon support

Resources

• Official Documentation
• GitHub Repository
• Examples Gallery
• Radix UI Primitives
• Tailwind CSS Documentation