# Prototyper UI Development Guide

Composable, design-first React component library built on **@base-ui/react** primitives and **Tailwind CSS v4**. Copy-paste distribution (like shadcn/ui), OKLCH color system, CVA variants, compound components.

**CRITICAL: This library uses `@base-ui/react`, NOT `@radix-ui/react`.** Base UI is the official successor to Radix, maintained by the MUI team. Do NOT import from Radix packages. Do NOT assume shadcn/ui patterns work identically — always fetch docs first.

### Dependencies

```bash
pnpm add @base-ui/react class-variance-authority clsx tailwind-merge lucide-react
```

### Project Structure

```
your-app/
  components/ui/         <- component source files (copy-paste)
  lib/utils.ts           <- cn() utility (clsx + tailwind-merge)
  prototyper-tokens.css  <- design tokens
  app/globals.css        <- @import "tailwindcss"; @import "./prototyper-tokens.css";
```

### Required Setup

1. **Tailwind CSS v4** with `@tailwindcss/postcss`
2. **`lib/utils.ts`** exporting `cn()`:
   ```ts
   import { clsx, type ClassValue } from "clsx";
   import { twMerge } from "tailwind-merge";
   export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs));
   }
   ```
3. **`prototyper-tokens.css`** imported in globals.css (run `node scripts/theme.mjs` to get it)
4. **`next-themes`** for dark mode (`.dark` class strategy)

### Hello World — Button

```tsx
import { Button } from "@/components/ui/button";

export default function HelloWorld() {
  return (
    <div className="flex gap-2">
      <Button>Default</Button>
      <Button variant="destructive" size="sm">
        Delete
      </Button>
      <Button variant="outline" isPending>
        Loading...
      </Button>
    </div>
  );
}
```

---

## 2. Component Selection Guide

### What are you building?

```
What are you building?
├── A clickable action?
│   ├── Standard button ──────────────── Button (6 variants, 9 sizes)
│   ├── On/off toggle button ─────────── Toggle (2 variants)
│   └── Group of related actions ─────── Toolbar (keyboard nav)
│
├── A form input?
│   ├── Free text ────────────────────── TextField (Input, TextArea)
│   ├── Number with +/- ──────────────── NumberField (8 exports)
│   ├── Pick one from a list ─────────── Select (dropdown) or RadioGroup (inline)
│   ├── Pick from filtered list ──────── Combobox (autocomplete, 24 exports)
│   ├── Yes/no toggle ────────────────── Checkbox (animated) or Switch (3 sizes)
│   ├── Value in a range ─────────────── Slider (compound, 6 exports)
│   └── Need label/description/error? ── Wrap ANY input with Field
│
├── An overlay / popup?
│   ├── Modal with actions ───────────── Dialog
│   ├── Slide-in panel ───────────────── Dialog (with side= prop — no separate Sheet)
│   ├── Info popup on click ──────────── Popover
│   ├── Quick hint on hover ──────────── Tooltip
│   └── Action list on click ─────────── Menu (DropdownMenu)
│
├── Showing progress / status?
│   ├── Task completion ──────────────── Progress (label + value)
│   └── Value in known range ─────────── Meter (color-coded gauge)
│
└── Content navigation? ──────────────── Tabs (horizontal or vertical)
```

### Compound vs Simple

| Type                        | Components                                                                                                                                  | Exports |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Simple** (1-2 exports)    | Button, Toggle, RadioGroup                                                                                                                  | 2 each  |
| **Compound** (3-10 exports) | Checkbox (3), Tabs (5), Switch (5), Popover (6), Slider (6), Toolbar (6), Meter (7), Progress (7), NumberField (9), Field (10), Dialog (10) | 3-10    |
| **Large compound** (11+)    | Select (11), Menu (15), Combobox (24)                                                                                                       | 11-24   |

---

## 3. Copy-Paste Patterns

These six patterns cover ~95% of use cases. Copy them directly.

### Pattern A: Simple Action (Button)

```tsx
import { Button } from "@/components/ui/button"

// Basic variants
<Button variant="default">Primary</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Cancel</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Sizes: xs, sm, default, lg, icon-xs, icon-sm, icon, icon-lg
<Button size="sm">Small</Button>
<Button size="icon"><SearchIcon /></Button>

// Loading state — disables interaction, keeps visual
<Button isPending>Saving...</Button>

// Render as link — render= replaces asChild from Radix
<Button render={<a href="/about" />}>About</Button>
```

**Key API difference from shadcn:** `render=` prop replaces Radix's `asChild`. 

…