brand-ui — A2UI Surface

import { A2uiSurface } from "@elabs-ai/components-ai";

Install

npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-ai

Skipping the @source line is the most common first failure: Tailwind does not scan node_modules, so every component renders unstyled. The one-time wiring

Prompt for your coding agent

Paste it into Claude Code, Cursor, Codex or any other coding agent. Text in [brackets] is yours to fill in.

Add the brand-ui A2uiSurface component (from @elabs-ai/components-ai) to this project.

1. Read https://elabs-ai.com/llms.txt first: it maps every package and the rules. If you can use MCP servers, connect https://elabs-ai.com/mcp and use its search, docs and tokens tools. If not, run the same lookups in the terminal: `npx -y @elabs-ai/components-cli search "<what you need>"` and `npx -y @elabs-ai/components-cli docs <Component>`.
2. Look A2uiSurface up before writing code: `npx -y @elabs-ai/components-cli docs A2uiSurface` prints its real props, variants, what it pairs with and what to avoid.
3. If @elabs-ai/components-ai is not installed yet: `pnpm add @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-ai` (or `npm install @elabs-ai/components-tokens @elabs-ai/components-ui @elabs-ai/components-ai`). If this is the first brand-ui package in the project, wire it once: import `@elabs-ai/components-tokens/styles.css` plus the `themes/light.css` and `themes/dark.css` stylesheets in the CSS entry, add one Tailwind `@source` line per installed @elabs-ai package (Tailwind does not scan node_modules, so without it everything renders unstyled), and wrap the app root in `ThemeProvider` from `@elabs-ai/components-tokens`.
4. Use it here: [the screen or file, and what it should show]
5. Rules: use only @elabs-ai/components-* components and the semantic tokens — no raw colours, no raw font sizes, no arbitrary Tailwind values. Look up each component's real props with the docs tool before you use it; never guess a prop.
6. Done means: the typecheck passes, `npx -y @elabs-ai/components-cli audit src --strict` reports nothing, and you have opened the app and looked at every screen you touched in the light and the dark theme.

Avoid

Letting the agent emit className, style or code — a surface is data; the validator rejects anything outside `brand-ui a2ui catalog`.
Resolving actions inside the surface — `on.<event>` names a host verb; the app's onAction decides what it means (D5).
Reaching for A2UI for a chat that only shows messages — that is a conversation (UIMessage); A2UI is for screens the agent designs.
Extending the catalog with a component that owns its own colours — every catalog type renders on semantic tokens so a surface inherits the app's theme.

Works with

Used inside

Message
ToolOutput
Artifact

Pairs with

uiCatalog
createA2uiCatalog
validateA2uiSurface

Avoid next to

JSXPreview for the same surface — pick the data path or the escape hatch, not both

Examples

8 live examples

Form Controls

A form-like surface: inputs, a select, a switch — every change reaches `onAction` with its value.

Composition

Tabs, an accordion and a timeline — stateful compounds the agent composes from the catalog.

Streaming

Streaming: partial JSON is completed, validated per node, and builds up behind a skeleton.

Loading

`loading`: nothing has arrived yet — the layout-shaped skeleton with a polite live region.

Invalid

A settled surface that breaks the contract: every problem, with its path, in a `role="alert"`.

Extended Catalog

An app-extended catalog: `Sparkline` is unknown to the shipped catalog but valid in this app's.

Live Edit

Live editing: the surface re-validates on every keystroke; incomplete JSON keeps the last frame.

API

`A2uiSurface`

Prop	Type	Description
`surface`required	`A2uiSurfaceSpec \| string \| null \| undefined`	The agent's surface: a parsed spec, or its JSON text (may be a streaming prefix).
`catalog`	`A2uiCatalog`	Which types render, and how. Defaults to the shipped `uiCatalog`.
`onAction`	`A2uiActionHandler`	Receives every `on.<event>` binding the user triggers.
`isStreaming`	`boolean`	Content is arriving incrementally — build up, suppress transient errors.
`loading`	`boolean`	No surface yet (fetch-then-show) — forces the skeleton.
`onError`	`(errors: A2uiError[]) => void`	Fires once per settled, invalid surface with the validation errors.
`skeleton`	`ReactNode`	Replace the default skeleton (shown before the first paint while pending).

Also accepts: Omit<ComponentProps<"div">, "children" | "onError">

Theming

The tokens each state resolves to. Change the token and every theme follows.

State	Token
loading	`layout-shaped Skeleton + role=status live region until the first node paints`
streaming	`isStreaming → the JSON prefix is completed, valid nodes draw, invalid-yet nodes are pruned; no error until the input settles`
error	`settled + invalid → role=alert listing every problem with its path; onError once`