Prototyper UI

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

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():

   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

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

3. Copy-Paste Patterns

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

Pattern A: Simple Action (Button)

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. Pass a JSX element, and Base UI merges the props onto it. When using render= on Button, the nativeButton prop is automatically handled internally.

Pattern B: Form Field (TextField + Field)

import { Field, FieldLabel, FieldDescription, FieldError } from "@/components/ui/field"
import { Input } from "@/components/ui/textfield"

// Field wraps ANY input with label, description, error
<Field>
  <FieldLabel>Email</FieldLabel>
  <FieldDescription>We'll never share your email.</FieldDescription>
  <Input placeholder="you@example.com" />
  <FieldError>Please enter a valid email address.</FieldError>
</Field>

// With validation (invalid prop on Field)
<Field invalid={!!errors.email}>
  <FieldLabel>Email</FieldLabel>
  <Input type="email" required />
  <FieldError>{errors.email}</FieldError>
</Field>

// TextArea variant
import { TextArea } from "@/components/ui/textfield"

<Field>
  <FieldLabel>Message</FieldLabel>
  <TextArea rows={4} placeholder="Your message..." />
</Field>

Field is a universal wrapper. Use it around TextField, NumberField, Select, Combobox, Checkbox, Switch, RadioGroup — any form input that needs a label, description, or error message.

Pattern C: Positioned Overlay (Popover)

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeader,
  PopoverTitle,
  PopoverDescription,
} from "@/components/ui/popover";
import { Button } from "@/components/ui/button";

<Popover>
  <PopoverTrigger render={<Button variant="outline" />}>
    Open Popover
  </PopoverTrigger>
  <PopoverContent side="bottom" align="center" sideOffset={4}>
    <PopoverHeader>
      <PopoverTitle>Settings</PopoverTitle>
      <PopoverDescription>Configure your preferences.</PopoverDescription>
    </PopoverHeader>
    {/* your content */}
  </PopoverContent>
</Popover>;

Positioning props (side, sideOffset, align, alignOffset) live on the Content component. Internally, they're forwarded to Base UI's Positioner layer — you don't need to think about Portal/Positioner/Popup yourself.

This same pattern applies to Tooltip, Menu, Select, and Combobox — all positioned overlays use side/align/offset. For Menu specifically:

import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuShortcut,
} from "@/components/ui/menu";

<DropdownMenu>
  <DropdownMenuTrigger render={<Button variant="outline" />}>
    Actions
  </DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>
      Edit <DropdownMenuShortcut>Cmd+E</DropdownMenuShortcut>
    </DropdownMenuItem>
    <DropdownMenuItem>Duplicate</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>;

Pattern D: Compound Visual (Slider)

import {
  Slider, SliderControl, SliderTrack,
  SliderIndicator, SliderThumb, SliderOutput,
} from "@/components/ui/slider"

<Slider defaultValue={50} min={0} max={100}>
  <SliderOutput />
  <SliderControl>
    <SliderTrack>
      <SliderIndicator />
      <SliderThumb />
    </SliderTrack>
  </SliderControl>
</Slider>

// Multi-thumb range slider
<Slider defaultValue={[25, 75]}>
  <SliderControl>
    <SliderTrack>
      <SliderIndicator />
      <SliderThumb />  {/* automatically creates one per value */}
      <SliderThumb />
    </SliderTrack>
  </SliderControl>
</Slider>

Compound visual components have a strict nesting order. The sub-components must be nested correctly — they communicate via React context.

Pattern E: Selection Input (Select + Field)

import { Field, FieldLabel, FieldError } from "@/components/ui/field";
import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectGroup,
  SelectLabel,
  SelectItem,
  SelectSeparator,
} from "@/components/ui/select";

<Field>
  <FieldLabel>Country</FieldLabel>
  <Select>
    <SelectTrigger size="default">
      <SelectValue placeholder="Select a country" />
    </SelectTrigger>
    <SelectContent>
      <SelectGroup>
        <SelectLabel>North America</SelectLabel>
        <SelectItem value="us">United States</SelectItem>
        <SelectItem value="ca">Canada</SelectItem>
      </SelectGroup>
      <SelectSeparator />
      <SelectGroup>
        <SelectLabel>Europe</SelectLabel>
        <SelectItem value="uk">United Kingdom</SelectItem>
        <SelectItem value="de">Germany</SelectItem>
      </SelectGroup>
    </SelectContent>
  </Select>
  <FieldError>Please select a country.</FieldError>
</Field>;

Pattern F: Dialog & Sheet (Unified)

import {
  Dialog, DialogTrigger, DialogContent,
  DialogHeader, DialogTitle, DialogDescription,
  DialogFooter, DialogClose,
} from "@/components/ui/dialog"
import { Button } from "@/components/ui/button"

// Standard center dialog
<Dialog>
  <DialogTrigger render={<Button />}>Edit Profile</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Edit Profile</DialogTitle>
      <DialogDescription>Make changes to your profile.</DialogDescription>
    </DialogHeader>
    {/* form content */}
    <DialogFooter>
      <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose>
      <Button type="submit">Save</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

// Sheet variant — just add side= prop
<Dialog>
  <DialogTrigger render={<Button variant="outline" />}>Open Sheet</DialogTrigger>
  <DialogContent side="right">  {/* "top" | "bottom" | "left" | "right" */}
    <DialogHeader>
      <DialogTitle>Navigation</DialogTitle>
    </DialogHeader>
    {/* sheet content */}
  </DialogContent>
</Dialog>

There is no separate Sheet component. Dialog handles both center modals and side sheets via the side prop. When side is set, the dialog slides in from that edge. When omitted, it's a standard centered modal.

4. Design System Reference

Token Selection: "I need a background — which token?"

What kind of element needs a background?
├── The page itself ────────────────── bg-background
├── A card / raised surface ────────── bg-surface (or bg-card)
├── A nested surface ───────────────── bg-surface-secondary / bg-surface-tertiary
├── An overlay (popover/dialog/menu) ── bg-overlay
├── A form input ───────────────────── bg-field-background
├── A primary action ───────────────── bg-primary
├── A destructive action ───────────── bg-destructive
├── A hover state (interactive) ────── hover-only:hover:bg-accent
├── A selected/active state ────────── bg-accent
├── Muted / secondary text area ────── bg-muted
└── A subtle tint of primary ───────── bg-primary-soft

Color Format (OKLCH)

Tokens store raw OKLCH channels. Tailwind utilities are pre-registered via @theme:

/* Token definition */
--primary: 55% 0.24 264;              /* lightness chroma hue */

/* In Tailwind — just use the utility */
className="bg-primary text-primary-foreground"

/* In raw CSS — wrap with oklch() */
background: oklch(var(--primary));

Never use hsl(var(--primary)), hardcoded hex, or bg-[oklch(55%_0.24_264)].

Token Categories

Derived Colors (Auto-Generated)

Hover states use color-mix() — no manual darkening:

--primary-hover: color-mix(
  in oklab,
  oklch(var(--primary)) 90%,
  oklch(var(--primary-foreground)) 10%
);
--primary-soft: color-mix(in oklab, oklch(var(--primary)) 15%, transparent);

Use as: hover-only:hover:bg-primary-hover, bg-primary-soft.

Shadow Tiers

Dark Mode

Dark mode activates via .dark class (next-themes). Token values swap automatically — you never write dark:bg-* classes. Shadows for surface and field become none in dark mode (depth comes from tonal contrast instead). Overlay shadows get a subtle white border ring.

Easing Tokens

CSS Utilities

Custom Tailwind Variants

5. Component Architecture

Sub-component Patterns

Component File Header

Every component file follows this strict pattern:

"use client"; // Always first line

import * as React from "react"; // Only when needed
import { Component as ComponentPrimitive } from "@base-ui/react/component-name";
import { cva, type VariantProps } from "class-variance-authority";
import { SomeIcon } from "lucide-react"; // Icons

import { cn } from "@/lib/utils"; // Internal utilities last

Always use deep path Base UI imports (@base-ui/react/dialog), never barrel imports. Alias primitives with Primitive suffix to avoid naming conflicts with your wrapper components.

Props Type Conventions

Components extend Base UI primitive props + CVA VariantProps:

// Simple component
function Button({
  className, variant, size, isPending, render, ...props
}: ButtonPrimitive.Props & VariantProps<typeof buttonVariants> & {
  isPending?: boolean
}) { ... }

// Overlay content — merge Popup + Positioner positioning props
function PopoverContent({
  className, side = "bottom", sideOffset = 4, align = "center", ...props
}: PopoverPrimitive.Popup.Props &
  Pick<PopoverPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset">
) { ... }

The render= Prop (Base UI's asChild Replacement)

Base UI does not use Radix's asChild. Instead, it provides render= which takes a JSX element:

// Render trigger as a Button
<DialogTrigger render={<Button variant="outline" />}>
  Open Dialog
</DialogTrigger>

// Render close as a Button
<DialogClose render={<Button variant="ghost" />}>
  Cancel
</DialogClose>

// Render as a link
<Button render={<a href="/about" />}>About Us</Button>

Base UI merges all primitive props (event handlers, ARIA attributes, refs) onto your element. The render= prop can also accept a function render={(props) => <Custom {...props} />} but the JSX element form is preferred.

data-slot Convention

Every rendered element gets a data-slot attribute for CSS targeting:

<button data-slot="button" />
<div data-slot="dialog-header" />
<div data-slot="select-content" />

Pattern: root = component name (button), sub-components = {root}-{role} (dialog-header, select-item).

6. Styling & Customization

className Overrides

All components accept className. It's merged via cn() (tailwind-merge) — your classes win over defaults:

<Button className="w-full rounded-full">Full Width Pill</Button>

CSS Targeting via data-slot

Style components from parent CSS without prop drilling:

[data-slot="button"] {
  /* targets all buttons */
}
[data-slot="dialog-content"] {
  /* targets dialog panels */
}

Reusing CVA Variants

Use variant functions on non-component elements (e.g., making a link look like a button):

import { buttonVariants } from "@/components/ui/button";

<a href="/about" className={buttonVariants({ variant: "outline", size: "sm" })}>
  About
</a>;

Token Overrides

Override any design token in your globals.css:

:root {
  --primary: 60% 0.2 150; /* green primary instead of blue */
  --radius: 0.75rem; /* larger border radius */
}

Custom Tailwind Variants

// Only apply hover on devices that support it (prevents sticky hover on touch)
"hover-only:hover:bg-accent";

// Only animate for users who haven't requested reduced motion
"motion-safe:active:scale-[0.97]";

// Disable animation for users who prefer reduced motion
"motion-reduce:transition-none";
"motion-reduce:animate-none";

Animation Conventions

Prototyper UI uses CSS-first animation — no framer-motion dependency.

• State transitions: transition-[color,background-color,border-color,box-shadow,opacity] duration-150 ease-smooth + motion-reduce:transition-none
• Press feedback: motion-safe:active:scale-[0.97] (buttons), scale-[0.98] (menu items), scale-[0.95] (small controls like checkbox)
• Overlay enter/exit: data-open:animate-in / data-closed:animate-out with fade-in/zoom-in-95/directional slides
• Signature easing: --ease-out-fluid (cubic-bezier(0.32, 0.72, 0, 1))
• Split timing: colors 100-150ms, transforms 250ms, enter > exit (300ms→200ms)
• Never: transition-all, bare active:scale-*, animations without motion-reduce: alternative

For detailed animation patterns, invoke the /animate-ui skill.

7. Accessibility Checklist

Every component should address:

• Motion reduction: Add motion-reduce:transition-none on elements with transition-* classes. Add motion-reduce:animate-none on elements with animate-in/animate-out.
• Touch safety: Use hover-only:hover: instead of bare hover: for background/color changes. Add no-highlight utility on interactive elements.
• Press feedback: Always prefix with motion-safe: — never bare active:scale-*.
• Focus management: Use focus-visible:focus-ring for buttons/toggles/links. Use focus-within:focus-field-ring for form field groups.
• Keyboard navigation: Handled by Base UI automatically — Arrow keys for RadioGroup, Tabs, Menu, Toolbar, Select. Escape to close overlays. Enter/Space to activate.

8. Common Mistakes

Import Mistakes

Styling Mistakes

Architecture Mistakes

Component-Specific Mistakes

9. Component Reference

10. Documentation Access

Scripts

# List all available components
node scripts/list.mjs

# Get component documentation (full docs + source + examples)
node scripts/docs.mjs button
node scripts/docs.mjs button dialog select    # multiple at once

# Get component source code only
node scripts/source.mjs button

# Get design tokens CSS
node scripts/theme.mjs

Direct URLs

MCP Server

claude mcp add prototyper-ui -- npx -y @prototyperco/mcp@latest

Tools: list_components, get_component_docs, get_component_source, get_theme, search_docs.

Always Fetch First

Before implementing any component, always fetch its documentation using the scripts or URLs above. Do not assume Radix/shadcn patterns work identically. Component APIs, data attributes, and animation conventions all differ from what you might expect.