初始化项目版本
This commit is contained in:
Axhub Make
481
.agents/skills/shadcn-ui/resources/component-catalog.md
Normal file
481
.agents/skills/shadcn-ui/resources/component-catalog.md
Normal file
@@ -0,0 +1,481 @@
|
||||
# shadcn/ui Component Catalog
|
||||
|
||||
Complete reference of all available shadcn/ui components, organized by category.
|
||||
|
||||
> **Note**: This catalog lists dependencies based on **Radix UI**. If you are using **Base UI**, the `add` command will handle the correct dependencies automatically.
|
||||
|
||||
## Layout Components
|
||||
|
||||
### Accordion
|
||||
Collapsible content sections.
|
||||
```bash
|
||||
npx shadcn@latest add accordion
|
||||
```
|
||||
**Use cases**: FAQs, settings panels, navigation menus
|
||||
**Key props**: `type` (single/multiple), `collapsible`
|
||||
**Dependencies**: @radix-ui/react-accordion
|
||||
|
||||
### Card
|
||||
Container for grouping related content.
|
||||
```bash
|
||||
npx shadcn@latest add card
|
||||
```
|
||||
**Sub-components**: CardHeader, CardTitle, CardDescription, CardContent, CardFooter
|
||||
**Use cases**: Product cards, profile cards, dashboard widgets
|
||||
**Dependencies**: None
|
||||
|
||||
### Separator
|
||||
Visual divider between content sections.
|
||||
```bash
|
||||
npx shadcn@latest add separator
|
||||
```
|
||||
**Props**: `orientation` (horizontal/vertical), `decorative`
|
||||
**Dependencies**: @radix-ui/react-separator
|
||||
|
||||
### Tabs
|
||||
Organize content into multiple panels, one visible at a time.
|
||||
```bash
|
||||
npx shadcn@latest add tabs
|
||||
```
|
||||
**Sub-components**: TabsList, TabsTrigger, TabsContent
|
||||
**Use cases**: Settings pages, dashboards, multi-step forms
|
||||
**Dependencies**: @radix-ui/react-tabs
|
||||
|
||||
### Collapsible
|
||||
Show/hide content with smooth animation.
|
||||
```bash
|
||||
npx shadcn@latest add collapsible
|
||||
```
|
||||
**Props**: `open`, `onOpenChange`, `disabled`
|
||||
**Dependencies**: @radix-ui/react-collapsible
|
||||
|
||||
## Form Components
|
||||
|
||||
### Button
|
||||
Clickable button with variants and sizes.
|
||||
```bash
|
||||
npx shadcn@latest add button
|
||||
```
|
||||
**Variants**: default, destructive, outline, secondary, ghost, link
|
||||
**Sizes**: default, sm, lg, icon
|
||||
**Dependencies**: @radix-ui/react-slot
|
||||
|
||||
### Input
|
||||
Text input field.
|
||||
```bash
|
||||
npx shadcn@latest add input
|
||||
```
|
||||
**Types**: text, email, password, number, tel, url
|
||||
**Use cases**: Forms, search bars, filters
|
||||
**Dependencies**: None
|
||||
|
||||
### Label
|
||||
Accessible label for form fields.
|
||||
```bash
|
||||
npx shadcn@latest add label
|
||||
```
|
||||
**Use with**: All form inputs for accessibility
|
||||
**Dependencies**: @radix-ui/react-label
|
||||
|
||||
### Textarea
|
||||
Multi-line text input.
|
||||
```bash
|
||||
npx shadcn@latest add textarea
|
||||
```
|
||||
**Props**: `rows`, `cols`, `resize` (via className)
|
||||
**Dependencies**: None
|
||||
|
||||
### Checkbox
|
||||
Binary toggle control.
|
||||
```bash
|
||||
npx shadcn@latest add checkbox
|
||||
```
|
||||
**Props**: `checked`, `onCheckedChange`, `disabled`
|
||||
**Dependencies**: @radix-ui/react-checkbox
|
||||
|
||||
### Radio Group
|
||||
Select one option from a set.
|
||||
```bash
|
||||
npx shadcn@latest add radio-group
|
||||
```
|
||||
**Sub-components**: RadioGroupItem
|
||||
**Dependencies**: @radix-ui/react-radio-group
|
||||
|
||||
### Select
|
||||
Dropdown selection control.
|
||||
```bash
|
||||
npx shadcn@latest add select
|
||||
```
|
||||
**Sub-components**: SelectTrigger, SelectContent, SelectItem, SelectValue
|
||||
**Use cases**: Country selectors, category filters
|
||||
**Dependencies**: @radix-ui/react-select
|
||||
|
||||
### Switch
|
||||
Binary toggle with visual feedback.
|
||||
```bash
|
||||
npx shadcn@latest add switch
|
||||
```
|
||||
**Props**: `checked`, `onCheckedChange`, `disabled`
|
||||
**Use cases**: Settings toggles, feature flags
|
||||
**Dependencies**: @radix-ui/react-switch
|
||||
|
||||
### Slider
|
||||
Select value from a range.
|
||||
```bash
|
||||
npx shadcn@latest add slider
|
||||
```
|
||||
**Props**: `min`, `max`, `step`, `value`, `onValueChange`
|
||||
**Use cases**: Volume controls, filters, settings
|
||||
**Dependencies**: @radix-ui/react-slider
|
||||
|
||||
### Form
|
||||
Comprehensive form component with validation.
|
||||
```bash
|
||||
npx shadcn@latest add form
|
||||
```
|
||||
**Sub-components**: FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage
|
||||
**Best used with**: react-hook-form, zod
|
||||
**Dependencies**: @radix-ui/react-label, @radix-ui/react-slot
|
||||
|
||||
## Data Display
|
||||
|
||||
### Table
|
||||
Display structured data in rows and columns.
|
||||
```bash
|
||||
npx shadcn@latest add table
|
||||
```
|
||||
**Sub-components**: TableHeader, TableBody, TableHead, TableRow, TableCell, TableFooter, TableCaption
|
||||
**Best used with**: @tanstack/react-table
|
||||
**Dependencies**: None
|
||||
|
||||
### Badge
|
||||
Highlight status or category.
|
||||
```bash
|
||||
npx shadcn@latest add badge
|
||||
```
|
||||
**Variants**: default, secondary, destructive, outline
|
||||
**Use cases**: Status indicators, tags, notifications
|
||||
**Dependencies**: None
|
||||
|
||||
### Avatar
|
||||
Display user profile images with fallback.
|
||||
```bash
|
||||
npx shadcn@latest add avatar
|
||||
```
|
||||
**Sub-components**: AvatarImage, AvatarFallback
|
||||
**Dependencies**: @radix-ui/react-avatar
|
||||
|
||||
### Progress
|
||||
Visual indicator of task completion.
|
||||
```bash
|
||||
npx shadcn@latest add progress
|
||||
```
|
||||
**Props**: `value` (0-100)
|
||||
**Dependencies**: @radix-ui/react-progress
|
||||
|
||||
### Skeleton
|
||||
Loading placeholder with animation.
|
||||
```bash
|
||||
npx shadcn@latest add skeleton
|
||||
```
|
||||
**Use cases**: Content loading states
|
||||
**Dependencies**: None
|
||||
|
||||
### Calendar
|
||||
Date selection interface.
|
||||
```bash
|
||||
npx shadcn@latest add calendar
|
||||
```
|
||||
**Props**: `mode` (single/multiple/range), `selected`, `onSelect`
|
||||
**Dependencies**: react-day-picker
|
||||
|
||||
## Overlay Components
|
||||
|
||||
### Dialog
|
||||
Modal dialog overlay.
|
||||
```bash
|
||||
npx shadcn@latest add dialog
|
||||
```
|
||||
**Sub-components**: DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription
|
||||
**Use cases**: Confirmations, forms, detailed views
|
||||
**Dependencies**: @radix-ui/react-dialog
|
||||
|
||||
### Sheet
|
||||
Side panel that slides in from edge.
|
||||
```bash
|
||||
npx shadcn@latest add sheet
|
||||
```
|
||||
**Sides**: top, right, bottom, left
|
||||
**Sub-components**: SheetTrigger, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription
|
||||
**Use cases**: Navigation menus, filters, settings
|
||||
**Dependencies**: @radix-ui/react-dialog
|
||||
|
||||
### Popover
|
||||
Floating content container.
|
||||
```bash
|
||||
npx shadcn@latest add popover
|
||||
```
|
||||
**Sub-components**: PopoverTrigger, PopoverContent
|
||||
**Use cases**: Tooltips with actions, mini forms
|
||||
**Dependencies**: @radix-ui/react-popover
|
||||
|
||||
### Tooltip
|
||||
Contextual information on hover.
|
||||
```bash
|
||||
npx shadcn@latest add tooltip
|
||||
```
|
||||
**Sub-components**: TooltipProvider, TooltipTrigger, TooltipContent
|
||||
**Props**: `side`, `sideOffset`, `delayDuration`
|
||||
**Dependencies**: @radix-ui/react-tooltip
|
||||
|
||||
### Dropdown Menu
|
||||
Context menu with actions.
|
||||
```bash
|
||||
npx shadcn@latest add dropdown-menu
|
||||
```
|
||||
**Sub-components**: DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuSeparator, DropdownMenuLabel
|
||||
**Use cases**: Action menus, settings
|
||||
**Dependencies**: @radix-ui/react-dropdown-menu
|
||||
|
||||
### Context Menu
|
||||
Right-click menu.
|
||||
```bash
|
||||
npx shadcn@latest add context-menu
|
||||
```
|
||||
**Sub-components**: Similar to DropdownMenu
|
||||
**Use cases**: Right-click actions, advanced UIs
|
||||
**Dependencies**: @radix-ui/react-context-menu
|
||||
|
||||
### Menubar
|
||||
Horizontal menu bar.
|
||||
```bash
|
||||
npx shadcn@latest add menubar
|
||||
```
|
||||
**Sub-components**: MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem
|
||||
**Use cases**: Application menus (File, Edit, View)
|
||||
**Dependencies**: @radix-ui/react-menubar
|
||||
|
||||
### Alert Dialog
|
||||
Modal dialog for important confirmations.
|
||||
```bash
|
||||
npx shadcn@latest add alert-dialog
|
||||
```
|
||||
**Sub-components**: AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel
|
||||
**Use cases**: Delete confirmations, destructive actions
|
||||
**Dependencies**: @radix-ui/react-alert-dialog
|
||||
|
||||
### Hover Card
|
||||
Content card revealed on hover.
|
||||
```bash
|
||||
npx shadcn@latest add hover-card
|
||||
```
|
||||
**Sub-components**: HoverCardTrigger, HoverCardContent
|
||||
**Use cases**: User previews, detailed information
|
||||
**Dependencies**: @radix-ui/react-hover-card
|
||||
|
||||
## Navigation
|
||||
|
||||
### Navigation Menu
|
||||
Accessible navigation with dropdowns.
|
||||
```bash
|
||||
npx shadcn@latest add navigation-menu
|
||||
```
|
||||
**Sub-components**: NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink
|
||||
**Use cases**: Main site navigation
|
||||
**Dependencies**: @radix-ui/react-navigation-menu
|
||||
|
||||
### Breadcrumb
|
||||
Show current page location in hierarchy.
|
||||
```bash
|
||||
npx shadcn@latest add breadcrumb
|
||||
```
|
||||
**Sub-components**: BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator
|
||||
**Use cases**: Multi-level navigation
|
||||
**Dependencies**: None
|
||||
|
||||
### Pagination
|
||||
Navigate through pages of content.
|
||||
```bash
|
||||
npx shadcn@latest add pagination
|
||||
```
|
||||
**Sub-components**: PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis
|
||||
**Dependencies**: None
|
||||
|
||||
## Feedback Components
|
||||
|
||||
### Alert
|
||||
Display important messages.
|
||||
```bash
|
||||
npx shadcn@latest add alert
|
||||
```
|
||||
**Variants**: default, destructive
|
||||
**Sub-components**: AlertTitle, AlertDescription
|
||||
**Use cases**: Error messages, warnings, info
|
||||
**Dependencies**: None
|
||||
|
||||
### Toast
|
||||
Temporary notification message.
|
||||
```bash
|
||||
npx shadcn@latest add toast
|
||||
```
|
||||
**Props**: `title`, `description`, `action`, `variant`
|
||||
**Usage**: Via `useToast()` hook
|
||||
**Dependencies**: @radix-ui/react-toast
|
||||
|
||||
### Sonner
|
||||
Alternative toast implementation.
|
||||
```bash
|
||||
npx shadcn@latest add sonner
|
||||
```
|
||||
**Better for**: Rich notifications, multiple toasts
|
||||
**Dependencies**: sonner
|
||||
|
||||
## Command & Search
|
||||
|
||||
### Command
|
||||
Command palette with search and keyboard navigation.
|
||||
```bash
|
||||
npx shadcn@latest add command
|
||||
```
|
||||
**Sub-components**: CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator
|
||||
**Use cases**: Command palettes, search interfaces
|
||||
**Dependencies**: cmdk
|
||||
|
||||
### Combobox
|
||||
Searchable select dropdown.
|
||||
```bash
|
||||
npx shadcn@latest add combobox
|
||||
```
|
||||
**Use cases**: Autocomplete, country selectors
|
||||
**Dependencies**: cmdk (via command)
|
||||
|
||||
## Utility Components
|
||||
|
||||
### Aspect Ratio
|
||||
Maintain consistent width-height ratio.
|
||||
```bash
|
||||
npx shadcn@latest add aspect-ratio
|
||||
```
|
||||
**Props**: `ratio` (e.g., 16/9, 4/3)
|
||||
**Dependencies**: @radix-ui/react-aspect-ratio
|
||||
|
||||
### Scroll Area
|
||||
Custom scrollbar styling.
|
||||
```bash
|
||||
npx shadcn@latest add scroll-area
|
||||
```
|
||||
**Use cases**: Custom scrollable areas
|
||||
**Dependencies**: @radix-ui/react-scroll-area
|
||||
|
||||
### Resizable
|
||||
Resizable panel layout.
|
||||
```bash
|
||||
npx shadcn@latest add resizable
|
||||
```
|
||||
**Sub-components**: ResizablePanelGroup, ResizablePanel, ResizableHandle
|
||||
**Use cases**: Split views, adjustable layouts
|
||||
**Dependencies**: react-resizable-panels
|
||||
|
||||
## Date & Time
|
||||
|
||||
### Date Picker
|
||||
Select dates with calendar popup.
|
||||
```bash
|
||||
npx shadcn@latest add date-picker
|
||||
```
|
||||
**Variants**: Single date, date range
|
||||
**Dependencies**: react-day-picker, date-fns
|
||||
|
||||
## Advanced Components
|
||||
|
||||
### Carousel
|
||||
Slideshow component.
|
||||
```bash
|
||||
npx shadcn@latest add carousel
|
||||
```
|
||||
**Sub-components**: CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
|
||||
**Dependencies**: embla-carousel-react
|
||||
|
||||
### Drawer
|
||||
Bottom drawer for mobile interfaces.
|
||||
```bash
|
||||
npx shadcn@latest add drawer
|
||||
```
|
||||
**Best for**: Mobile-first designs
|
||||
**Dependencies**: vaul
|
||||
|
||||
## Component Composition Patterns
|
||||
|
||||
### Form + Validation Pattern
|
||||
```bash
|
||||
npx shadcn@latest add form input label button
|
||||
npm install react-hook-form zod @hookform/resolvers
|
||||
```
|
||||
|
||||
### Data Table Pattern
|
||||
```bash
|
||||
npx shadcn@latest add table button dropdown-menu
|
||||
npm install @tanstack/react-table
|
||||
```
|
||||
|
||||
### Dashboard Layout Pattern
|
||||
```bash
|
||||
npx shadcn@latest add card tabs badge avatar
|
||||
```
|
||||
|
||||
### Authentication Pattern
|
||||
```bash
|
||||
npx shadcn@latest add card input label button tabs
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Component | Category | Complexity | Dependencies |
|
||||
|-----------|----------|------------|--------------|
|
||||
| Button | Form | Simple | radix-slot |
|
||||
| Input | Form | Simple | None |
|
||||
| Card | Layout | Simple | None |
|
||||
| Dialog | Overlay | Medium | radix-dialog |
|
||||
| Table | Data | Simple | None |
|
||||
| Form | Form | Complex | radix-label/slot |
|
||||
| Command | Search | Complex | cmdk |
|
||||
| Calendar | Date | Medium | react-day-picker |
|
||||
|
||||
## Installation Shortcuts
|
||||
|
||||
Common component bundles:
|
||||
|
||||
```bash
|
||||
# Essential forms
|
||||
npx shadcn@latest add form input label button select checkbox
|
||||
|
||||
# Data display
|
||||
npx shadcn@latest add table badge avatar progress skeleton
|
||||
|
||||
# Overlay/modal components
|
||||
npx shadcn@latest add dialog sheet popover tooltip alert-dialog
|
||||
|
||||
# Navigation
|
||||
npx shadcn@latest add navigation-menu breadcrumb pagination
|
||||
|
||||
# Layout
|
||||
npx shadcn@latest add card accordion tabs separator
|
||||
```
|
||||
|
||||
## Component Updates
|
||||
|
||||
To update components to the latest version:
|
||||
|
||||
```bash
|
||||
# Re-add component (will prompt to overwrite)
|
||||
npx shadcn@latest add button
|
||||
|
||||
# Or use diff command to see changes
|
||||
npx shadcn@latest diff button
|
||||
```
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Official Component Docs](https://ui.shadcn.com/docs/components)
|
||||
- [Component Examples](https://ui.shadcn.com/examples)
|
||||
- [Radix UI Primitives](https://www.radix-ui.com/primitives)
|
||||
516
.agents/skills/shadcn-ui/resources/customization-guide.md
Normal file
516
.agents/skills/shadcn-ui/resources/customization-guide.md
Normal file
@@ -0,0 +1,516 @@
|
||||
# shadcn/ui Customization Guide
|
||||
|
||||
Learn how to customize shadcn/ui components to match your brand and design requirements.
|
||||
|
||||
## Theming Approach
|
||||
|
||||
shadcn/ui uses a CSS variable-based theming system, making it easy to customize colors, spacing, and other design tokens globally.
|
||||
|
||||
## Color Customization
|
||||
|
||||
### Understanding the Color System
|
||||
|
||||
shadcn/ui uses HSL color values stored as CSS variables. Each color has a base value and a foreground variant for text/content that appears on top of it.
|
||||
|
||||
**Base Color Variables** (in `globals.css`):
|
||||
```css
|
||||
:root {
|
||||
--background: 0 0% 100%; /* Page background */
|
||||
--foreground: 222.2 84% 4.9%; /* Primary text color */
|
||||
--primary: 221.2 83.2% 53.3%; /* Primary brand color */
|
||||
--primary-foreground: 210 40% 98%; /* Text on primary */
|
||||
--secondary: 210 40% 96.1%; /* Secondary actions */
|
||||
--accent: 210 40% 96.1%; /* Accent highlights */
|
||||
--muted: 210 40% 96.1%; /* Muted backgrounds */
|
||||
--destructive: 0 84.2% 60.2%; /* Error/danger */
|
||||
--border: 214.3 31.8% 91.4%; /* Border colors */
|
||||
--input: 214.3 31.8% 91.4%; /* Input borders */
|
||||
--ring: 221.2 83.2% 53.3%; /* Focus rings */
|
||||
}
|
||||
```
|
||||
|
||||
### Changing Brand Colors
|
||||
|
||||
To match your brand, update the primary color:
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Original blue */
|
||||
--primary: 221.2 83.2% 53.3%;
|
||||
|
||||
/* Change to brand purple */
|
||||
--primary: 270 91% 65%;
|
||||
|
||||
/* Adjust foreground for contrast */
|
||||
--primary-foreground: 0 0% 100%;
|
||||
}
|
||||
```
|
||||
|
||||
**HSL Format**: `hue saturation lightness`
|
||||
- Hue: 0-360 (color wheel position)
|
||||
- Saturation: 0-100% (color intensity)
|
||||
- Lightness: 0-100% (brightness)
|
||||
|
||||
### Tools for Color Selection
|
||||
|
||||
1. **HSL Color Picker**: https://hslpicker.com/
|
||||
2. **Shadcn Theme Generator**: https://ui.shadcn.com/themes
|
||||
3. **Coolors**: https://coolors.co/ (generates palettes)
|
||||
|
||||
### Creating a Color Scheme
|
||||
|
||||
Start with your primary brand color, then derive other colors:
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* 1. Primary brand color */
|
||||
--primary: 230 90% 60%;
|
||||
--primary-foreground: 0 0% 100%;
|
||||
|
||||
/* 2. Lighter variant for secondary */
|
||||
--secondary: 230 30% 95%;
|
||||
--secondary-foreground: 230 90% 30%;
|
||||
|
||||
/* 3. Subtle accent (shift hue slightly) */
|
||||
--accent: 200 90% 60%;
|
||||
--accent-foreground: 0 0% 100%;
|
||||
|
||||
/* 4. Muted backgrounds (low saturation) */
|
||||
--muted: 230 20% 96%;
|
||||
--muted-foreground: 230 20% 40%;
|
||||
|
||||
/* 5. Keep destructive red-based */
|
||||
--destructive: 0 84% 60%;
|
||||
--destructive-foreground: 0 0% 100%;
|
||||
}
|
||||
```
|
||||
|
||||
## Dark Mode
|
||||
|
||||
### Setting Up Dark Mode
|
||||
|
||||
shadcn/ui includes dark mode support out of the box. Add dark mode colors:
|
||||
|
||||
```css
|
||||
.dark {
|
||||
--background: 222.2 84% 4.9%;
|
||||
--foreground: 210 40% 98%;
|
||||
--primary: 221.2 83.2% 53.3%;
|
||||
--primary-foreground: 210 40% 98%;
|
||||
/* ... all color variables */
|
||||
}
|
||||
```
|
||||
|
||||
### Toggle Dark Mode
|
||||
|
||||
**Next.js with next-themes**:
|
||||
```bash
|
||||
npm install next-themes
|
||||
```
|
||||
|
||||
```tsx
|
||||
// app/providers.tsx
|
||||
"use client"
|
||||
|
||||
import { ThemeProvider } from "next-themes"
|
||||
|
||||
export function Providers({ children }: { children: React.ReactNode }) {
|
||||
return (
|
||||
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
|
||||
{children}
|
||||
</ThemeProvider>
|
||||
)
|
||||
}
|
||||
|
||||
// app/layout.tsx
|
||||
import { Providers } from "./providers"
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html suppressHydrationWarning>
|
||||
<body>
|
||||
<Providers>{children}</Providers>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
|
||||
// components/theme-toggle.tsx
|
||||
"use client"
|
||||
|
||||
import { Moon, Sun } from "lucide-react"
|
||||
import { useTheme } from "next-themes"
|
||||
import { Button } from "@/components/ui/button"
|
||||
|
||||
export function ThemeToggle() {
|
||||
const { setTheme, theme } = useTheme()
|
||||
|
||||
return (
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="icon"
|
||||
onClick={() => setTheme(theme === "light" ? "dark" : "light")}
|
||||
>
|
||||
<Sun className="h-5 w-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
|
||||
<Moon className="absolute h-5 w-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
|
||||
<span className="sr-only">Toggle theme</span>
|
||||
</Button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Component Customization
|
||||
|
||||
### Using Variants
|
||||
|
||||
shadcn/ui components use `class-variance-authority` (cva) for variants. Example from Button:
|
||||
|
||||
```typescript
|
||||
// components/ui/button.tsx
|
||||
import { cva, type VariantProps } from "class-variance-authority"
|
||||
|
||||
const buttonVariants = cva(
|
||||
"inline-flex items-center justify-center rounded-md text-sm font-medium",
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: "bg-primary text-primary-foreground hover:bg-primary/90",
|
||||
destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
|
||||
outline: "border border-input bg-background hover:bg-accent",
|
||||
ghost: "hover:bg-accent hover:text-accent-foreground",
|
||||
link: "text-primary underline-offset-4 hover:underline",
|
||||
},
|
||||
size: {
|
||||
default: "h-10 px-4 py-2",
|
||||
sm: "h-9 rounded-md px-3",
|
||||
lg: "h-11 rounded-md px-8",
|
||||
icon: "h-10 w-10",
|
||||
},
|
||||
},
|
||||
defaultVariants: {
|
||||
variant: "default",
|
||||
size: "default",
|
||||
},
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Adding Custom Variants
|
||||
|
||||
To add a new variant, edit the component file in `components/ui/`:
|
||||
|
||||
```typescript
|
||||
// Add new "success" variant to button
|
||||
const buttonVariants = cva(
|
||||
"...",
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: "...",
|
||||
destructive: "...",
|
||||
// Add new variant
|
||||
success: "bg-green-600 text-white hover:bg-green-700",
|
||||
},
|
||||
// Add new size
|
||||
size: {
|
||||
default: "...",
|
||||
xl: "h-12 rounded-md px-10 text-base",
|
||||
},
|
||||
},
|
||||
}
|
||||
)
|
||||
|
||||
// Update TypeScript interface
|
||||
export interface ButtonProps
|
||||
extends React.ButtonHTMLAttributes<HTMLButtonElement>,
|
||||
VariantProps<typeof buttonVariants> {
|
||||
asChild?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
Usage:
|
||||
```tsx
|
||||
<Button variant="success" size="xl">Save Changes</Button>
|
||||
```
|
||||
|
||||
### Creating Composite Components
|
||||
|
||||
Don't modify `components/ui/` directly. Instead, create wrapper components:
|
||||
|
||||
```tsx
|
||||
// components/loading-button.tsx
|
||||
import { Button, ButtonProps } from "@/components/ui/button"
|
||||
import { Loader2 } from "lucide-react"
|
||||
|
||||
interface LoadingButtonProps extends ButtonProps {
|
||||
loading?: boolean
|
||||
}
|
||||
|
||||
export function LoadingButton({
|
||||
loading,
|
||||
children,
|
||||
disabled,
|
||||
...props
|
||||
}: LoadingButtonProps) {
|
||||
return (
|
||||
<Button disabled={loading || disabled} {...props}>
|
||||
{loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
|
||||
{children}
|
||||
</Button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Typography Customization
|
||||
|
||||
### Font Family
|
||||
|
||||
Update `tailwind.config.js`:
|
||||
|
||||
```javascript
|
||||
module.exports = {
|
||||
theme: {
|
||||
extend: {
|
||||
fontFamily: {
|
||||
sans: ['Inter', 'system-ui', 'sans-serif'],
|
||||
heading: ['Poppins', 'system-ui', 'sans-serif'],
|
||||
mono: ['Fira Code', 'monospace'],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Import fonts in your layout:
|
||||
|
||||
```tsx
|
||||
// app/layout.tsx
|
||||
import { Inter, Poppins } from 'next/font/google'
|
||||
|
||||
const inter = Inter({ subsets: ['latin'], variable: '--font-sans' })
|
||||
const poppins = Poppins({
|
||||
weight: ['600', '700'],
|
||||
subsets: ['latin'],
|
||||
variable: '--font-heading',
|
||||
})
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html className={`${inter.variable} ${poppins.variable}`}>
|
||||
<body className="font-sans">{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Use in components:
|
||||
```tsx
|
||||
<h1 className="font-heading text-3xl">Heading</h1>
|
||||
<p className="font-sans">Body text</p>
|
||||
```
|
||||
|
||||
### Font Sizes
|
||||
|
||||
Extend Tailwind's font scale:
|
||||
|
||||
```javascript
|
||||
// tailwind.config.js
|
||||
module.exports = {
|
||||
theme: {
|
||||
extend: {
|
||||
fontSize: {
|
||||
'xs': '0.75rem', // 12px
|
||||
'sm': '0.875rem', // 14px
|
||||
'base': '1rem', // 16px
|
||||
'lg': '1.125rem', // 18px
|
||||
'xl': '1.25rem', // 20px
|
||||
'2xl': '1.5rem', // 24px
|
||||
'3xl': '1.875rem', // 30px
|
||||
'4xl': '2.25rem', // 36px
|
||||
'5xl': '3rem', // 48px
|
||||
'6xl': '3.75rem', // 60px
|
||||
'7xl': '4.5rem', // 72px
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Spacing & Layout
|
||||
|
||||
### Border Radius
|
||||
|
||||
Customize roundedness globally:
|
||||
|
||||
```css
|
||||
/* globals.css */
|
||||
:root {
|
||||
--radius: 0.5rem; /* Default (8px) */
|
||||
|
||||
/* More rounded */
|
||||
--radius: 1rem; /* 16px */
|
||||
|
||||
/* Sharp edges */
|
||||
--radius: 0; /* No rounding */
|
||||
|
||||
/* Very rounded */
|
||||
--radius: 1.5rem; /* 24px */
|
||||
}
|
||||
```
|
||||
|
||||
This affects all components using `rounded-lg`, `rounded-md`, `rounded-sm`.
|
||||
|
||||
### Custom Spacing
|
||||
|
||||
Extend Tailwind's spacing scale:
|
||||
|
||||
```javascript
|
||||
// tailwind.config.js
|
||||
module.exports = {
|
||||
theme: {
|
||||
extend: {
|
||||
spacing: {
|
||||
'72': '18rem',
|
||||
'84': '21rem',
|
||||
'96': '24rem',
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Animation Customization
|
||||
|
||||
### Adjusting Existing Animations
|
||||
|
||||
```javascript
|
||||
// tailwind.config.js
|
||||
module.exports = {
|
||||
theme: {
|
||||
extend: {
|
||||
keyframes: {
|
||||
// Make accordion faster
|
||||
"accordion-down": {
|
||||
from: { height: 0 },
|
||||
to: { height: "var(--radix-accordion-content-height)" },
|
||||
},
|
||||
"accordion-up": {
|
||||
from: { height: "var(--radix-accordion-content-height)" },
|
||||
to: { height: 0 },
|
||||
},
|
||||
},
|
||||
animation: {
|
||||
"accordion-down": "accordion-down 0.15s ease-out", // Faster
|
||||
"accordion-up": "accordion-up 0.15s ease-out",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Adding New Animations
|
||||
|
||||
```javascript
|
||||
// tailwind.config.js
|
||||
module.exports = {
|
||||
theme: {
|
||||
extend: {
|
||||
keyframes: {
|
||||
"fade-in": {
|
||||
"0%": { opacity: 0 },
|
||||
"100%": { opacity: 1 },
|
||||
},
|
||||
"slide-in-bottom": {
|
||||
"0%": { transform: "translateY(100%)" },
|
||||
"100%": { transform: "translateY(0)" },
|
||||
},
|
||||
},
|
||||
animation: {
|
||||
"fade-in": "fade-in 0.3s ease-out",
|
||||
"slide-in-bottom": "slide-in-bottom 0.3s ease-out",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Use in components:
|
||||
```tsx
|
||||
<div className="animate-fade-in">Content</div>
|
||||
```
|
||||
|
||||
## Advanced Customization
|
||||
|
||||
### Creating a Design System
|
||||
|
||||
Structure your customizations:
|
||||
|
||||
```
|
||||
src/
|
||||
├── styles/
|
||||
│ ├── globals.css # CSS variables & base styles
|
||||
│ ├── themes/
|
||||
│ │ ├── default.css # Default theme
|
||||
│ │ └── brand.css # Brand-specific overrides
|
||||
│ └── components/
|
||||
│ └── custom.css # Component-specific styles
|
||||
├── lib/
|
||||
│ └── design-tokens.ts # Shared constants
|
||||
└── components/
|
||||
├── ui/ # shadcn components (don't modify)
|
||||
└── custom/ # Your wrapper components
|
||||
```
|
||||
|
||||
### Design Tokens File
|
||||
|
||||
```typescript
|
||||
// lib/design-tokens.ts
|
||||
export const designTokens = {
|
||||
colors: {
|
||||
brand: {
|
||||
primary: 'hsl(230, 90%, 60%)',
|
||||
secondary: 'hsl(230, 30%, 95%)',
|
||||
},
|
||||
},
|
||||
spacing: {
|
||||
section: '5rem',
|
||||
card: '1.5rem',
|
||||
},
|
||||
radius: {
|
||||
card: '1rem',
|
||||
button: '0.5rem',
|
||||
},
|
||||
typography: {
|
||||
h1: 'text-5xl font-heading font-bold',
|
||||
h2: 'text-4xl font-heading font-semibold',
|
||||
h3: 'text-3xl font-heading font-semibold',
|
||||
body: 'text-base font-sans',
|
||||
small: 'text-sm text-muted-foreground',
|
||||
},
|
||||
} as const
|
||||
```
|
||||
|
||||
Use in components:
|
||||
```tsx
|
||||
import { designTokens } from "@/lib/design-tokens"
|
||||
|
||||
<h1 className={designTokens.typography.h1}>Title</h1>
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Don't modify `components/ui/` files directly**: Create wrapper components instead
|
||||
2. **Use CSS variables for theming**: Easier to maintain and switch themes
|
||||
3. **Leverage Tailwind's `extend`**: Don't replace defaults, extend them
|
||||
4. **Keep variants in component files**: Co-locate variant logic with components
|
||||
5. **Test dark mode**: Ensure all customizations work in both themes
|
||||
6. **Document custom variants**: Add comments for custom additions
|
||||
7. **Use consistent spacing**: Stick to Tailwind's spacing scale
|
||||
8. **Maintain accessibility**: Don't sacrifice contrast for aesthetics
|
||||
|
||||
## Resources
|
||||
|
||||
- [Tailwind CSS Customization](https://tailwindcss.com/docs/theme)
|
||||
- [CVA Documentation](https://cva.style/docs)
|
||||
- [Radix UI Theming](https://www.radix-ui.com/themes/docs/theme/overview)
|
||||
- [HSL Color Theory](https://www.w3.org/TR/css-color-3/#hsl-color)
|
||||
463
.agents/skills/shadcn-ui/resources/migration-guide.md
Normal file
463
.agents/skills/shadcn-ui/resources/migration-guide.md
Normal file
@@ -0,0 +1,463 @@
|
||||
# Migration Guide to shadcn/ui
|
||||
|
||||
This guide helps you migrate from other UI libraries to shadcn/ui.
|
||||
|
||||
## Why Migrate to shadcn/ui?
|
||||
|
||||
- **Full ownership**: Code lives in your project, not node_modules
|
||||
- **Customizable**: Modify any component to fit your needs
|
||||
- **No breaking changes**: Update components individually
|
||||
- **Smaller bundles**: Only include what you use
|
||||
- **Modern stack**: Built with Radix UI and Tailwind CSS
|
||||
- **Type-safe**: Full TypeScript support
|
||||
|
||||
## Migration Strategies
|
||||
|
||||
### Strategy 1: Incremental Migration (Recommended)
|
||||
|
||||
Gradually replace components over time:
|
||||
|
||||
1. Install shadcn/ui alongside existing library
|
||||
2. Replace components page by page or feature by feature
|
||||
3. Remove old library once migration is complete
|
||||
|
||||
**Pros**: Low risk, can be done alongside feature work
|
||||
**Cons**: Temporary bundle size increase
|
||||
|
||||
### Strategy 2: Big Bang Migration
|
||||
|
||||
Replace all components at once:
|
||||
|
||||
1. Set up shadcn/ui
|
||||
2. Create component mapping document
|
||||
3. Replace all components in one effort
|
||||
4. Test thoroughly
|
||||
|
||||
**Pros**: Clean cutover, no mixed UI
|
||||
**Cons**: High risk, requires dedicated time
|
||||
|
||||
## Internal Migrations (shadcn specific)
|
||||
|
||||
### RTL Support Migration
|
||||
If you need to support RTL languages (like Arabic or Hebrew) in an existing shadcn/ui project:
|
||||
|
||||
```bash
|
||||
npx shadcn@latest migrate rtl
|
||||
```
|
||||
|
||||
This CLI command transforms your components to use **logical properties**:
|
||||
- `ml-4` -> `ms-4` (margin-start)
|
||||
- `pl-4` -> `ps-4` (padding-start)
|
||||
- `text-left` -> `text-start`
|
||||
|
||||
It ensures your UI adapts correctly to layout direction without manual refactoring.
|
||||
|
||||
## From Material-UI (MUI)
|
||||
|
||||
### Component Mapping
|
||||
|
||||
| MUI Component | shadcn/ui Equivalent | Notes |
|
||||
|---------------|----------------------|-------|
|
||||
| Button | Button | Similar API |
|
||||
| TextField | Input + Label | Separate components |
|
||||
| Select | Select | Different structure |
|
||||
| Dialog | Dialog | Similar concept |
|
||||
| Drawer | Sheet | Side panel |
|
||||
| Card | Card | Very similar |
|
||||
| Table | Table | Use with TanStack Table |
|
||||
| Checkbox | Checkbox | Similar API |
|
||||
| Switch | Switch | Similar API |
|
||||
| Tabs | Tabs | Similar structure |
|
||||
| Tooltip | Tooltip | Simpler API |
|
||||
| Menu | Dropdown Menu | Different trigger model |
|
||||
| Snackbar | Toast | Different implementation |
|
||||
| Autocomplete | Combobox | Use with Command |
|
||||
|
||||
### Key Differences
|
||||
|
||||
**1. Import Structure**
|
||||
```tsx
|
||||
// MUI
|
||||
import Button from '@mui/material/Button'
|
||||
|
||||
// shadcn/ui
|
||||
import { Button } from '@/components/ui/button'
|
||||
```
|
||||
|
||||
**2. Form Components**
|
||||
```tsx
|
||||
// MUI
|
||||
<TextField
|
||||
label="Email"
|
||||
value={email}
|
||||
onChange={(e) => setEmail(e.target.value)}
|
||||
error={!!errors.email}
|
||||
helperText={errors.email}
|
||||
/>
|
||||
|
||||
// shadcn/ui
|
||||
<div className="space-y-2">
|
||||
<Label htmlFor="email">Email</Label>
|
||||
<Input
|
||||
id="email"
|
||||
value={email}
|
||||
onChange={(e) => setEmail(e.target.value)}
|
||||
/>
|
||||
{errors.email && (
|
||||
<p className="text-sm text-destructive">{errors.email}</p>
|
||||
)}
|
||||
</div>
|
||||
|
||||
// Or with Form component
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="email"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormLabel>Email</FormLabel>
|
||||
<FormControl>
|
||||
<Input {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
```
|
||||
|
||||
**3. Theming**
|
||||
```tsx
|
||||
// MUI
|
||||
import { ThemeProvider, createTheme } from '@mui/material/styles'
|
||||
|
||||
const theme = createTheme({
|
||||
palette: {
|
||||
primary: { main: '#1976d2' },
|
||||
},
|
||||
})
|
||||
|
||||
<ThemeProvider theme={theme}>
|
||||
<App />
|
||||
</ThemeProvider>
|
||||
|
||||
// shadcn/ui
|
||||
// Edit globals.css
|
||||
:root {
|
||||
--primary: 215 100% 50%;
|
||||
}
|
||||
```
|
||||
|
||||
**4. Styling Approach**
|
||||
```tsx
|
||||
// MUI (sx prop)
|
||||
<Button sx={{ px: 4, py: 2, borderRadius: 2 }}>
|
||||
Click me
|
||||
</Button>
|
||||
|
||||
// shadcn/ui (Tailwind classes)
|
||||
<Button className="px-4 py-2 rounded-lg">
|
||||
Click me
|
||||
</Button>
|
||||
```
|
||||
|
||||
### Migration Example: Login Form
|
||||
|
||||
**Before (MUI)**:
|
||||
```tsx
|
||||
import { TextField, Button, Box } from '@mui/material'
|
||||
|
||||
export function LoginForm() {
|
||||
return (
|
||||
<Box component="form" sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
|
||||
<TextField label="Email" type="email" required />
|
||||
<TextField label="Password" type="password" required />
|
||||
<Button variant="contained" type="submit">
|
||||
Sign In
|
||||
</Button>
|
||||
</Box>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**After (shadcn/ui)**:
|
||||
```tsx
|
||||
import { Input } from '@/components/ui/input'
|
||||
import { Label } from '@/components/ui/label'
|
||||
import { Button } from '@/components/ui/button'
|
||||
|
||||
export function LoginForm() {
|
||||
return (
|
||||
<form className="flex flex-col gap-4">
|
||||
<div className="space-y-2">
|
||||
<Label htmlFor="email">Email</Label>
|
||||
<Input id="email" type="email" required />
|
||||
</div>
|
||||
<div className="space-y-2">
|
||||
<Label htmlFor="password">Password</Label>
|
||||
<Input id="password" type="password" required />
|
||||
</div>
|
||||
<Button type="submit">Sign In</Button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## From Chakra UI
|
||||
|
||||
### Component Mapping
|
||||
|
||||
| Chakra UI | shadcn/ui | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| Button | Button | Similar variants |
|
||||
| Input | Input | More basic |
|
||||
| Select | Select | Different structure |
|
||||
| Modal | Dialog | Similar concept |
|
||||
| Drawer | Sheet | Very similar |
|
||||
| Box | div | Use Tailwind classes |
|
||||
| Flex | div | Use flex utilities |
|
||||
| Stack | div | Use space-y-* classes |
|
||||
| Text | p/span | Use typography classes |
|
||||
| Heading | h1/h2/etc | Use typography classes |
|
||||
| useToast | useToast | Different API |
|
||||
| Menu | Dropdown Menu | Similar |
|
||||
|
||||
### Key Differences
|
||||
|
||||
**1. Layout Components**
|
||||
```tsx
|
||||
// Chakra UI
|
||||
<Stack spacing={4} direction="column">
|
||||
<Box>Item 1</Box>
|
||||
<Box>Item 2</Box>
|
||||
</Stack>
|
||||
|
||||
// shadcn/ui
|
||||
<div className="flex flex-col space-y-4">
|
||||
<div>Item 1</div>
|
||||
<div>Item 2</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**2. Responsive Styles**
|
||||
```tsx
|
||||
// Chakra UI
|
||||
<Box display={{ base: 'block', md: 'flex' }} />
|
||||
|
||||
// shadcn/ui
|
||||
<div className="block md:flex" />
|
||||
```
|
||||
|
||||
**3. Color Mode**
|
||||
```tsx
|
||||
// Chakra UI
|
||||
import { useColorMode } from '@chakra-ui/react'
|
||||
|
||||
const { colorMode, toggleColorMode } = useColorMode()
|
||||
|
||||
// shadcn/ui (with next-themes)
|
||||
import { useTheme } from 'next-themes'
|
||||
|
||||
const { theme, setTheme } = useTheme()
|
||||
```
|
||||
|
||||
## From Ant Design
|
||||
|
||||
### Component Mapping
|
||||
|
||||
| Ant Design | shadcn/ui | Notes |
|
||||
|------------|-----------|-------|
|
||||
| Button | Button | Similar |
|
||||
| Input | Input | More basic |
|
||||
| Form | Form | Different approach |
|
||||
| Table | Table | Use TanStack Table |
|
||||
| Modal | Dialog | Similar |
|
||||
| Drawer | Sheet | Similar |
|
||||
| Select | Select | Different API |
|
||||
| DatePicker | Calendar + Popover | More manual |
|
||||
| Menu | Navigation Menu | Different |
|
||||
| message | Toast | Different API |
|
||||
| notification | Toast | Similar concept |
|
||||
|
||||
### Key Differences
|
||||
|
||||
**1. Form Handling**
|
||||
```tsx
|
||||
// Ant Design
|
||||
<Form
|
||||
form={form}
|
||||
onFinish={onSubmit}
|
||||
>
|
||||
<Form.Item name="email" rules={[{ required: true }]}>
|
||||
<Input />
|
||||
</Form.Item>
|
||||
<Form.Item>
|
||||
<Button type="primary" htmlType="submit">Submit</Button>
|
||||
</Form.Item>
|
||||
</Form>
|
||||
|
||||
// shadcn/ui (with react-hook-form)
|
||||
<Form {...form}>
|
||||
<form onSubmit={form.handleSubmit(onSubmit)}>
|
||||
<FormField
|
||||
control={form.control}
|
||||
name="email"
|
||||
render={({ field }) => (
|
||||
<FormItem>
|
||||
<FormControl>
|
||||
<Input {...field} />
|
||||
</FormControl>
|
||||
<FormMessage />
|
||||
</FormItem>
|
||||
)}
|
||||
/>
|
||||
<Button type="submit">Submit</Button>
|
||||
</form>
|
||||
</Form>
|
||||
```
|
||||
|
||||
**2. Notifications**
|
||||
```tsx
|
||||
// Ant Design
|
||||
import { message } from 'antd'
|
||||
|
||||
message.success('Success!')
|
||||
|
||||
// shadcn/ui
|
||||
import { useToast } from '@/components/ui/use-toast'
|
||||
|
||||
const { toast } = useToast()
|
||||
|
||||
toast({
|
||||
title: "Success!",
|
||||
description: "Operation completed.",
|
||||
})
|
||||
```
|
||||
|
||||
## From Bootstrap
|
||||
|
||||
### Component Mapping
|
||||
|
||||
| Bootstrap | shadcn/ui | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| btn | Button | Similar variants |
|
||||
| form-control | Input | Similar |
|
||||
| card | Card | Very similar structure |
|
||||
| modal | Dialog | Different API |
|
||||
| dropdown | Dropdown Menu | Similar concept |
|
||||
| nav/navbar | Navigation Menu | Different |
|
||||
| alert | Alert | Similar |
|
||||
| badge | Badge | Similar |
|
||||
| table | Table | Use with TanStack Table |
|
||||
|
||||
### Key Differences
|
||||
|
||||
**1. Class-Based vs Component-Based**
|
||||
```tsx
|
||||
// Bootstrap
|
||||
<button className="btn btn-primary btn-lg">
|
||||
Click me
|
||||
</button>
|
||||
|
||||
// shadcn/ui
|
||||
<Button variant="default" size="lg">
|
||||
Click me
|
||||
</Button>
|
||||
```
|
||||
|
||||
**2. Cards**
|
||||
```html
|
||||
<!-- Bootstrap -->
|
||||
<div class="card">
|
||||
<div class="card-header">Title</div>
|
||||
<div class="card-body">Content</div>
|
||||
<div class="card-footer">Footer</div>
|
||||
</div>
|
||||
|
||||
<!-- shadcn/ui -->
|
||||
<Card>
|
||||
<CardHeader>
|
||||
<CardTitle>Title</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent>Content</CardContent>
|
||||
<CardFooter>Footer</CardFooter>
|
||||
</Card>
|
||||
```
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
### Before Migration
|
||||
|
||||
- [ ] Audit current component usage
|
||||
- [ ] Set up shadcn/ui in a test branch
|
||||
- [ ] Create component mapping document
|
||||
- [ ] Plan migration order (start with simple components)
|
||||
- [ ] Set up Tailwind CSS properly
|
||||
- [ ] Configure path aliases
|
||||
|
||||
### During Migration
|
||||
|
||||
- [ ] Install shadcn/ui components as needed
|
||||
- [ ] Replace components incrementally
|
||||
- [ ] Update styling to use Tailwind classes
|
||||
- [ ] Test each page/feature after migration
|
||||
- [ ] Update tests to match new components
|
||||
- [ ] Handle form validation (switch to react-hook-form + zod)
|
||||
- [ ] Migrate theme/color variables
|
||||
|
||||
### After Migration
|
||||
|
||||
- [ ] Remove old UI library dependencies
|
||||
- [ ] Clean up unused imports
|
||||
- [ ] Optimize bundle size
|
||||
- [ ] Update documentation
|
||||
- [ ] Review and update design system
|
||||
- [ ] Train team on new components
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### 1. Not Setting Up Tailwind Properly
|
||||
|
||||
shadcn/ui requires Tailwind. Ensure:
|
||||
- `tailwind.config.js` includes correct content paths
|
||||
- CSS variables are defined in `globals.css`
|
||||
- Tailwind plugins are installed (e.g., `tailwindcss-animate`)
|
||||
|
||||
### 2. Forgetting Path Aliases
|
||||
|
||||
Components use `@/` imports. Configure:
|
||||
- `tsconfig.json` with path aliases
|
||||
- Vite/Next.js config for runtime resolution
|
||||
|
||||
### 3. Trying to Match Old Library Exactly
|
||||
|
||||
Don't force shadcn/ui to work like your old library. Embrace the new patterns:
|
||||
- Use composition over configuration
|
||||
- Leverage Tailwind utilities
|
||||
- Create wrapper components for custom needs
|
||||
|
||||
### 4. Not Using Form Libraries
|
||||
|
||||
shadcn/ui form components are basic. For complex forms, use:
|
||||
- `react-hook-form` for form state
|
||||
- `zod` for validation
|
||||
- shadcn's `Form` component for integration
|
||||
|
||||
### 5. Ignoring Accessibility
|
||||
|
||||
While shadcn/ui is accessible by default, custom modifications can break this. Test with:
|
||||
- Keyboard navigation
|
||||
- Screen readers
|
||||
- ARIA attribute validation
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Discord**: [shadcn/ui Discord](https://discord.com/invite/vNvTqVaWm6)
|
||||
- **GitHub Discussions**: [shadcn/ui Discussions](https://github.com/shadcn-ui/ui/discussions)
|
||||
- **Documentation**: [ui.shadcn.com](https://ui.shadcn.com)
|
||||
|
||||
## Next Steps
|
||||
|
||||
After migration:
|
||||
1. Review the [Customization Guide](./customization-guide.md)
|
||||
2. Explore the [Component Catalog](./component-catalog.md)
|
||||
3. Check out [Examples](../examples/)
|
||||
4. Consider building a component library on top of shadcn/ui
|
||||
412
.agents/skills/shadcn-ui/resources/setup-guide.md
Normal file
412
.agents/skills/shadcn-ui/resources/setup-guide.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# shadcn/ui Setup Guide
|
||||
|
||||
This guide walks you through setting up shadcn/ui in both new and existing projects.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you begin, ensure you have:
|
||||
- **Node.js 18+** installed
|
||||
- **React 18+** in your project
|
||||
- **Tailwind CSS 3.0+** configured
|
||||
- A package manager: npm, yarn, pnpm, or bun
|
||||
|
||||
## Quick Start (New Project)
|
||||
|
||||
### Option 1: npx shadcn create (Recommended)
|
||||
|
||||
The easiest way to start a new project with shadcn/ui is using the `create` command, which allows you to customize everything (framework, library, style, font, etc.).
|
||||
|
||||
```bash
|
||||
npx shadcn@latest create
|
||||
```
|
||||
|
||||
This interactive command will guide you through:
|
||||
1. **Project Name**: Directory for your app.
|
||||
2. **Visual Style**: Choose from Vega, Nova, Maia, Lyra, Mira, or Classic.
|
||||
3. **Base Color**: Select your primary theme color.
|
||||
4. **Framework**: Next.js, Vite, Laravel, etc.
|
||||
5. **Component Library**: Choose **Radix UI** or **Base UI**.
|
||||
6. **RTL Support**: Enable Right-to-Left support if needed.
|
||||
|
||||
### Option 2: Classic Manual Setup (Next.js)
|
||||
|
||||
```bash
|
||||
# Create a new Next.js project
|
||||
npx create-next-app@latest my-app
|
||||
cd my-app
|
||||
|
||||
# Initialize shadcn/ui
|
||||
npx shadcn@latest init
|
||||
|
||||
# Add your first component
|
||||
npx shadcn@latest add button
|
||||
```
|
||||
|
||||
### Option 3: Classic Manual Setup (Vite + React)
|
||||
|
||||
```bash
|
||||
# Create a new Vite project
|
||||
npm create vite@latest my-app -- --template react-ts
|
||||
cd my-app
|
||||
npm install
|
||||
|
||||
# Install Tailwind CSS
|
||||
npm install -D tailwindcss postcss autoprefixer
|
||||
npx tailwindcss init -p
|
||||
|
||||
# Initialize shadcn/ui
|
||||
npx shadcn@latest init
|
||||
|
||||
# Add your first component
|
||||
npx shadcn@latest add button
|
||||
```
|
||||
|
||||
## Existing Project Setup
|
||||
|
||||
### Step 1: Ensure Tailwind CSS is Installed
|
||||
|
||||
If Tailwind is not installed:
|
||||
|
||||
```bash
|
||||
npm install -D tailwindcss postcss autoprefixer
|
||||
npx tailwindcss init -p
|
||||
```
|
||||
|
||||
Configure `tailwind.config.js`:
|
||||
|
||||
```javascript
|
||||
/** @type {import('tailwindcss').Config} */
|
||||
export default {
|
||||
content: [
|
||||
"./index.html",
|
||||
"./src/**/*.{js,ts,jsx,tsx}",
|
||||
],
|
||||
theme: {
|
||||
extend: {},
|
||||
},
|
||||
plugins: [],
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Initialize shadcn/ui
|
||||
|
||||
Run the initialization command:
|
||||
|
||||
```bash
|
||||
npx shadcn@latest init
|
||||
```
|
||||
|
||||
You'll be asked to configure:
|
||||
|
||||
1. **Style**: Choose between `default`, `new-york`, or one of the new styles (Vega, Nova, etc.)
|
||||
- `default`: Clean and minimal design
|
||||
- `new-york`: More refined with subtle details
|
||||
|
||||
2. **Base Color**: Choose your primary color palette
|
||||
- slate, gray, zinc, neutral, or stone
|
||||
|
||||
3. **CSS Variables**: Recommend `yes` for easier theming
|
||||
|
||||
4. **TypeScript**: Recommend `yes` for type safety
|
||||
|
||||
5. **Import Alias**: Default is `@/components` (recommended)
|
||||
|
||||
6. **React Server Components**: Choose based on your framework
|
||||
- `yes` for Next.js 13+ with app directory
|
||||
- `no` for Vite, CRA, or Next.js pages directory
|
||||
|
||||
7. **RTL Support**: Answer `yes` if you need Right-to-Left layout support (this will use logical properties like `ms-4` instead of `ml-4`).
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Visual Styles
|
||||
shadcn/ui now offers multiple visual styles beyond the defaults:
|
||||
- **Vega**: The classic shadcn/ui look.
|
||||
- **Nova**: Reduced padding/margins, compact.
|
||||
- **Maia**: Soft, rounded, generous spacing.
|
||||
- **Lyra**: Boxy, sharp, mono font friendly.
|
||||
- **Mira**: Dense, compact.
|
||||
|
||||
### Base UI Support
|
||||
You can now choose between **Radix UI** and **Base UI** as the underlying primitive library. They share the same component API/abstraction, so your usage remains consistent.
|
||||
|
||||
|
||||
### Step 3: Verify Configuration
|
||||
|
||||
The init command creates/updates several files:
|
||||
|
||||
**components.json** (root of project):
|
||||
```json
|
||||
{
|
||||
"$schema": "https://ui.shadcn.com/schema.json",
|
||||
"style": "default",
|
||||
"rsc": false,
|
||||
"tsx": true,
|
||||
"tailwind": {
|
||||
"config": "tailwind.config.js",
|
||||
"css": "src/index.css",
|
||||
"baseColor": "slate",
|
||||
"cssVariables": true
|
||||
},
|
||||
"aliases": {
|
||||
"components": "@/components",
|
||||
"utils": "@/lib"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**src/lib/utils.ts**:
|
||||
```typescript
|
||||
import { clsx, type ClassValue } from "clsx"
|
||||
import { twMerge } from "tailwind-merge"
|
||||
|
||||
export function cn(...inputs: ClassValue[]) {
|
||||
return twMerge(clsx(inputs))
|
||||
}
|
||||
```
|
||||
|
||||
**Updated tailwind.config.js**:
|
||||
```javascript
|
||||
/** @type {import('tailwindcss').Config} */
|
||||
module.exports = {
|
||||
darkMode: ["class"],
|
||||
content: [
|
||||
'./pages/**/*.{ts,tsx}',
|
||||
'./components/**/*.{ts,tsx}',
|
||||
'./app/**/*.{ts,tsx}',
|
||||
'./src/**/*.{ts,tsx}',
|
||||
],
|
||||
theme: {
|
||||
container: {
|
||||
center: true,
|
||||
padding: "2rem",
|
||||
screens: {
|
||||
"2xl": "1400px",
|
||||
},
|
||||
},
|
||||
extend: {
|
||||
colors: {
|
||||
border: "hsl(var(--border))",
|
||||
input: "hsl(var(--input))",
|
||||
ring: "hsl(var(--ring))",
|
||||
background: "hsl(var(--background))",
|
||||
foreground: "hsl(var(--foreground))",
|
||||
primary: {
|
||||
DEFAULT: "hsl(var(--primary))",
|
||||
foreground: "hsl(var(--primary-foreground))",
|
||||
},
|
||||
// ... more colors
|
||||
},
|
||||
borderRadius: {
|
||||
lg: "var(--radius)",
|
||||
md: "calc(var(--radius) - 2px)",
|
||||
sm: "calc(var(--radius) - 4px)",
|
||||
},
|
||||
keyframes: {
|
||||
"accordion-down": {
|
||||
from: { height: 0 },
|
||||
to: { height: "var(--radix-accordion-content-height)" },
|
||||
},
|
||||
"accordion-up": {
|
||||
from: { height: "var(--radix-accordion-content-height)" },
|
||||
to: { height: 0 },
|
||||
},
|
||||
},
|
||||
animation: {
|
||||
"accordion-down": "accordion-down 0.2s ease-out",
|
||||
"accordion-up": "accordion-up 0.2s ease-out",
|
||||
},
|
||||
},
|
||||
},
|
||||
plugins: [require("tailwindcss-animate")],
|
||||
}
|
||||
```
|
||||
|
||||
**Updated globals.css** (or equivalent):
|
||||
```css
|
||||
@tailwind base;
|
||||
@tailwind components;
|
||||
@tailwind utilities;
|
||||
|
||||
@layer base {
|
||||
:root {
|
||||
--background: 0 0% 100%;
|
||||
--foreground: 222.2 84% 4.9%;
|
||||
--card: 0 0% 100%;
|
||||
--card-foreground: 222.2 84% 4.9%;
|
||||
--popover: 0 0% 100%;
|
||||
--popover-foreground: 222.2 84% 4.9%;
|
||||
--primary: 221.2 83.2% 53.3%;
|
||||
--primary-foreground: 210 40% 98%;
|
||||
--secondary: 210 40% 96.1%;
|
||||
--secondary-foreground: 222.2 47.4% 11.2%;
|
||||
--muted: 210 40% 96.1%;
|
||||
--muted-foreground: 215.4 16.3% 46.9%;
|
||||
--accent: 210 40% 96.1%;
|
||||
--accent-foreground: 222.2 47.4% 11.2%;
|
||||
--destructive: 0 84.2% 60.2%;
|
||||
--destructive-foreground: 210 40% 98%;
|
||||
--border: 214.3 31.8% 91.4%;
|
||||
--input: 214.3 31.8% 91.4%;
|
||||
--ring: 221.2 83.2% 53.3%;
|
||||
--radius: 0.5rem;
|
||||
}
|
||||
|
||||
.dark {
|
||||
--background: 222.2 84% 4.9%;
|
||||
--foreground: 210 40% 98%;
|
||||
/* ... dark mode variables */
|
||||
}
|
||||
}
|
||||
|
||||
@layer base {
|
||||
* {
|
||||
@apply border-border;
|
||||
}
|
||||
body {
|
||||
@apply bg-background text-foreground;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Configure Path Aliases
|
||||
|
||||
Ensure your `tsconfig.json` includes path aliases:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"baseUrl": ".",
|
||||
"paths": {
|
||||
"@/*": ["./src/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For Vite, also update `vite.config.ts`:
|
||||
|
||||
```typescript
|
||||
import path from "path"
|
||||
import { defineConfig } from "vite"
|
||||
import react from "@vitejs/plugin-react"
|
||||
|
||||
export default defineConfig({
|
||||
plugins: [react()],
|
||||
resolve: {
|
||||
alias: {
|
||||
"@": path.resolve(__dirname, "./src"),
|
||||
},
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### Step 5: Add Components
|
||||
|
||||
Now you can add components:
|
||||
|
||||
```bash
|
||||
# Add individual components
|
||||
npx shadcn@latest add button
|
||||
npx shadcn@latest add card
|
||||
npx shadcn@latest add dialog
|
||||
|
||||
# Add multiple components at once
|
||||
npx shadcn@latest add button card dialog input label
|
||||
```
|
||||
|
||||
Components will be added to `src/components/ui/` by default.
|
||||
|
||||
## Framework-Specific Considerations
|
||||
|
||||
### Next.js App Router
|
||||
|
||||
- Set `rsc: true` in `components.json`
|
||||
- Add `"use client"` to stateful components
|
||||
- Import components work from server components by default
|
||||
|
||||
### Next.js Pages Router
|
||||
|
||||
- Set `rsc: false` in `components.json`
|
||||
- All components are client-side by default
|
||||
|
||||
### Vite
|
||||
|
||||
- Ensure path aliases are configured in `vite.config.ts`
|
||||
- Import `globals.css` in your main entry point (`main.tsx`)
|
||||
|
||||
### Create React App
|
||||
|
||||
- Use `craco` or `react-app-rewired` for path alias support
|
||||
- Or use relative imports instead of aliases
|
||||
|
||||
## Verification Steps
|
||||
|
||||
1. **Check file structure**:
|
||||
```
|
||||
src/
|
||||
├── components/
|
||||
│ └── ui/
|
||||
├── lib/
|
||||
│ └── utils.ts
|
||||
└── index.css (or globals.css)
|
||||
```
|
||||
|
||||
2. **Test a simple component**:
|
||||
```tsx
|
||||
import { Button } from "@/components/ui/button"
|
||||
|
||||
export default function App() {
|
||||
return <Button>Click me</Button>
|
||||
}
|
||||
```
|
||||
|
||||
3. **Verify Tailwind is working**:
|
||||
- Component should render with proper styling
|
||||
- Check browser dev tools for applied classes
|
||||
|
||||
4. **Test dark mode** (if using CSS variables):
|
||||
```tsx
|
||||
<html className="dark">
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Cannot find module '@/components/ui/button'"
|
||||
|
||||
**Solution**: Check path alias configuration in `tsconfig.json` and framework config.
|
||||
|
||||
### Styles not applying
|
||||
|
||||
**Solution**:
|
||||
- Ensure `globals.css` is imported in your app entry point
|
||||
- Verify Tailwind config `content` paths include your files
|
||||
- Check CSS variables are defined in `globals.css`
|
||||
|
||||
### TypeScript errors in components
|
||||
|
||||
**Solution**:
|
||||
- Run `npm install` to ensure all dependencies are installed
|
||||
- Check that `@types/react` is installed
|
||||
- Restart TypeScript server in your editor
|
||||
|
||||
### Components look broken
|
||||
|
||||
**Solution**:
|
||||
- Verify `tailwindcss-animate` is installed: `npm install tailwindcss-animate`
|
||||
- Check that CSS variables are properly defined
|
||||
- Ensure you're not overriding component styles globally
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Browse the [component catalog](./component-catalog.md)
|
||||
2. Read the [customization guide](./customization-guide.md)
|
||||
3. Check out example implementations in `/examples`
|
||||
4. Join the [shadcn/ui Discord](https://discord.com/invite/vNvTqVaWm6)
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Official Documentation](https://ui.shadcn.com)
|
||||
- [Component Examples](https://ui.shadcn.com/examples)
|
||||
- [GitHub Repository](https://github.com/shadcn-ui/ui)
|
||||
- [Tailwind CSS Docs](https://tailwindcss.com/docs)
|
||||
Reference in New Issue
Block a user