Registry And Distribution

Siteplane UI ships through a shadcn-compatible source registry. Consumers own the copied code, while item manifests, hashes, license notices and Doctor checks keep the original source contract visible.

The searchable catalog is available at /r/registry.json. Every item JSON includes its category, public documentation and Siteplane agent-contract metadata alongside the installable source.

Agent-first path

Start with Getting Started, install the portable Skill from AI Agents, then let the agent inspect the project and use the standard shadcn CLI or MCP server against @siteplane. This page keeps the complete source-distribution and manual update contract available for human review.

pnpm dlx shadcn@4.16.1 info --json
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 mcp init

See the current Button primitive, Validated Form recipe, complete /llms-full.txt contract and /agent-evals.json evidence record.

Current status

Siteplane UI is pre-1.0. Registry artifacts and local sync are designed for preview releases. Release 0.1.0 passed registry validation, the versioned fresh-consumer browser gate and the seven-workflow Codex CLI qualification recorded in /agent-evals.json. The proposed @siteplane Directory entry is validated locally, but automatic namespace resolution is not available until the upstream entry is merged and passes the live CLI check.

Intent search evidence

The static catalog is qualified with shadcn@4.16.1. Its pinned search matrix uses only item names and the public MDX-sourced descriptions; changing the CLI version requires search requalification.

Registry item types

Why source distribution

• Teams can inspect and intentionally edit installed source.
• Manifests and hashes make local drift visible.
• Provider, stylesheet, motion and interaction contracts can be verified in the consuming app.
• Primitive fixes move back into Siteplane UI before being synced out again.

Hosted registry

Configure the namespace in components.json:

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

Then install namespaced items:

pnpm dlx shadcn@4.16.1 add @siteplane/base
pnpm dlx shadcn@4.16.1 add @siteplane/button @siteplane/dialog @siteplane/input

The Agent Skill is not a registry item. Install it through the pinned Skills CLI as documented in AI Agents.

The base item writes the complete stylesheet to src/styles/siteplane-ui.css; it never replaces an existing src/app/globals.css.

In that app stylesheet, replace only the existing framework imports:

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

with exactly:

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

Keep every app-owned CSS rule below that import unchanged. Do not retain both import blocks because the Siteplane stylesheet already includes Tailwind, tw-animate-css and the shadcn Tailwind layer.

LICENSE.siteplane-ui and TRADEMARKS.siteplane-ui.md are installed at the project root so redistribution terms remain next to the copied source.

Canonical hosted copies remain available at Registry License and Registry Trademarks.

Immutable release URLs

/r/* and @siteplane track the current discovery surface. A release is reproduced from /r/v/<semver>/registry.json and /r/v/<semver>/<item>.json. All internal registry dependencies are absolute URLs inside that same versioned graph.

For Siteplane UI 0.1.0, the documented transitive proof starts with one URL:

https://ui.siteplane.io/r/v/0.1.0/dashboard-shell.json

The matching siteplane-manifest.json binds the graph to the Skill and public agent-contract hashes. The mutable graph stays available for discovery; it is not the reproducibility boundary.

Local maintainer flow

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

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

siteplane:sync writes source and .siteplane-ui/manifest.json. siteplane:doctor checks drift, missing providers, CSS hooks and unsafe primitive changes. Review .siteplane-ui/patch-notes.md after every sync.

Release validation

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

A release also runs the fresh-consumer gate: install the hosted-style items into an app that already owns globals.css, confirm installation leaves that file unchanged, replace only its framework import block with the Siteplane stylesheet import, and compile the consumer.

Source contract

Copied primitives under src/components/siteplane-ui/** or src/components/ui/** are technically editable. Supported sync applies while their manifest hashes match. Compose product behavior outside those files; an intentional primitive edit is a documented fork and Doctor-reported drift.

Update policy

• Treat updates as explicit source sync work, not automatic runtime upgrades.
• Run Doctor before and after syncing an existing app.
• Preserve unrelated product changes and app-owned setup files.
• Move primitive fixes back into Siteplane UI first, then sync intentionally.
• Keep the installed license and trademark notice with redistributed source.