# Getting started

Let your coding agent set up Siteplane UI and its skill, or set it up yourself with the shadcn CLI.

Siteplane UI is a React UI kit for building with AI agents. Every component comes finished, with its states, motion and micro-interactions built in. Patterns, sections and templates combine them into whole screens, and a skill shows your agent how to use all of it. You install everything with the shadcn CLI, and the code lives in your project.

## Set up with your agent

Open your coding agent, such as Claude Code, Codex or Cursor, in your application directory and send it this prompt. In an empty directory, it creates a Next.js application first.

```text
Set up Siteplane UI (https://ui.siteplane.io) in this project and install its skill for yourself.

Follow the installation guide for this project's framework step by step:
- Next.js (App Router): https://ui.siteplane.io/docs-markdown/installation/nextjs.md
- Vite: https://ui.siteplane.io/docs-markdown/installation/vite.md

If this directory is empty, create a Next.js application in it with the command from the Next.js guide. Siteplane UI needs React 19, TypeScript, Tailwind CSS 4 and an @/* alias that points to src/*. The guides add Tailwind and the alias where they are missing. If an existing application would need an upgrade or a restructure, such as React 18 to 19, Tailwind CSS 3 to 4 or a move into src, tell me what would have to change and wait for my answer.

1. Write components.json as the guide shows. Do not run shadcn init, because it writes a theme over the kit's styles. If components.json already exists, keep it and add "@siteplane": "https://ui.siteplane.io/registry/{name}.json" to its registries.
2. Install the first component: pnpm dlx shadcn@4.18.0 add @siteplane/button
3. Load the kit stylesheet and the Inter font as the guide shows. If the user wants another typeface, follow the guide's link to Typeface instead of loading Inter. In a new application, replace the starter styles. In an existing one, make the kit stylesheet the first import, keep the application's own styles below it and remove a separate @import "tailwindcss".
4. If the project's .env.local or .env defines SITEPLANE_LICENSE_KEY, also add the @siteplane-pro registry from the Siteplane UI Pro section of https://ui.siteplane.io/docs-markdown/installation.md. Never print or commit the key.
5. Install the skill for yourself: pnpm dlx skills@1.5.25 add https://ui.siteplane.io -a claude-code. If you are not Claude Code, replace claude-code with your agent, for example codex or cursor. The installer needs Node.js 22.20 or newer. Then read the installed SKILL.md and follow it for all Siteplane UI work in this project.
6. In a new application, render a Siteplane UI Button on the start page as the guide shows. Run the build and fix any errors the setup caused. If you can open a browser, check that Siteplane UI components render styled. Unstyled ones mean the global CSS import or Tailwind scanning is missing.

Use the project's package manager; with npm, replace pnpm dlx with npx. When you are done, tell me what you changed and how to start the application.
```

## Set up by hand

Run the commands from your application directory. They use pnpm; with npm, replace `pnpm dlx` with `npx`.

### Set up the kit

Siteplane UI needs React 19, TypeScript, Tailwind CSS 4 and an `@/*` alias that points to `src/*`. [Installation](/docs/installation/) covers the complete setup for [Next.js](/docs/installation/nextjs/) and [Vite](/docs/installation/vite/).

Create `components.json` in your application directory instead of running `shadcn init`. This is the complete file for Next.js; the [Vite guide](/docs/installation/vite/#create-componentsjson) has the one for Vite:

```json title="components.json"
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks",
    "utils": "@/siteplane/system/utils/cn"
  },
  "registries": {
    "@siteplane": "https://ui.siteplane.io/registry/{name}.json"
  }
}
```

If your application already has a `components.json`, add the `@siteplane` entry to its `registries` instead.

Install your first component:

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/button
```

Then make the kit stylesheet your global CSS. In a new Next.js application, replace the contents of `src/app/globals.css` with these two lines:

```css title="src/app/globals.css"
@import "../siteplane/system/styles/base.css";
@source "..";
```

An application with its own styles keeps them below the import, as [Installation](/docs/installation/#load-styles-and-typography) shows.

### Install the skill

The [skill](/docs/agents/skills/) shows your coding agent which component fits and how to combine them. Install it for your agent, for example Claude Code:

```bash
pnpm dlx skills@1.5.25 add https://ui.siteplane.io -a claude-code
```

For Codex or Cursor, use `codex` or `cursor` in place of `claude-code`. Keep `-a` when your agent runs the command. Started by an agent, the installer skips its prompts, and without `-a` it can install the skill for every agent it supports.

## Try it

With the kit and the skill installed, give your agent its first task:

```text wrap
Build a settings page with a profile form and a team members table using Siteplane UI.
```

## Customize and automate

Set [shared size, density, radius, and locale](/docs/customization/providers/), then adjust [theme tokens](/docs/customization/theming/) or [local styles](/docs/customization/styling/). When you build with your agent, start from the [agent setup](/docs/agents/setup/) and the [application guidelines](/docs/agents/guidelines/). Every page has a Markdown version: [llms.txt](/llms.txt) indexes them, and [llms-full.txt](/llms-full.txt) includes the complete examples.

## Source and updates

Installed source belongs to your application. Review incoming changes before you overwrite local customizations; see [installation and updates](/docs/installation/#updating-and-manual-installation) and [known limitations](/docs/help/). From 1.0, the API these docs describe is stable, and a renamed prop or part keeps working under its old name until the next major version; see [Stability and deprecations](/docs/installation/#stability-and-deprecations).