---
name: "shadcn/ui Component Library"
description: "Master shadcn/ui: setup, CSS variable theming (HSL), all key components (Button, Card, Dialog, Sheet, Form, DataTable, Command, Toast, Sidebar), advanced patterns (Cmd+K palette, responsive sidebar, theme switcher, charts), customization with cva, and Radix UI accessibility."
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["shadcn", "ui", "radix", "components", "react", "tailwind"]
---

# shadcn/ui Component Library

---
name: "shadcn/ui Component Library"
description: "Master shadcn/ui: setup, CSS variable theming (HSL), all key components (Button, Card, Dialog, Sheet, Form, DataTable, Command, Toast, Sidebar), advanced patterns (Cmd+K palette, responsive sidebar, t"
version: "1.0.0"
author: "skynet"
category: "dev"
tags: ["shadcn", "ui", "radix", "components", "react", "tailwind"]
---

I will search the knowledge graph for any existing documentation on shadcn/ui and Tailwind CSS to ensure the reference is consistent with any previously stored insights.
I will retrieve the details of the existing node to incorporate its contents into the comprehensive technical reference.
I will use Google search to gather the latest details on shadcn/ui initialization, `components.json` structure, and the newest features of the components requested by the user.
I will now refine my search by breaking it down into smaller, more specific queries, starting with shadcn/ui initialization and theming.
I will conduct another targeted search to obtain the remaining details on shadcn/ui initialization, HSL theming, form and DataTable examples, Recharts integration, and CVA variants.
I will now construct the code examples for the Button variants, Card structure, and CVA customization, and I will perform one last targeted search for specific Form, DataTable, and Recharts code snippets to ensure the highest accuracy.
This technical reference provides a blueprint for building premium, accessible, and high-performance user interfaces using **shadcn/ui** and **Tailwind CSS**.

### 1. SETUP: The Modern Workflow
The modern `shadcn` CLI (v2.0+) features automatic framework detection and a refined configuration schema.

*   **Initialization:**
    ```bash
    npx shadcn@latest init
    ```
*   **`components.json` Configuration:**
    Ensure your configuration uses the `New York` style and defines explicit aliases for clean imports.
    ```json
    {
      "$schema": "https://ui.shadcn.com/schema.json",
      "style": "new-york",
      "rsc": true,
      "tailwind": {
        "config": "tailwind.config.js",
        "css": "app/globals.css",
        "baseColor": "zinc",
        "cssVariables": true
      },
      "aliases": {
        "components": "@/components",
        "ui": "@/components/ui",
        "utils": "@/lib/utils"
      }
    }
    ```

### 2. THEMING: The HSL Variable System
Shadcn/ui uses HSL values in `globals.css` without the `hsl()` wrapper. This allows Tailwind to inject opacity modifiers (e.g., `bg-primary/50`).

*   **Core Variables:**
    ```css
    @layer base {
      :root {
        --background: 0 0% 100%;
        --foreground: 240 10% 3.9%;
        --primary: 240 5.9% 10%;
        --primary-foreground: 0 0% 98%;
        --destructive: 0 84.2% 60.2%;
        --border: 240 5.9% 90%;
        --radius: 0.5rem;
      }
      .dark {
        --background: 240 10% 3.9%;
        --foreground: 0 0% 98%;
        --primary: 0 0% 98%;
        --primary-foreground: 240 5.9% 10%;
      }
    }
    ```

### 3. KEY COMPONENTS: Patterns & Code
#### Button (Variants & Sizes)
Uses `class-variance-authority` (CVA) for type-safe style management.
```tsx
import { Button } from "@/components/ui/button"

export default function Example() {
  return (
    <div className="flex gap-4">
      <Button variant="default" size="default">Primary</Button>
      <Button variant="destructive" size="sm">Delete</Button>
      <Button variant="outline" size="lg">Outline</Button>
      <Button variant="ghost" size="icon"><Settings /></Button>
    </div>
  )
}
```

#### Form (react-hook-form + zod)
The "gold standard" for type-safe form management in React.
```tsx
"use client"
import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import * as z from "zod"
import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form"
import { Input } from "@/components/ui/input"

const formSchema = z.object({
  email: z.string().email(),
})

export function LoginForm() {
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: { email: "" },
  })

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(console.log)} className="space-y-4">
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl><Input {...field} /></FormControl>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  )
}
```

#### DataTable (@tanstack/react-table)
A headless approach that separates logic from UI.
```tsx
"use client"
import { useReactTable, getCoreRowModel, flexRender } from "@tanstack/react-table"
import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@/components/ui/table"

export function DataTable({ columns, data }) {
  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() })
  return (
    <div className="rounded-md border">
      <Table>
        <TableHeader>
          {table.getHeaderGroups().map(hg => (
            <TableRow key={hg.id}>
              {hg.headers.map(h => <TableHead key={h.id}>{flexRender(h.column.columnDef.header, h.getContext())}</TableHead>)}
            </TableRow>
          ))}
        </TableHeader>
        <TableBody>
          {table.getRowModel().rows.map(row => (
            <TableRow key={row.id}>
              {row.getVisibleCells().map(c => <TableCell key={c.id}>{flexRender(c.column.columnDef.cell, c.getContext())}</TableCell>)}
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </div>
  )
}
```

### 4. ADVANCED PATTERNS
*   **Command Palette:** Use `cmdk` via the `Command` component to create a global search interface (⌘K).
*   **Charts:** Shadcn's chart implementation uses `Recharts` with CSS variables for dynamic coloring that automatically respects dark mode.
*   **Responsive Sidebar:** The modern `Sidebar` component uses `SidebarProvider` and `SidebarTrigger`, providing a collapsible desktop sidebar that automatically transforms into a `Sheet` (drawer) on mobile.

### 5. CUSTOMIZATION & BEST PRACTICES
*   **CVA (Class Variance Authority):** Always extend existing components or create new ones using `cva` to maintain consistency and type safety.
*   **Composition over Configuration:** Avoid props like `isLarge` or `hasBorder`. Instead, compose primitives (e.g., `<Card className="p-8 border-2">`).
*   **Accessibility:** shadcn/ui is built on **Radix UI**, which handles WAI-ARIA compliance (focus management, keyboard navigation, screen readers) out of the box.
*   **Server vs Client Components:** Keep your UI primitives (Button, Input, etc.) as "Client Components" (`'use client'`) if they require interactivity, but use them within "Server Components" for initial data fetching and better SEO.

I've added this reference to your knowledge graph as: **Mastering shadcn/ui & Tailwind CSS** in **Web Development** — this includes the full configuration, HSL theming system, and implementation patterns for Forms and DataTables.