Get started

Add Acme UI to your app.

Install primitives with the shadcn CLI, wire dark mode yourself, and use the shared token language across dashboards, forms, and marketing surfaces.

Prerequisites

Before you install.

React 19+ and Tailwind CSS v4
A shadcn/ui project with `components.json` configured
Path aliases: `@/components/ui/*` and `@/lib/utils`

Setup

Five steps.

Install the foundation

Start with `base`. It pulls in Geist fonts, OKLCH theme tokens, base CSS, and the `cn` utility. Nothing else is written to your project.

Terminal

$ pnpm dlx shadcn@latest add https://acme-design-system-psi.vercel.app/r/base.json

Register the namespace

Optional but recommended. After this, install items by short name instead of full URLs.

Terminal

$ pnpm dlx shadcn@latest registry add @acme=https://acme-design-system-psi.vercel.app/r/{name}.json

Add primitives

Install one component at a time, or use a bundle when you want a larger starter set.

Terminal

$ pnpm dlx shadcn@latest add @acme/button
$ pnpm dlx shadcn@latest add @acme/dialog
$ pnpm dlx shadcn@latest add @acme/essentials

Wire dark mode

The theme provider is not part of the registry. Use class-based dark mode so tokens match `@custom-variant dark`.

app/layout or root shell

import { ThemeProvider } from 'next-themes'

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="light" disableTransitionOnChange>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Use semantic tokens

Prefer design-system utilities over raw CSS variables in product code.

Examples

className="bg-background text-foreground border-border-muted"
className="rounded-md shadow-frame-primary"
className="text-display text-page text-section text-lead"

Bundles

Install groups by role.

@acme/essentials

Base actions, inputs, badges, cards, loading

@acme/forms

Inputs, selection controls, calendar, date picker

@acme/overlays

Dialog, sheet, drawer, menus, popover, tooltip

@acme/data

Tables, tabs, navigation, status, charts

@acme/media

Audio player, spinner, shimmering text

@acme/all

Base plus every primitive

Opt-in

Extras, only when you ask.

Project files and brand assets are standalone items. Neither base nor all installs them.

@acme/design

DESIGN.md with principles, tokens, and usage guidance

@acme/project-config

AGENTS.md, oxlint, oxfmt, and .gitignore defaults

@acme/logo

Acme logo component using the primary token

@acme/favicons

Light and dark SVG favicons