# @quietbuildlab/ui — Full API Reference > Themed shadcn/ui component library. Ships six ready-made themes (Manuscript, Midnight, > Slate, Sunset, Ocean, Mono), each light + dark, and 31 components on Radix UI + Tailwind v4. > Pick a theme with one CSS import or switch at runtime via `data-theme`. Re-themable further > via CSS variable overrides. --- ## Install ```bash npm install @quietbuildlab/ui ``` Requires Tailwind CSS v4 and React 18 or 19. In the consumer app's main CSS file, pick ONE of these three setups. ### A) Single preset (most common) ```css @import "tailwindcss"; @import "@quietbuildlab/ui/themes/midnight.css"; /* manuscript | midnight | slate | sunset | ocean | mono */ @source "../node_modules/@quietbuildlab/ui/dist"; ``` ### B) Backward-compat (Manuscript only) ```css @import "tailwindcss"; @import "@quietbuildlab/ui/theme.css"; @source "../node_modules/@quietbuildlab/ui/dist"; ``` ### C) Runtime theme switching ```css @import "tailwindcss"; @import "@quietbuildlab/ui/themes.css"; @source "../node_modules/@quietbuildlab/ui/dist"; ``` Then set the theme on ``: ```ts document.documentElement.dataset.theme = "ocean" // any preset name ``` Default if no `data-theme` is set: Manuscript. Order matters in all setups: tailwind first, then theme/themes CSS, then @source so Tailwind scans the package's built JS for utility classes. ## Themes shipped | Theme | Vibe | Accent | Radius | Type | |---|---|---|---|---| | Manuscript | Warm paper, editorial | Forest green | 4px | Lora + Inter | | Midnight | Cool, focused | Indigo | 6px | Inter | | Slate | Neutral, corporate | Slate-blue | 4px | Inter | | Sunset | Warm, friendly | Coral | 10px | Inter | | Ocean | Calm SaaS | Teal | 6px | Inter | | Mono | Brutalist B/W | Black/white | 0px | Inter + mono | ## Importing All components are named exports from the package root: ```tsx import { Button, Card, CardHeader, Dialog, DialogTrigger, DialogContent, Sheet, SheetTrigger, SheetContent, AlertDialog, AlertDialogTrigger, AlertDialogContent, } from '@quietbuildlab/ui' ``` Do NOT deep-import (no `from '@quietbuildlab/ui/dist/...'`). ## Dark mode Toggle a `dark` class on ``: ```ts document.documentElement.classList.toggle('dark', isDark) ``` In runtime-switching mode, typically toggle both: ```ts document.documentElement.dataset.theme = "midnight" document.documentElement.classList.toggle('dark', isDark) ``` The library does NOT ship a theme-provider — apps own the toggle. ## Theming Override CSS variables AFTER the preset import: ```css :root { --primary: oklch(0.40 0.10 250); --ring: oklch(0.40 0.10 250); --radius: 0.5rem; } .dark { --primary: oklch(0.65 0.10 250); --ring: oklch(0.65 0.10 250); } ``` Token groups: surfaces (background, foreground, card, popover), accent (primary, ring), quiet UI (secondary, muted, accent), form (border, input), status (destructive), shape (radius), type (font-sans, font-serif), plus chart-1..5 and sidebar-*. --- ## Group: Foundations ### Button Clickable action element. Built on a native ` // Destructive with size // Polymorphic — renders as with button styling // Icon-only ``` ### Badge Small inline label for status, categories, or counts. ```tsx interface BadgeProps extends React.ComponentProps<"span"> { variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link" asChild?: boolean } ``` ```tsx import { Badge } from '@quietbuildlab/ui' New Error Draft ``` ### Input Single-line text input. Accepts all standard `` props. ```tsx // Props: React.ComponentProps<"input"> — all native input attributes pass through ``` ```tsx import { Input, Label } from '@quietbuildlab/ui'

``` ### Textarea Multi-line text input. Accepts all standard `

` props.

```tsx
import { Textarea, Label } from '@quietbuildlab/ui'

<div className="flex flex-col gap-1.5">
  <Label htmlFor="bio">Bio</Label>
  <Textarea id="bio" rows={4} placeholder="Tell us about yourself" />
</div>
```

### Label

Styled `<label>` element. Pair with `htmlFor` to associate with a form control.

```tsx
import { Label, Input } from '@quietbuildlab/ui'

<Label htmlFor="name">Full name</Label>
<Input id="name" />
```

---

## Group: Surfaces

### Card

Rounded surface container. Compose with sub-components for structured layouts.

Sub-components: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `CardAction`

All sub-components accept `React.ComponentProps<"div">` (className + standard div attrs).

`CardAction` renders in the top-right corner of `CardHeader` when present (uses CSS grid).

```tsx
import {
  Card, CardHeader, CardTitle, CardDescription,
  CardContent, CardFooter, CardAction, Button
} from '@quietbuildlab/ui'

<Card className="max-w-sm">
  <CardHeader>
    <CardTitle>Workspace</CardTitle>
    <CardDescription>Your active projects</CardDescription>
    <CardAction>
      <Button variant="ghost" size="icon-sm"><PlusIcon /></Button>
    </CardAction>
  </CardHeader>
  <CardContent>
    <p className="text-sm text-muted-foreground">3 projects active</p>
  </CardContent>
  <CardFooter>
    <Button variant="outline" size="sm">View all</Button>
  </CardFooter>
</Card>
```

---

## Group: Forms

### Checkbox

Binary toggle. Controlled via `checked` + `onCheckedChange`, or uncontrolled.

```tsx
// Props: React.ComponentProps<typeof CheckboxPrimitive.Root>
// Key props: checked, defaultChecked, onCheckedChange, disabled, required, name, value
```

```tsx
import { Checkbox, Label } from '@quietbuildlab/ui'

<div className="flex items-center gap-2">
  <Checkbox id="terms" onCheckedChange={(checked) => console.log(checked)} />
  <Label htmlFor="terms">Accept terms</Label>
</div>
```

### Switch

On/off toggle. Same controlled pattern as Checkbox.

```tsx
// Props: React.ComponentProps<typeof SwitchPrimitive.Root>
// Key props: checked, defaultChecked, onCheckedChange, disabled, name, value
```

```tsx
import { Switch, Label } from '@quietbuildlab/ui'

const [enabled, setEnabled] = useState(false)

<div className="flex items-center gap-2">
  <Switch id="notifications" checked={enabled} onCheckedChange={setEnabled} />
  <Label htmlFor="notifications">Email notifications</Label>
</div>
```

### RadioGroup + RadioGroupItem

Single-selection group. Wrap `RadioGroupItem` + `Label` pairs inside `RadioGroup`.

```tsx
// RadioGroup props: value, defaultValue, onValueChange, orientation, disabled, required, name
// RadioGroupItem props: value (required), disabled, required
```

```tsx
import { RadioGroup, RadioGroupItem, Label } from '@quietbuildlab/ui'

<RadioGroup defaultValue="monthly" onValueChange={(v) => console.log(v)}>
  <div className="flex items-center gap-2">
    <RadioGroupItem id="monthly" value="monthly" />
    <Label htmlFor="monthly">Monthly</Label>
  </div>
  <div className="flex items-center gap-2">
    <RadioGroupItem id="annual" value="annual" />
    <Label htmlFor="annual">Annual</Label>
  </div>
</RadioGroup>
```

### Select

Combobox / dropdown selector. Portals to document.body.

Sub-components: `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`

```tsx
// Select props: value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, disabled, required, name
// SelectTrigger extra prop: size?: "sm" | "default"
// SelectContent extra props: position?: "item-aligned" | "popper", align?: "start" | "center" | "end"
```

```tsx
import {
  Select, SelectTrigger, SelectValue,
  SelectContent, SelectItem, SelectGroup, SelectLabel
} from '@quietbuildlab/ui'

<Select onValueChange={(v) => console.log(v)}>
  <SelectTrigger className="w-[200px]">
    <SelectValue placeholder="Pick a plan" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>Plans</SelectLabel>
      <SelectItem value="free">Free</SelectItem>
      <SelectItem value="pro">Pro</SelectItem>
      <SelectItem value="enterprise">Enterprise</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>
```

---

## Group: Overlays

### Dialog

Modal dialog. Portals to document.body with animated overlay.

Sub-components: `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `DialogClose`

```tsx
// Dialog props (Radix Root): open, defaultOpen, onOpenChange, modal
// DialogContent extra prop: showCloseButton?: boolean (default true)
// DialogFooter extra prop: showCloseButton?: boolean (default false) — adds a styled Close button
```

```tsx
import {
  Dialog, DialogTrigger, DialogContent, DialogHeader,
  DialogTitle, DialogDescription, DialogFooter, Button
} from '@quietbuildlab/ui'

<Dialog>
  <DialogTrigger asChild>
    <Button variant="outline">Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Confirm deletion</DialogTitle>
      <DialogDescription>This action cannot be undone.</DialogDescription>
    </DialogHeader>
    <DialogFooter showCloseButton>
      <Button variant="destructive">Delete</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

### DropdownMenu

Contextual menu. Portals to document.body.

Sub-components: `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuSeparator`, `DropdownMenuLabel`

```tsx
// DropdownMenu props (Radix Root): open, defaultOpen, onOpenChange, dir, modal
// DropdownMenuContent props: side, align, sideOffset, alignOffset, etc. (Radix Content)
// DropdownMenuItem props: onSelect, disabled, textValue, inset
```

```tsx
import {
  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
  DropdownMenuItem, DropdownMenuSeparator, DropdownMenuLabel, Button
} from '@quietbuildlab/ui'

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Actions</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuLabel>Account</DropdownMenuLabel>
    <DropdownMenuItem>Profile</DropdownMenuItem>
    <DropdownMenuItem>Settings</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem className="text-destructive">Sign out</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

### Tooltip

Hover/focus tooltip. Portals to document.body. Requires `<TooltipProvider>` in the ancestor tree.

```tsx
// TooltipProvider props: delayDuration (default 0), skipDelayDuration, disableHoverableContent
// Tooltip props: open, defaultOpen, onOpenChange, delayDuration, disableHoverableContent
// TooltipContent props: side, align, sideOffset (default 0), alignOffset, avoidCollisions
```

```tsx
import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent, Button } from '@quietbuildlab/ui'

// Mount once at app root:
<TooltipProvider>
  <App />
</TooltipProvider>

// Then wherever you need a tooltip:
<Tooltip>
  <TooltipTrigger asChild>
    <Button variant="ghost" size="icon" aria-label="Copy">
      <CopyIcon />
    </Button>
  </TooltipTrigger>
  <TooltipContent>Copy to clipboard</TooltipContent>
</Tooltip>
```

---

## Group: Feedback

### Skeleton

Loading placeholder. No specific props beyond `className` for sizing.

```tsx
import { Skeleton } from '@quietbuildlab/ui'

// Match the shape of the content it replaces via className
<Skeleton className="h-4 w-48" />
<Skeleton className="h-10 w-10 rounded-full" />
```

### Progress

Horizontal progress bar. `value` is 0–100.

```tsx
// Props: React.ComponentProps<typeof ProgressPrimitive.Root>
// Key props: value (number 0–100), max, getValueLabel
```

```tsx
import { Progress } from '@quietbuildlab/ui'

const [progress, setProgress] = useState(0)

<Progress value={progress} className="w-64" />
```

### Toaster

Toast notification host. Mount once at the app root. Trigger toasts with `toast()` from sonner.

Internally uses `next-themes` for color-mode detection. Without a `<ThemeProvider attribute="class">`,
it falls back to OS `prefers-color-scheme` rather than tracking the `.dark` class on `<html>`.

```tsx
import { Toaster } from '@quietbuildlab/ui'
import { toast } from 'sonner'

// In your root layout or _app:
<Toaster />

// Anywhere in the app:
toast('File saved')
toast.success('Uploaded successfully')
toast.error('Upload failed', { description: 'Check your connection.' })
toast.loading('Saving...')
```

### Separator

Horizontal or vertical visual divider.

```tsx
// Props: React.ComponentProps<typeof SeparatorPrimitive.Root>
// Key props: orientation?: "horizontal" | "vertical" (default "horizontal"), decorative
```

```tsx
import { Separator } from '@quietbuildlab/ui'

<Separator />
<Separator orientation="vertical" className="h-6" />
```

---

## Group: Data

### Table

Semantic HTML table primitives — styling only, no data logic.

Sub-components: `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption`

All accept `React.ComponentProps` of their underlying HTML element.

```tsx
import {
  Table, TableHeader, TableBody, TableHead,
  TableRow, TableCell, TableCaption
} from '@quietbuildlab/ui'

<Table>
  <TableCaption>Recent invoices</TableCaption>
  <TableHeader>
    <TableRow>
      <TableHead>Invoice</TableHead>
      <TableHead>Amount</TableHead>
      <TableHead>Status</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>INV-001</TableCell>
      <TableCell>$120.00</TableCell>
      <TableCell>Paid</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

### Pagination

Numbered pagination UI primitives (no logic — wire up hrefs or onClick yourself).

Sub-components: `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis`

```tsx
// PaginationLink props: isActive?: boolean, size (Button size), + <a> attrs
```

```tsx
import {
  Pagination, PaginationContent, PaginationItem,
  PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis
} from '@quietbuildlab/ui'

<Pagination>
  <PaginationContent>
    <PaginationItem><PaginationPrevious href="?page=1" /></PaginationItem>
    <PaginationItem><PaginationLink href="?page=1" isActive>1</PaginationLink></PaginationItem>
    <PaginationItem><PaginationLink href="?page=2">2</PaginationLink></PaginationItem>
    <PaginationItem><PaginationEllipsis /></PaginationItem>
    <PaginationItem><PaginationNext href="?page=2" /></PaginationItem>
  </PaginationContent>
</Pagination>
```

### DataTable

TanStack Table-powered data grid with built-in pagination controls, rows-per-page selector,
empty state, and loading state.

```tsx
interface DataTableProps<TData, TValue> {
  columns: ColumnDef<TData, TValue>[]   // from @tanstack/react-table
  data: TData[]                          // full dataset (client) or current page slice (server)
  pageSize?: number                      // initial/controlled page size (default 10)
  pageSizeOptions?: number[]             // dropdown options (default [10, 25, 50, 100])
  pageIndex?: number                     // controlled page index (server-side mode)
  pageCount?: number                     // total pages — presence flips to server-side mode
  onPaginationChange?: (state: PaginationState) => void
  loading?: boolean                      // dims table and disables controls
  emptyMessage?: React.ReactNode         // default "No results."
  className?: string
}
```

Column types come from `@tanstack/react-table` (a transitive dep):

```tsx
import type { ColumnDef } from '@tanstack/react-table'
```

---

## Group: Layout

### Tabs

Tabbed content switcher. Supports horizontal (default) and vertical orientations.

Sub-components: `TabsList`, `TabsTrigger`, `TabsContent`

```tsx
// Tabs props: value, defaultValue, onValueChange, orientation ("horizontal" | "vertical")
// TabsList extra prop: variant?: "default" | "line"
```

```tsx
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@quietbuildlab/ui'

<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="activity">Activity</TabsTrigger>
    <TabsTrigger value="settings">Settings</TabsTrigger>
  </TabsList>
  <TabsContent value="overview"><p>Overview content</p></TabsContent>
  <TabsContent value="activity"><p>Activity feed</p></TabsContent>
  <TabsContent value="settings"><p>Settings form</p></TabsContent>
</Tabs>
```

Line variant (underline style):

```tsx
<Tabs defaultValue="all">
  <TabsList variant="line">
    <TabsTrigger value="all">All</TabsTrigger>
    <TabsTrigger value="active">Active</TabsTrigger>
  </TabsList>
  <TabsContent value="all">...</TabsContent>
  <TabsContent value="active">...</TabsContent>
</Tabs>
```

---

## DataTable in depth

### Client-side (default)

Pass the full dataset. The table handles pagination internally.

```tsx
import { DataTable } from '@quietbuildlab/ui'
import type { ColumnDef } from '@tanstack/react-table'

type User = { id: string; name: string; email: string; role: string }

const columns: ColumnDef<User>[] = [
  { accessorKey: 'name',  header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'role',  header: 'Role' },
]

const allUsers: User[] = [...] // full array

export function UsersTable() {
  return <DataTable columns={columns} data={allUsers} pageSize={25} />
}
```

### Server-side

Presence of `pageCount` flips the mode. The parent owns `pageIndex`/`pageSize`, fetches the
right slice, and passes `loading` so the table dims controls during fetch.

```tsx
import { useState } from 'react'
import { DataTable } from '@quietbuildlab/ui'
import type { ColumnDef } from '@tanstack/react-table'
import type { PaginationState } from '@tanstack/react-table'

type Order = { id: string; product: string; amount: number; status: string }

const columns: ColumnDef<Order>[] = [
  { accessorKey: 'product', header: 'Product' },
  { accessorKey: 'amount',  header: 'Amount' },
  { accessorKey: 'status',  header: 'Status' },
]

export function OrdersTable() {
  const [pagination, setPagination] = useState<PaginationState>({ pageIndex: 0, pageSize: 10 })
  const [isLoading, setIsLoading] = useState(false)
  const [pageRows, setPageRows] = useState<Order[]>([])
  const [pageCount, setPageCount] = useState(0)

async function handlePaginationChange(next: PaginationState) {
    setPagination(next)
    setIsLoading(true)
    const res = await fetchOrders(next.pageIndex, next.pageSize)
    setPageRows(res.rows)
    setPageCount(res.pageCount)
    setIsLoading(false)
  }

return (
    <DataTable
      columns={columns}
      data={pageRows}
      pageIndex={pagination.pageIndex}
      pageSize={pagination.pageSize}
      pageCount={pageCount}
      onPaginationChange={handlePaginationChange}
      loading={isLoading}
    />
  )
}
```

---

## Group: Feedback & Overlays (new in v0.6)

### Alert

Inline non-blocking status banner. Use for info / warning / success / error messages that
don't require user action. For blocking yes/no confirmations, use `AlertDialog` instead.

```tsx
interface AlertProps extends React.ComponentProps<"div"> {
  variant?: "default" | "destructive"
}
```

Subcomponents: `AlertTitle`, `AlertDescription`. A leading `<svg>` icon is auto-styled.

```tsx
<Alert>
  <InfoIcon />
  <AlertTitle>Heads up</AlertTitle>
  <AlertDescription>You can dismiss this anytime.</AlertDescription>
</Alert>

<Alert variant="destructive">
  <TriangleAlertIcon />
  <AlertTitle>Connection failed</AlertTitle>
  <AlertDescription>Check your network and try again.</AlertDescription>
</Alert>
```

### AlertDialog

Blocking yes/no confirmation modal. Use for destructive actions (delete, sign-out, discard).
Built on Radix AlertDialog. Always include both `AlertDialogAction` and `AlertDialogCancel`.

`AlertDialogAction` has destructive-button styling by default. `AlertDialogCancel` has
outline-button styling.

```tsx
<AlertDialog>
  <AlertDialogTrigger asChild><Button variant="destructive">Delete</Button></AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this project?</AlertDialogTitle>
      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>
```

### Sheet

Slide-in panel anchored to an edge. Built on Radix Dialog so it traps focus.
Side prop on `SheetContent`: `"top" | "right" (default) | "bottom" | "left"`.

```tsx
<Sheet>
  <SheetTrigger asChild><Button>Open menu</Button></SheetTrigger>
  <SheetContent side="left">
    <SheetHeader>
      <SheetTitle>Menu</SheetTitle>
      <SheetDescription>Navigate the app.</SheetDescription>
    </SheetHeader>
    <nav className="grid gap-2 p-4">…</nav>
  </SheetContent>
</Sheet>
```

## Group: Disclosure & Identity (new in v0.6)

### Accordion

Vertical stack of collapsible sections. `type="single"` allows one open at a time (pass
`collapsible` to allow zero too); `type="multiple"` allows several.

```tsx
<Accordion type="single" collapsible>
  <AccordionItem value="a">
    <AccordionTrigger>How does billing work?</AccordionTrigger>
    <AccordionContent>Monthly, billed in advance.</AccordionContent>
  </AccordionItem>
  <AccordionItem value="b">
    <AccordionTrigger>Can I cancel?</AccordionTrigger>
    <AccordionContent>Yes, anytime.</AccordionContent>
  </AccordionItem>
</Accordion>
```

### Avatar

User image with text fallback. Default size 32px; change via `className` (`size-6`,
`size-10`, `size-14`, etc.). The fallback renders if the image fails or is loading.

```tsx
<Avatar>
  <AvatarImage src="https://example.com/u.jpg" alt="Ada Lovelace" />
  <AvatarFallback>AL</AvatarFallback>
</Avatar>

<Avatar className="size-10">
  <AvatarFallback>MW</AvatarFallback>
</Avatar>
```

Group avatars with negative spacing:

```tsx
<div className="flex -space-x-2">
  <Avatar className="border-2 border-background"><AvatarFallback>A</AvatarFallback></Avatar>
  <Avatar className="border-2 border-background"><AvatarFallback>B</AvatarFallback></Avatar>
  <Avatar className="border-2 border-background"><AvatarFallback>+3</AvatarFallback></Avatar>
</div>
```

## Group: Inputs (new in v0.6)

### Slider

Range input. Pass `defaultValue={[50]}` (uncontrolled) or `value={[v]} onValueChange={setV}`
(controlled). Two-element arrays render a range slider with two thumbs.

```tsx
interface SliderProps extends React.ComponentProps<typeof SliderPrimitive.Root> {
  // forwards everything to Radix Slider; useful props:
  // min, max, step, defaultValue, value, onValueChange, disabled, orientation
}
```

```tsx
<Slider defaultValue={[50]} min={0} max={100} step={1} />
<Slider defaultValue={[20, 80]} min={0} max={100} step={5} />

// Controlled
const [v, setV] = useState([35])
<Slider value={v} onValueChange={setV} min={0} max={100} />
```

---

## Composition rules

1. **Tooltip needs `<TooltipProvider>` somewhere up the tree.** Wrap the app once at the root.
2. **Dialog / AlertDialog / Sheet / DropdownMenu / Tooltip / Select content portals to `document.body`.** They render
   outside their parent's DOM tree. Pass `className` to `*Content` for styling.
3. **Compound components stay together.** `<Card>` is a styled div on its own, but `<CardHeader>`
   etc. must be children of `<Card>`. Same for `<Tabs>`, `<Dialog>`, `<AlertDialog>`, `<Sheet>`,
   `<Accordion>`, `<DropdownMenu>`, `<Select>`, `<RadioGroup>`.
4. **Use semantic tokens, not raw colors.** `bg-destructive`, `text-foreground`, `border-input`
   retheme automatically. `bg-red-500` does not.
5. **`asChild` (Radix Slot) for polymorphism.** `<Button asChild><Link to="/foo">Go</Link></Button>`
   renders the link with button styling. Don't nest `<a>`/`<Link>` inside `<button>`.

---

## Common pitfalls

- **Don't use raw color utilities** (`bg-red-500`) — defeats the theme. Use semantic tokens.
- **Don't import from `dist/`.** Use the package root.
- **Don't add a `<ThemeProvider>` thinking the library needs one.** Just toggle `.dark` on
  `<html>` (and optionally `data-theme` in runtime-switching mode). Exception: if you want
  `Toaster` to track the class, then yes — `next-themes` ThemeProvider helps.
- **Don't import more than one theme entrypoint.** `theme.css`, `themes/<name>.css`, and
  `themes.css` all define `:root` tokens — importing two will cause the second to win, possibly
  with surprising results. Pick one mode and stick with it.
- **Don't expect SSR-specific hydration helpers** — components are client-side React; the
  `'use client'` directive is in the components for Next.js App Router compatibility.
- **Tailwind utility overrides via `className` work via `tailwind-merge`** — `cn('px-2', 'px-4')`
  resolves to `px-4`. But for tokens, override the CSS variable instead of fighting class
  specificity.
- **`onPaginationChange` in server-side DataTable receives the full next `PaginationState`**
  (both `pageIndex` and `pageSize`). Handle both — the user may change either.

---

## More

- Live Storybook: https://quiet-build.github.io/ui/
- llms.txt (concise index): https://quiet-build.github.io/ui/llms.txt
- AGENTS.md: https://github.com/quiet-build/ui/blob/main/AGENTS.md
- THEMING.md: https://github.com/quiet-build/ui/blob/main/THEMING.md
- Source: https://github.com/quiet-build/ui