Installation

ambientui installs through the shadcn CLI into any React project with Tailwind CSS v4. Real source files land in your repo — you own every line, and there is no runtime dependency on us. The easiest path is to let your agent do all of this; the commands below are the same ones it runs.

Register the registry, once

This teaches the shadcn CLI what @ambientui/… means. One command, once per project:

npx shadcn@latest registry add "@ambientui=https://registry.ambientui.ai/r/{name}.json"

The doors

Take the guidance first — the start door installs the setup skill with the constitution (DESIGN.md) beside it, so the repo itself carries the rules the system runs on: how a reference becomes a configuration, and the propagation rules that make every border and corner follow the theme.

npx shadcn@latest add @ambientui/start

The governance door lands the working rules beside it — a CLAUDE.md of hard rules and three reviewer skills, written for the ambientui repo and adapted to yours as part of setup:

npx shadcn@latest add @ambientui/governance

Then the system itself — the design system's configuration engine, and the assistant that rides on it:

npx shadcn@latest add @ambientui/foundation

npx shadcn@latest add @ambientui/ambient-layer

The Foundation lands under lib/foundation/ with components/foundation-provider.tsx; the complete ambient layer lands under components/ambient/. Two stylesheets landed too — wire them into your global CSS, after the Tailwind import. They are what makes one saved configuration re-theme everything, so import them as shipped rather than rebuilding what is inside them:

@import "tailwindcss";
@import "./styles/foundation.css";
@import "./styles/ambient.css";

Then mount both providers at the app root before building anything:

<FoundationProvider>
  <AssistantProvider navItems={NAV} onNavigate={goTo}>
    <App />
    <Assistant />
  </AssistantProvider>
</FoundationProvider>

navItems is your own route list, and onNavigate wires into your router — the layer never imports your route table.

Then check the install actually landed before building on it. The shadcn CLI fails quietly when a project's @/ alias is not configured in every tsconfig it reads: it writes real files into a literal folder named @ at the repo root and reports success, and every import into the layer is then unresolvable — which crashes the assistant the moment it opens. If that folder exists, add the paths entry to every tsconfig, move its contents into src/, and re-run the door. Then press ⌘K and watch the console: zero errors is the bar.

The Foundation

The configuration space, and the pieces it is made of.

npx shadcn add @ambientui/foundation

The design system as a bounded configuration space: pick the accent, the gray, the radius step, the spacing unit, the motion character, and every surface follows. Saving is the commit point.

npx shadcn add @ambientui/foundation-tokens

Every dimension the design system can vary — accents, grays, the radius window, the spacing grid, scaling, the role map, motion characters, fonts, icon libraries — and the compiler that turns a config into CSS. Data and one pure function; no React.

npx shadcn add @ambientui/foundation-theme

The runtime variables the Foundation drives — the radius window and the motion roles — and the @theme block that routes Tailwind's utilities through them.

npx shadcn add @ambientui/foundation-ambient-bridge

Binds the ambient layer's motion, palette and stream pace to your Foundation config, so the assistant has no values of its own.

The ambient layer

The assistant itself, and its material.

npx shadcn add @ambientui/ambient-layer

The complete AI assistant surface — orb, line, panel, dock, spotlight and history. It renders above your product rather than inside its component tree.

npx shadcn add @ambientui/ambient-styles

The glass recipes, translucency tokens, live border, glyph breath and stream edge that every ambient surface wears.

npx shadcn add @ambientui/ambient-assets

The five SVG shapes the heat shader wraps — the circle the orb wears and the rects a surface field fills. Static files, served from your public root.

npx shadcn add @ambientui/orb-character

The assistant's animated identity — an iridescent sphere whose palette derives from the theme accent, with four states covering the AI's lifecycle.

For your agent

Guidance that installs into the repo, so future sessions find it.

npx shadcn add @ambientui/start

The guided setup, written for the AI agent doing the work: install the system, ask the owner for one inspiration reference, express it as Foundation configuration, build the product, and end with the spotlight open. Installs as a skill WITH the constitution beside it - DESIGN.md is the logic the journey runs on (a reference is a request for a configuration; every dimension derives from tokens), and a setup that skips it produces screens whose borders and corners do not follow the theme.

npx shadcn add @ambientui/governance

The rules an AI agent works under in this system: the constitution's hard rules, plus three review roles — design-system manager, product-design manager, and copy.

Single pieces

Beyond the doors above, the registry ships 30 of the layer's components individually — just the reasoning panel, just the diff, just the composer. Every component's page in the design system carries its own install command, and the full index lives at registry.ambientui.ai.

The npm route

If you would rather consume the layer as a package than own the source, the same code ships on npm:

npm install ambientui

Import ambientui/styles/ambient.css once, and the components from ambientui/*. Pick one route per repo: the registry files and the package are the same layer twice, and mixing them in one project is a conflict, not a convenience.

Where to next

The agent skill makes your repo carry this whole setup as guidance, and getting started shows the journey these commands belong to.