Getting started

Installation

Add Cuelark UI components to any shadcn/ui project with the shadcn CLI, by URL or by the @cuelark namespace.

1. A shadcn/ui project

Cuelark UI works in any React project set up for shadcn/ui with Tailwind CSS v4: Next.js, TanStack Start, React Router, Vite or Astro. If you are starting fresh, run npx shadcn@latest init and follow the prompts.

2. Add a component

Point the CLI at a component's registry URL. The theme tokens, the motion layer and any components it builds on come along automatically.

pnpm dlx shadcn@latest add https://ui.cuelark.com/r/button.json

3. Optional: the @cuelark namespace

Add the registry to components.json once, then install by name, e.g. npx shadcn@latest add @cuelark/dialog @cuelark/toast.

components.json

{
  "registries": {
    "@cuelark": "https://ui.cuelark.com/r/{name}.json"
  }
}

4. Use it

Components land in your ui folder like any shadcn component. Import them and change whatever you like, because the code is yours.

save-bar.tsx

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

export function SaveBar() {
  return <Button kbd="⌘S">Save changes</Button>;
}

Using an AI assistant

With the shadcn MCP server, assistants such as Claude, Cursor or Windsurf can browse and install Cuelark components for you once the namespace is configured. For context, point them at llms.txt or llms-full.txt.

.mcp.json

{
  "mcpServers": {
    "shadcn": { "command": "npx", "args": ["shadcn@latest", "mcp"] }
  }
}

Requirements

React 19 and Tailwind CSS v4 with tw-animate-css (included by shadcn init).
Animated components use gsap and @gsap/react, which the CLI installs. GSAP is free for commercial use under its standard license.
Next steps: theming and the component index.