Prerequisites

Before you begin, make sure your project meets the following requirements:

• Node.js 18 or later
• Next.js 15+ with the App Router (pages router is not supported)
• pnpm is recommended, though npm and yarn also work
• Tailwind CSS v4 — Clinia UI does not support Tailwind v3

1. Initialize with the Clinia base

Run shadcn init pointing directly at the Clinia base registry item:

pnpm dlx shadcn@latest init https://ui.clinia.dev/r/base.json

This creates a components.json at the root of your project configured with:

• style: "base-maia" — selects the Base UI component variant
• iconLibrary: "hugeicons" — sets HugeIcons as the default icon set (apps may swap in lucide or another richer library; there are no custom Clinia product icons)
• @clinia namespace pre-registered so you can install Clinia registry items by name

Your components.json will look similar to this after initialization:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-maia",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "iconLibrary": "hugeicons",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@clinia": {
      "url": "https://ui.clinia.dev/r/{name}.json"
    }
  }
}

2. Install the Clinia Theme

The theme registry item installs the @clinia/tailwindcss package and writes the necessary imports into your globals.css:

pnpm dlx shadcn@latest add @clinia/theme

After running this, your globals.css will contain:

@import "@clinia/tailwindcss";

This single import brings in all design tokens (colors, typography, spacing, radii) and the base reset.

3. Add Your First Component

Add shadcn components — they automatically inherit Clinia tokens because your project's CSS variables have been overridden by the theme:

npx shadcn@latest add button card input

This lands the component source code in components/ui/. You own the files and can edit them freely.

4. Use the Component

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

export default function Page() {
  return (
    <main>
      <Button>Book appointment</Button>
      <Button variant="outline">Learn more</Button>
    </main>
  )
}

Manual Setup

If you prefer not to use the shadcn CLI, you can wire up the design tokens manually.

Install the package:

pnpm add @clinia/tailwindcss

Import in globals.css:

@import "@clinia/tailwindcss";

With manual setup, you will need to install individual shadcn components using the CLI.

Next Steps

• Registry — understand how the registry is structured
• Theming — configure dark mode and token overrides