Installation

Requirements

Prototyper UI components require the following:

React 19+
Next.js 15+
Tailwind CSS v4
Base UI (@base-ui/react)

Quick Start

Option A: Prototyper UI CLI (Recommended)

Set up your project and add components with the Prototyper UI CLI:

bunx @prototyperco/cli init       # tokens, utils, base styles
bunx @prototyperco/cli add button # add components

Run add without arguments for an interactive component picker, or install everything at once:

bunx @prototyperco/cli add --all

Machine Mode Package (Installable Runtime)

To scaffold URL-driven machine mode in a Next.js App Router project:

bunx @prototyperco/cli machine-mode init

See the full guide at Machine Mode Package.

Option B: shadcn CLI

If you already use shadcn, install any component directly from the registry:

npx shadcn@latest add https://prototyper-ui.com/r/button.json

This copies the component source into your project (typically components/ui/button.tsx) along with any required dependencies.

npx shadcn@latest add https://prototyper-ui.com/r/button.json https://prototyper-ui.com/r/dialog.json https://prototyper-ui.com/r/select.json

Keeping Up to Date

bunx @prototyperco/cli update    # check for component updates
bunx @prototyperco/cli doctor    # verify project setup

Manual Setup

If you prefer to set up manually or need to understand each step, follow this guide.

Install Dependencies

npm install @base-ui/react class-variance-authority clsx tailwind-merge

Add the `cn` Utility

Create lib/utils.ts in your project:

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Set Up CSS Tokens

Add the design tokens to your globals.css. The token system has four layers:

Theme registration — maps CSS custom properties to Tailwind utilities:

@theme {
  /* Radius scale */
  --radius-xl: calc(var(--radius) + 4px);
  --radius-lg: var(--radius);
  --radius-md: calc(var(--radius) - 2px);
  --radius-sm: calc(var(--radius) - 4px);

  /* Colors — each generates bg-*, text-*, border-* utilities */
  --color-background: oklch(var(--background));
  --color-foreground: oklch(var(--foreground));
  --color-primary: oklch(var(--primary));
  --color-primary-foreground: oklch(var(--primary-foreground));
  /* ... see full token list in the Theming guide */

  /* Shadows — three semantic tiers */
  --shadow-surface:
    0 2px 4px 0 oklch(0% 0 0 / 0.04), 0 1px 2px 0 oklch(0% 0 0 / 0.06),
    0 0 0 1px oklch(0% 0 0 / 0.04);
  --shadow-field:
    0 1px 2px 0 oklch(0% 0 0 / 0.05), 0 0 0 1px oklch(0% 0 0 / 0.04);
  --shadow-overlay:
    0 8px 30px oklch(0% 0 0 / 0.12), 0 2px 8px oklch(0% 0 0 / 0.06),
    0 0 0 1px oklch(0% 0 0 / 0.06);

  /* Easing curves */
  --ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-out-fluid: cubic-bezier(0.32, 0.72, 0, 1);
  /* ... */
}

Light mode tokens (:root) — base OKLCH values for all colors, surfaces, and borders.

Dark mode tokens (.dark) — overrides for dark mode, including zeroed shadows where tonal contrast provides depth.

CSS utilities — shared focus, disabled, and invalid patterns used by every component:

@utility focus-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: 2px;
}

@utility focus-field-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: -1px;
}

@utility status-disabled {
  opacity: 0.5;
  pointer-events: none;
  cursor: not-allowed;
}

For the complete globals.css file, see the Theming guide.

Copy Component Files

Copy the component source from the registry into your components/ui/ directory. Each component is a self-contained file that imports from @base-ui/react and @/lib/utils.

// components/ui/button.tsx
"use client";

import { Button as ButtonPrimitive } from "@base-ui/react/button";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

// ... component implementation

Token Overview

The design system organizes tokens into clear categories:

Category	Examples	Purpose
Colors	`--primary`, `--destructive`, `--success`	Brand and semantic colors (OKLCH values)
Surfaces	`--surface`, `--overlay`, `--field-background`	Role-based surface backgrounds
Borders	`--border`, `--border-light`, `--field-border`	Edge treatments at multiple weights
Shadows	`--shadow-surface`, `--shadow-field`, `--shadow-overlay`	Three semantic tiers, mode-adaptive
Easings	`--ease-smooth`, `--ease-out-fluid`	Animation timing functions
Radius	`--radius`, `--radius-sm`, `--radius-lg`	Border radius scale
Derived	`--primary-hover`, `--primary-soft`	Auto-computed via `color-mix()`

Dark Mode

Prototyper UI supports dark mode through the .dark class on the <html> element. The recommended approach uses next-themes:

Using next-themes

npm install next-themes

// app/layout.tsx
import { ThemeProvider } from "next-themes";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

How Dark Mode Works

The .dark class toggles all color tokens to their dark variants and adjusts the shadow system:

Colors shift to darker backgrounds and lighter foregrounds
Shadows are zeroed for surface and field (tonal contrast provides depth instead)
Overlay shadows switch to a subtle white inset glow + deeper dark shadow
Derived colors (--primary-hover, --primary-soft, etc.) auto-adapt via color-mix()

Alternative: data-theme Attribute

You can also toggle dark mode via a data-theme attribute if you prefer:

[data-theme="dark"] {
  /* Same dark mode token overrides as .dark */
}

System Preference

To respect the user's OS setting without JavaScript:

@media (prefers-color-scheme: dark) {
  :root {
    /* Dark mode token overrides */
  }
}

The next-themes approach with enableSystem handles this automatically and avoids flash of wrong theme on load.

Requirements

Prototyper UI components require the following:

React 19+
Next.js 15+
Tailwind CSS v4
Base UI (@base-ui/react)

Quick Start

Option A: Prototyper UI CLI (Recommended)

Set up your project and add components with the Prototyper UI CLI:

bunx @prototyperco/cli init       # tokens, utils, base styles
bunx @prototyperco/cli add button # add components

Run add without arguments for an interactive component picker, or install everything at once:

bunx @prototyperco/cli add --all

Machine Mode Package (Installable Runtime)

To scaffold URL-driven machine mode in a Next.js App Router project:

bunx @prototyperco/cli machine-mode init

See the full guide at Machine Mode Package.

Option B: shadcn CLI

If you already use shadcn, install any component directly from the registry:

npx shadcn@latest add https://prototyper-ui.com/r/button.json

This copies the component source into your project (typically components/ui/button.tsx) along with any required dependencies.

npx shadcn@latest add https://prototyper-ui.com/r/button.json https://prototyper-ui.com/r/dialog.json https://prototyper-ui.com/r/select.json

Keeping Up to Date

bunx @prototyperco/cli update    # check for component updates
bunx @prototyperco/cli doctor    # verify project setup

Manual Setup

If you prefer to set up manually or need to understand each step, follow this guide.

Install Dependencies

npm install @base-ui/react class-variance-authority clsx tailwind-merge

Add the `cn` Utility

Create lib/utils.ts in your project:

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Set Up CSS Tokens

Add the design tokens to your globals.css. The token system has four layers:

Theme registration — maps CSS custom properties to Tailwind utilities:

@theme {
  /* Radius scale */
  --radius-xl: calc(var(--radius) + 4px);
  --radius-lg: var(--radius);
  --radius-md: calc(var(--radius) - 2px);
  --radius-sm: calc(var(--radius) - 4px);

  /* Colors — each generates bg-*, text-*, border-* utilities */
  --color-background: oklch(var(--background));
  --color-foreground: oklch(var(--foreground));
  --color-primary: oklch(var(--primary));
  --color-primary-foreground: oklch(var(--primary-foreground));
  /* ... see full token list in the Theming guide */

  /* Shadows — three semantic tiers */
  --shadow-surface:
    0 2px 4px 0 oklch(0% 0 0 / 0.04), 0 1px 2px 0 oklch(0% 0 0 / 0.06),
    0 0 0 1px oklch(0% 0 0 / 0.04);
  --shadow-field:
    0 1px 2px 0 oklch(0% 0 0 / 0.05), 0 0 0 1px oklch(0% 0 0 / 0.04);
  --shadow-overlay:
    0 8px 30px oklch(0% 0 0 / 0.12), 0 2px 8px oklch(0% 0 0 / 0.06),
    0 0 0 1px oklch(0% 0 0 / 0.06);

  /* Easing curves */
  --ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
  --ease-out-fluid: cubic-bezier(0.32, 0.72, 0, 1);
  /* ... */
}

Light mode tokens (:root) — base OKLCH values for all colors, surfaces, and borders.

Dark mode tokens (.dark) — overrides for dark mode, including zeroed shadows where tonal contrast provides depth.

CSS utilities — shared focus, disabled, and invalid patterns used by every component:

@utility focus-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: 2px;
}

@utility focus-field-ring {
  outline: 2px solid var(--color-ring);
  outline-offset: -1px;
}

@utility status-disabled {
  opacity: 0.5;
  pointer-events: none;
  cursor: not-allowed;
}

For the complete globals.css file, see the Theming guide.

Copy Component Files

Copy the component source from the registry into your components/ui/ directory. Each component is a self-contained file that imports from @base-ui/react and @/lib/utils.

// components/ui/button.tsx
"use client";

import { Button as ButtonPrimitive } from "@base-ui/react/button";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";

// ... component implementation

Token Overview

The design system organizes tokens into clear categories:

Category	Examples	Purpose
Colors	`--primary`, `--destructive`, `--success`	Brand and semantic colors (OKLCH values)
Surfaces	`--surface`, `--overlay`, `--field-background`	Role-based surface backgrounds
Borders	`--border`, `--border-light`, `--field-border`	Edge treatments at multiple weights
Shadows	`--shadow-surface`, `--shadow-field`, `--shadow-overlay`	Three semantic tiers, mode-adaptive
Easings	`--ease-smooth`, `--ease-out-fluid`	Animation timing functions
Radius	`--radius`, `--radius-sm`, `--radius-lg`	Border radius scale
Derived	`--primary-hover`, `--primary-soft`	Auto-computed via `color-mix()`

Dark Mode

Prototyper UI supports dark mode through the .dark class on the <html> element. The recommended approach uses next-themes:

Using next-themes

npm install next-themes

// app/layout.tsx
import { ThemeProvider } from "next-themes";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

How Dark Mode Works

The .dark class toggles all color tokens to their dark variants and adjusts the shadow system:

Colors shift to darker backgrounds and lighter foregrounds
Shadows are zeroed for surface and field (tonal contrast provides depth instead)
Overlay shadows switch to a subtle white inset glow + deeper dark shadow
Derived colors (--primary-hover, --primary-soft, etc.) auto-adapt via color-mix()

Alternative: data-theme Attribute

You can also toggle dark mode via a data-theme attribute if you prefer:

[data-theme="dark"] {
  /* Same dark mode token overrides as .dark */
}

System Preference

To respect the user's OS setting without JavaScript:

@media (prefers-color-scheme: dark) {
  :root {
    /* Dark mode token overrides */
  }
}

The next-themes approach with enableSystem handles this automatically and avoids flash of wrong theme on load.

Installation

Requirements

Quick Start

Option A: Prototyper UI CLI (Recommended)

Machine Mode Package (Installable Runtime)

Option B: shadcn CLI

Keeping Up to Date

Manual Setup

Install Dependencies

Add the `cn` Utility

Set Up CSS Tokens

Copy Component Files

Token Overview

Dark Mode

Using next-themes

How Dark Mode Works

Alternative: data-theme Attribute

System Preference

On this page

Installation

Requirements

Quick Start

Option A: Prototyper UI CLI (Recommended)

Machine Mode Package (Installable Runtime)

Option B: shadcn CLI

Keeping Up to Date

Manual Setup

Install Dependencies

Add the `cn` Utility

Set Up CSS Tokens

Copy Component Files

Token Overview

Dark Mode

Using next-themes

How Dark Mode Works

Alternative: data-theme Attribute

System Preference

On this page