Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/concepts/catalogs.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Whether you are building a simple prototype or a complex production application,

To help developers get started quickly, the A2UI team maintains the [Basic Catalog](../../specification/v0_9/json/basic_catalog.json).

This is a pre-defined catalog file that contains a standard set of general-purpose components (Buttons, Inputs, Cards) and functions. It is not a special "type" of catalog; it is simply a version of a catalog that we have already written and have open source renderers for.
This is a pre-defined catalog file that contains a basic set of general-purpose components (Buttons, Inputs, Cards) and functions. It is not a special "type" of catalog; it is simply a version of a catalog that we have already written and have open source renderers for.

The basic catalog allows you to bootstrap an application or validate A2UI concepts without needing to write your own schema from scratch. It is intentionally sparse to remain easily implementable by different renderers.

Expand Down Expand Up @@ -389,7 +389,7 @@ Here is how catalog version mismatches are handled in practice:

- **An old iOS client is using an older catalog than the agent**
- The agent sends a new component `Badge` that the old iOS client doesn't know about. The client renders a generic textbox placeholder or safe text description for it, keeping the rest of the interface functional.
- The agent sends a new property `badge` on a `Button` that an old client doesn't know about. The client safely ignores it and renders the standard button.
- The agent sends a new property `badge` on a `Button` that an old client doesn't know about. The client safely ignores it and renders the basic button.
- The agent no longer sends the `Facepile` component that was removed in a later catalog version. This causes no issues for the client.

- **A web client rolls out a new catalog version ahead of the agent**
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ Every component has:

To help developers get started quickly, the A2UI team maintains the [Basic Catalog](../../specification/v0_9/json/basic_catalog.json).

This is a pre-defined catalog file that contains a standard set of general-purpose components (Buttons, Inputs, Cards). It is not a special "type" of catalog; it is simply a version of a catalog that has open source renderers available.
This is a pre-defined catalog file that contains a basic set of general-purpose components (Buttons, Inputs, Cards). It is not a special "type" of catalog; it is simply a version of a catalog that has open source renderers available.

For the complete component gallery with examples, see [Component Reference](../reference/components.md).

Expand Down
2 changes: 1 addition & 1 deletion docs/ecosystem/a2ui-in-the-world.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ The [Agent Development Kit](https://google.github.io/adk-docs/) (ADK) is Google'

**How ADK uses A2UI:**

ADK integrated the A2UI v0.8 standard catalog to automatically render spec-compliant agent parts as native UI components directly in the chat. ADK also handles A2UI↔A2A message conversion, so agents built with ADK can send rich UI to any A2UI-capable client.
ADK integrated the A2UI v0.8 basic catalog to automatically render spec-compliant agent parts as native UI components directly in the chat. ADK also handles A2UI↔A2A message conversion, so agents built with ADK can send rich UI to any A2UI-capable client.

- **Built-in rendering**: ADK Web renders A2UI components natively in the dev UI.
- **A2A integration**: A2UI messages are converted between A2A DataPart metadata and ADK events.
Expand Down
6 changes: 5 additions & 1 deletion docs/ecosystem/renderers.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ These projects are not directly A2UI renderers but are closely related and do su
| ---------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **vercel-labs/json-render** (`@json-render/*`) | React, Vue, Svelte, Solid, React Native | Generative UI framework by Vercel — uses its own JSON schema (not A2UI protocol) with Zod-based component catalogs. Supports streaming, 36 pre-built shadcn/ui components, and cross-platform rendering. | [GitHub](https://github.com/vercel-labs/json-render) · [npm](https://www.npmjs.com/package/@json-render/core) · [Docs](https://json-render.dev/) |

### Ecosystem Utilities

- **[@a2ui/markdown-it](https://www.npmjs.com/package/@a2ui/markdown-it)** — Enables markdown rendering in the Text widgets of all renderers.

### Highlights

**easyops-cn/a2ui-sdk** (`@a2ui-sdk/react`) is the most fully-featured community React renderer, with 11 published versions, Radix UI primitives, Tailwind CSS styling, and a dedicated docs site. It was [announced on the A2UI discussions](https://github.com/google/A2UI/discussions/489). For the official A2UI React renderer, see [`@a2ui/react`](https://www.npmjs.com/package/@a2ui/react).
Expand All @@ -44,7 +48,7 @@ These projects are not directly A2UI renderers but are closely related and do su

**sivamrudram-eng/a2ui-react-native** is the only React Native renderer, enabling A2UI on iOS and Android via a single codebase.

**BBC6BAE9/a2ui-swift** (formerly **a2ui-swiftui**) is a native SwiftUI renderer supporting iOS, macOS, visionOS, watchOS, and tvOS. It covers all 18 standard A2UI components with dual v0.8 + v0.9 protocol support, includes JSONL streaming, and uses the Observation framework for reactivity.
**BBC6BAE9/a2ui-swift** (formerly **a2ui-swiftui**) is a native SwiftUI renderer supporting iOS, macOS, visionOS, watchOS, and tvOS. It covers all 18 basic A2UI components with dual v0.8 + v0.9 protocol support, includes JSONL streaming, and uses the Observation framework for reactivity.
Comment thread
ditman marked this conversation as resolved.

## Submitting a Renderer

Expand Down
16 changes: 8 additions & 8 deletions docs/guides/renderer-development.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ Implement the following rendering logic:
- Buffer all incoming `surfaceUpdate` and `dataModelUpdate` messages without rendering immediately.
- Handle `beginRendering`: This message acts as the explicit signal to perform the initial render of a surface and set the root component ID.
- Start rendering from the specified `root` component ID.
- If a `catalogId` is provided, ensure the corresponding component catalog is used (defaulting to the standard catalog if omitted).
- If a `catalogId` is provided, ensure the corresponding component catalog is used (defaulting to the basic catalog if omitted).
- Apply any global `styles` (e.g., `font`, `primaryColor`) provided in this message.
- **Data Binding Resolution**:
- Implement a resolver for `BoundValue` objects found in component properties.
Expand All @@ -113,28 +113,28 @@ Implement the following communication features:
- Send the complete `userAction` object to the server's event handling endpoint.
- **Client Capabilities Reporting**:
- In **every** A2A message sent to the server (as part of the metadata), include an `a2uiClientCapabilities` object.
- This object should declare the component catalog your client supports via `supportedCatalogIds` (e.g., including the URI for the standard 0.8 catalog).
- This object should declare the component catalog your client supports via `supportedCatalogIds` (e.g., including the URI for the basic 0.8 catalog).
- Optionally, if the server supports it, provide `inlineCatalogs` for custom, on-the-fly component definitions.
- **Error Reporting**: Implement a mechanism to send an `error` message to the server to report any client-side errors (e.g., failed data binding, unknown component type).

## II. Standard Component Catalog Checklist
## II. Basic Component Catalog Checklist

To ensure a consistent user experience across platforms, A2UI defines a standard set of components. Your client should map these abstract definitions to their corresponding native UI widgets.
To ensure a consistent user experience across platforms, A2UI defines a basic set of components. Your client should map these abstract definitions to their corresponding native UI widgets.

### Basic Content

The standard catalog includes the following basic content components:
The basic catalog includes the following basic content components:

- **Text**: Render text content. Must support data binding on `text` and a `usageHint` for styling (h1-h5, body, caption).
- **Image**: Render an image from a URL. Must support `fit` (cover, contain, etc.) and `usageHint` (avatar, hero, etc.) properties.
- **Icon**: Render a predefined icon from the standard set specified in the catalog.
- **Icon**: Render a predefined icon from the basic set specified in the catalog.
- **Video**: Render a video player for a given URL.
- **AudioPlayer**: Render an audio player for a given URL, optionally with a description.
- **Divider**: Render a visual separator, supporting both `horizontal` and `vertical` axes.

### Layout & Containers

The standard catalog includes the following layout and container components:
The basic catalog includes the following layout and container components:

- **Row**: Arrange children horizontally. Must support `distribution` (justify-content) and `alignment` (align-items). Children can have a `weight` property to control flex-grow behavior.
- **Column**: Arrange children vertically. Must support `distribution` and `alignment`. Children can have a `weight` property to control flex-grow behavior.
Expand All @@ -145,7 +145,7 @@ The standard catalog includes the following layout and container components:

### Interactive & Input Components

The standard catalog includes the following interactive and input components:
The basic catalog includes the following interactive and input components:

- **Button**: A clickable element that triggers a `userAction`. Must be able to contain a `child` component (typically Text or Icon) and may vary in style based on the `primary` boolean.
- **CheckBox**: A checkbox that can be toggled, reflecting a boolean value.
Expand Down
8 changes: 4 additions & 4 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,10 @@ A2UI enables AI agents to generate rich, interactive user interfaces that render

## Specification Versions

| Version | Status | Description |
| -------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[v0.8](specification/v0.8-a2ui.md)** | **Stable** | Current production release. Surfaces, components, data binding, adjacency list model. |
| **[v0.9](specification/v0.9-a2ui.md)** | **Draft** | Adds `createSurface`, client-side functions, custom catalogs, and the extension specification. [Evolution guide →](specification/v0.9-evolution-guide.md) |
| Version | Status | Description |
| -------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **[v0.8](specification/v0.8-a2ui.md)** | **Stable** | Current production release. Surfaces, components, data binding, adjacency list model. |
| **[v0.9](specification/v0.9-a2ui.md)** | **Current** | Adds `createSurface`, client-side functions, custom catalogs, and the extension specification. [Evolution guide →](specification/v0.9-evolution-guide.md) |

A2UI is Apache 2.0 licensed,
created by Google with contributions from CopilotKit and the open source community,
Expand Down
2 changes: 1 addition & 1 deletion docs/introduction/what-is-a2ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ A2UI: JSON messages describing UI that:
}
```

=== "v0.9 (Draft)"
=== "v0.9 (Current)"

```jsonl
{
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ Display images from URLs.

### Icon

Display icons from the standard set defined in the catalog.
Display icons from the basic set defined in the catalog.

=== "v0.8"

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Signals the client to initialize and render a surface.
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `surfaceId` | string | ✅ | Unique identifier for this surface. |
| `root` | string | ✅ | The `id` of the component that should be the root of the UI tree for this surface. |
| `catalogId` | string | ❌ | Identifier for the component catalog. Defaults to the v0.8 standard catalog if omitted. |
| `catalogId` | string | ❌ | Identifier for the component catalog. Defaults to the v0.8 basic catalog if omitted. |
| `styles` | object | ❌ | Styling information for the UI, as defined by the catalog. |

### Example
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/renderers.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ You have a lot of flexibility, to bring custom components to a renderer, or buil

| Renderer | Platform | v0.8 | v0.9 | Links |
| ------------------------ | ------------------ | --------- | --------- | ------------------------------------------------------------------------------------ |
| **React** | Web | ✅ Stable | | [Code](https://github.com/google/A2UI/tree/main/renderers/react) |
| **React** | Web | ✅ Stable | ✅ Stable | [Code](https://github.com/google/A2UI/tree/main/renderers/react) |
| **Lit (Web Components)** | Web | ✅ Stable | ✅ Stable | [Code](https://github.com/google/A2UI/tree/main/renderers/lit) |
| **Angular** | Web | ✅ Stable | ✅ Stable | [Code](https://github.com/google/A2UI/tree/main/renderers/angular) |
| **Flutter (GenUI SDK)** | Mobile/Desktop/Web | ✅ Stable | ✅ Stable | [Docs](https://docs.flutter.dev/ai/genui) · [Code](https://github.com/flutter/genui) |
Expand Down
Loading
Loading