Getting Started

Source-owned UI for coding agents. Discover, inspect, install, compose and verify the real component source instead of guessing from memory.

Agent-first setup

1. Install the Siteplane Agent Skill

The release replaces <full-commit> with the qualified immutable revision. Replace <codex|claude-code> with the selected host:

pnpm dlx skills@1.5.21 add https://github.com/LukasvanUden/siteplane-ui/tree/<full-commit>/.agents/skills/siteplane-ui --skill siteplane-ui --agent <codex|claude-code> --copy --yes

The same instruction-only Skill is copied into the project-native location used by Codex CLI or Claude Code. The component registry does not install the Skill.

2. Inspect the project

Ask the agent to read components.json and inspect the real project before it selects or installs source:

pnpm dlx shadcn@4.16.1 info --json

3. Discover and install current source

Until the proposed @siteplane Registry Directory entry is live, add the normal explicit namespace to components.json:

{
  "registries": {
    "@siteplane": "https://ui.siteplane.io/r/{name}.json"
  }
}

Let the agent use the standard shadcn CLI or MCP server to inspect current source and install only what the interface needs:

pnpm dlx shadcn@4.16.1 list @siteplane
pnpm dlx shadcn@4.16.1 search @siteplane --query "validated form"
pnpm dlx shadcn@4.16.1 view @siteplane/validated-form
pnpm dlx shadcn@4.16.1 add @siteplane/validated-form
pnpm dlx shadcn@4.16.1 mcp init

No Siteplane-specific MCP server is required. The standard shadcn server reads the configured namespace.

4. Give the agent the outcome

Build this interface with Siteplane UI. Inspect the project and current registry
source first, install only missing items, compose outside primitive files, then verify
the real interface.

5. Verify the result

Run the relevant code and browser checks for the consuming application. In this repository, the release-grade registry checks are:

pnpm build:registry
pnpm validate:registry
pnpm check:consumer -- --registry-version 0.1.0

Siteplane UI 0.1.0 is tested with Codex CLI across seven representative workflows. All seven deterministic and browser gates passed, followed by the named screenshot review. The exact candidate, evaluated source, versions, date and hashes are in /agent-evals.json.

Setup resources

Machine-readable setup and evidence:

• /llms.txt — short discovery index.
• /llms-full.txt — complete public setup and source contracts.
• /r/registry.json — mutable discovery catalog.
• /r/v/0.1.0/registry.json — immutable release catalog.
• /r/v/0.1.0/siteplane-manifest.json — release graph and contract hashes.
• /r/button.json — one primitive artifact.
• /r/validated-form.json — one recipe artifact.
• /agent-evals.json — compact release evidence.

Manual installation reference

Agent-first does not remove the human API path. Use this section when reviewing or performing setup directly.

Runtime

• Next.js App Router
• React 19
• Tailwind CSS v4
• Base UI through @base-ui/react
• CSS-first Siteplane motion through central tokens, state attributes and utilities

Install the base layer

pnpm dlx shadcn@4.16.1 add \
  @siteplane/base \
  @siteplane/button \
  @siteplane/toast \
  @siteplane/tooltip

The base item writes the complete Siteplane stylesheet to src/styles/siteplane-ui.css and leaves an existing src/app/globals.css untouched. In that file, replace only this framework import block:

@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";

with exactly:

@import "../styles/siteplane-ui.css";

Keep every app-owned rule below the import unchanged. Do not keep both import blocks. The installer also places LICENSE.siteplane-ui and TRADEMARKS.siteplane-ui.md in the project root.

Mount providers

import { SiteplaneUIProvider } from "@/components/ui/siteplane-provider";
import { ToastProvider } from "@/components/ui/toast";
import { TooltipProvider } from "@/components/ui/tooltip";
import { SiteplaneMotionProvider } from "@/motion";

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <SiteplaneMotionProvider>
      <SiteplaneUIProvider>
        <TooltipProvider>
          <ToastProvider position="top-right">{children}</ToastProvider>
        </TooltipProvider>
      </SiteplaneUIProvider>
    </SiteplaneMotionProvider>
  );
}

The built-in UI fallback remains controlSize="default", density="default" and radius="default". Larger controls are explicit app, subtree or component decisions.

Render a component

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

export function SaveAction() {
  return <Button>Save changes</Button>;
}

Do not recreate Siteplane primitives from memory. If the registry does not contain a required control or reusable composition, treat it as a UI Kit gap or a product-owned pattern.

Review updates

Review source-owned changes before applying them:

pnpm dlx shadcn@4.16.1 add @siteplane/button --diff

An intentional edit to copied primitive source is a fork. Inspect and reconcile it instead of overwriting it automatically.

Local maintainer sync

Maintainers can sync the same source directly from this repository:

pnpm siteplane:sync \
  --target /path/to/app \
  --namespace siteplane-ui \
  --items base,button,input,select,sidebar,dashboard-shell,toast,tooltip

pnpm siteplane:doctor \
  --target /path/to/app \
  --namespace siteplane-ui \
  --scope src

Inspect .siteplane-ui/patch-notes.md after every sync.

Rules

• Import visible controls from the installed Siteplane namespace.
• Import reusable app compositions from @/components/patterns/*.
• Keep one motion, UI, tooltip and toast provider at the app root.
• Use existing system tokens for color, spacing, radius, shadow and motion.
• Read the motion guide before changing global motion behavior.