Getting Started

Prerequisites

Before you begin, make sure you have:

• Node.js 18 or later
• React 19+
• Next.js 15+ (or any React framework with Tailwind CSS v4)
• Tailwind CSS v4

Initialize your project

Run the init command to set up design tokens, utilities, and base styles:

npx @prototyperco/cli init

This will:

1. Merge OKLCH design tokens into your globals.css
2. Create lib/utils.ts with the cn() utility
3. Write a .prototyper-ui.json manifest
4. Optionally install AI skills for Claude Code or Cursor

Add your first component

Install a component using the CLI:

npx @prototyperco/cli add button

The component source file lands in components/ui/button.tsx — you own this file and can edit it freely.

Run add without arguments for an interactive picker, or install multiple components at once:

npx @prototyperco/cli add button card dialog field text-field

To install every available component:

npx @prototyperco/cli add --all

Install dependencies

If the CLI didn't install them automatically, add the required peer dependencies:

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

Use a component

Import and use the component in your page:

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

export default function Page() {
  return (
    <div className="flex gap-4 p-8">
      <Button>Default</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="destructive">Destructive</Button>
    </div>
  );
}

Build a simple page

Here's a complete example combining several components:

import { Button } from "@/components/ui/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/ui/card";
import { Field, FieldLabel, FieldDescription } from "@/components/ui/field";
import { TextField, Input } from "@/components/ui/text-field";

export default function SignUpPage() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <Card className="w-full max-w-md">
        <CardHeader>
          <CardTitle>Create an account</CardTitle>
          <CardDescription>Enter your details to get started.</CardDescription>
        </CardHeader>
        <CardContent className="space-y-4">
          <TextField>
            <FieldLabel>Name</FieldLabel>
            <Input placeholder="Jane Doe" />
          </TextField>
          <TextField>
            <FieldLabel>Email</FieldLabel>
            <Input type="email" placeholder="jane@example.com" />
          </TextField>
        </CardContent>
        <CardFooter>
          <Button className="w-full">Sign up</Button>
        </CardFooter>
      </Card>
    </div>
  );
}

Customize your theme

Prototyper UI uses OKLCH color tokens defined in your globals.css. To customize colors, edit the CSS custom properties in the :root block:

:root {
  --primary: 39.11% 0.084 240.8; /* Lightness Chroma Hue */
  --primary-foreground: 98.48% 0.002 247.84;
}

For a visual editor, use the Theme Builder to pick colors and copy the generated tokens.

See the Theming guide for the full token reference.

Verify your setup

Run the doctor command to check that everything is configured correctly:

npx @prototyperco/cli doctor

Using with shadcn

If you already use shadcn, you can install Prototyper UI components directly from the registry without running init:

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

Both libraries can coexist — Prototyper UI components install to the same components/ui/ directory and follow the same conventions.

Accessibility notes

Touch targets

Prototyper UI components meet accessibility standards out of the box. However, icon-only buttons default to size-8 (32px), which is below the WCAG 2.5.8 recommended minimum of 44px.

For touch-heavy interfaces (mobile apps, kiosks), use size="sm" or add custom padding to increase the hit area:

{
  /* Option 1: Use a larger size */
}
<Button size="sm" variant="ghost">
  <TrashIcon />
</Button>;

{
  /* Option 2: Add padding to the icon button */
}
<Button variant="ghost" size="icon" className="size-11">
  <TrashIcon />
</Button>;

Next steps

• Browse all Components to see what's available
• Read the CLI Reference for all commands and options
• Learn about Forms with validation and react-hook-form
• Explore the Theming guide for deep customization
• Try the Theme Builder for visual token editing