Installation

Already have React + Tailwind v4? Do this.

npx paubha@latest init
npx paubha@latest add button

That's it. init writes your design tokens and the cn() helper, installs three small deps, and imports the tokens into your global stylesheet for you; add copies a component's actual source into your project (no runtime dependency on Paubha; you own the file) and prints the exact import line to paste, e.g. @/components/ui/button/button.

If either command complains, jump to Troubleshooting. It now tells you exactly what's missing instead of failing silently.

Starting from an empty folder?

Pick your framework. Every step is copy-paste, no prior Tailwind experience needed.

Next.js

npx create-next-app@latest my-app --typescript --tailwind --app
cd my-app
npx paubha@latest init

create-next-app --tailwind already wires up Tailwind v4, so init has everything it needs. Then:

npx paubha@latest add button

Import it from @/components/ui/button/button and drop <Button>Click me</Button> into any page.

Vite (React)

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install tailwindcss @tailwindcss/vite

Add the Tailwind plugin to vite.config.ts and @import "tailwindcss"; to your main CSS (see Tailwind's Vite guide if you haven't done this before), then:

npx paubha@latest init
npx paubha@latest add button

Verify your setup

Before running the CLI, a 10-second sanity check saves a lot of confusion later:

Don't have a package.json yet? You're in an empty folder, so use one of the "starting from zero" walkthroughs above first.

Troubleshooting

npx paubha init exits with "No package.json found" You're not inside a project. Create one first (npx create-next-app@latest or npm create vite@latest), then re-run init from inside it.

A warning about tailwindcss or React version, but it still ran That's non-fatal: init/add will still write files, but components may not render correctly until you're on Tailwind v4 and React 19+. Fix the version, then re-run with --force to rewrite the token files.

It errors with "Tailwind CSS v3 detected, but Paubha requires v4+" Paubha's tokens rely on Tailwind v4's CSS-first @theme, and there's no tailwind.config.js to bridge from v3. Follow Tailwind's v3→v4 upgrade guide, then re-run init --force.

Components render but have no styling init adds the token imports to your global stylesheet automatically, so this usually means it couldn't find that file — check its output. tokens.css and theme.css must be imported after @import "tailwindcss";, otherwise Tailwind's resets and the token layer fight over precedence. In Next.js app/globals.css it should look like this:

@import "tailwindcss";
@import "../styles/tokens.css";
@import "../styles/theme.css";

If your stylesheet lives somewhere init doesn't look, point it there once and re-run:

{ "tailwind": { "css": "src/shell/base.css" } }

Dark mode isn't doing anything It follows the OS by default, so check your system appearance setting first. If you're switching themes with a class, the class goes on <html> (class="dark"), not on <body> or a wrapper div. See Theming.

I don't want to use the CLI at all See Manual copy-paste below.

Using an AI coding agent

Point it at /skill.md: install commands, the full token list, and the real component API conventions, in one file. Works for Claude Code (drop it in as .claude/skills/paubha/SKILL.md), Cursor, or anything else that reads project-level agent instructions.

Manual copy-paste

If you'd rather skip the CLI entirely:

1. Copy tokens.css and theme.css from the docs repo into your styles, and @import both after @import "tailwindcss"; (this is the step init automates; see the CSS order note under Troubleshooting).
2. Add cn():

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

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

3. Copy each component's source from its docs page (or the registry JSON) into your codebase.

shadcn registry compatibility

Paubha's registry follows the open shadcn schema, so components are also installable with:

npx shadcn@latest add https://paubha.tech/r/button.json

For every flag and option, see the full CLI reference.