Installation

The adoption path is intentionally short. Start with @bitsyui/core, then decide whether you want to write token overrides directly or let the CLI generate a starter file.

The shortest setup path

These steps are the whole story for most projects.

Install the foundation package.
Import it once in your application stylesheet.
Add the CLI only if you want a generated starter override file.

pnpm add @bitsyui/core

/* app.css */
@import "@bitsyui/core";

pnpm dlx @bitsyui/cli init bitsy.css --dry-run

The stable v1 entry point is the single @bitsyui/core import. You do not need to assemble individual CSS files by hand.

Start with a few meaningful token changes

Token overrides should feel like the first customization layer, not an advanced escape hatch.

@import "@bitsyui/core";

:root {
  --bitsy-brand-900: #1f3a5f;
  --bitsy-brand-700: #2f5180;
  --bitsy-radius-control: var(--bitsy-radius-md);
}

What to change first

Recolor through the brand palette, and reshape through --bitsy-radius-control and --bitsy-radius-container.
Use a typography profile when hierarchy and reading posture should change.
Keep the structure stable and let token changes do the work.

The CLI stays narrow: it helps with starter token choices, not framework setup or project scaffolding.

Preview the surfaces locally

Use docs for adoption and theme exploration. Use Storybook for isolated validation. Use Node 26 LTS and pnpm 12 or newer.

pnpm install
pnpm dev:docs
pnpm dev:storybook