The documents

The files that actually govern this system, rendered here from the same release the site is built against. Each page carries the full document and a copy button, so an agent can be handed the exact rules.

The system

start.md

The official way in, written for the agent: the whole setup journey as one followable document — also served raw at /start.md.

DESIGN.md

The constitution: the two vocabularies, the token rules, the ambient layer contract, and how the system is governed.

DECISION-LOG.md

Every decision that shaped the system, dated, with its why: what was tried, what was reversed, and where the rules came from.

README.md

What ambientui is, the two ways to take it, and how the repo proves its own claims before printing them.

Working rules

CLAUDE.md

The rules the AI works under: tokens only, sanctioned components only, and what counts as a governance event.

Motion spec

The global motion contract for porting — roles, characters, and the arrival choreography.

Ambient shell spec

The complete behavior contract for porting the assistant's shell: every mode, gesture and transition it must honor.

Ambient API

How the assistant connects to your backend: one validated API, stubs until a server exists, whole or streamed answers.

Figma sync

Code → Figma, variables only, code wins on conflict — the procedure and the drift check.

Skills

The three review roles your agent takes on. They install with npx shadcn add @ambientui/governance — or copy one straight into .claude/skills/.

ds-manager.md

Guards the system: compliance, promotion versus rejection, impact analysis, and keeping it in sync.

product-design-manager.md

Guards the product: the right surface for the use case, flow consistency, and UX quality.

product-copy.md

Guards the words: microcopy, errors, empty states, terminology, and product voice.