diff --git a/docs/concepts/components.md b/docs/concepts/components.md index 0b1cb6c36..27fd29648 100644 --- a/docs/concepts/components.md +++ b/docs/concepts/components.md @@ -169,14 +169,11 @@ Every component has: } ``` -## The Standard Catalog +## The Basic Catalog -A2UI defines a standard catalog of components organized by purpose: +To help developers get started quickly, the A2UI team maintains the [Basic Catalog](../specification/v0_9/json/basic_catalog.json). -- **Layout**: Row, Column, List - arrange other components -- **Display**: Text, Image, Icon, Video, Divider - show information -- **Interactive**: Button, TextField, CheckBox, DateTimeInput, Slider - user input -- **Container**: Card, Tabs, Modal - group and organize content +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. For the complete component gallery with examples, see [Component Reference](../reference/components.md). @@ -242,17 +239,13 @@ A surface is a complete, cohesive UI (form, dashboard, chat, etc.). The flat structure makes all updates simple ID-based operations. -## Custom Components +## Defining Your Own Catalog -Beyond the standard catalog, clients can define custom components for domain-specific needs: +While the Basic Catalog is useful for starting out, most production applications will define their own catalog to reflect their specific design system. -- **How**: Register custom component types in your renderer -- **What**: Charts, maps, custom visualizations, specialized widgets -- **Security**: Custom components still part of the client's trusted catalog +By defining your own catalog, you restrict the agent to using exactly the components and visual language that exist in your application, rather than generic inputs or buttons. -Custom components are _advertised_ from the client's renderer to the LLM. The LLM can then use them in addition to the standard catalog. - -See [Custom Components Guide](../guides/custom-components.md) for implementation details. +See [Defining Your Own Catalog Guide](../guides/defining-your-own-catalog.md) for implementation details. ## Best Practices diff --git a/docs/guides/client-setup.md b/docs/guides/client-setup.md index 5f019e9f5..05e9e5523 100644 --- a/docs/guides/client-setup.md +++ b/docs/guides/client-setup.md @@ -15,9 +15,9 @@ Integrate A2UI into your application using the renderer for your platform. ## Component Catalogs -A component catalog is any collection of components — standard ones, your custom components, or shared libraries. **Your design system is what matters.** You can register any collection of components and functions, and A2UI will work with them. The catalog is just the contract between your agent and your renderer. +A component catalog is any collection of components — the Basic Catalog, your own components, or shared libraries. **Your design system is what matters.** You can register any collection of components and functions, and A2UI will work with them. The catalog is just the contract between your agent and your renderer. -See [Custom Components](custom-components.md) for how to extend or replace the standard catalog. +See [Defining Your Own Catalog](defining-your-own-catalog.md) for how to define a catalog that matches your design system. ## Shared Web Library @@ -161,6 +161,6 @@ TODO: Add error handling examples. - **[Quickstart](../quickstart.md)**: Try the demo application - **[Theming & Styling](theming.md)**: Customize the look and feel -- **[Custom Components](custom-components.md)**: Extend the component catalog +- **[Defining Your Own Catalog](defining-your-own-catalog.md)**: Extend the component catalog - **[Agent Development](agent-development.md)**: Build agents that generate A2UI - **[Reference Documentation](../reference/messages.md)**: Deep dive into the protocol diff --git a/docs/guides/custom-components.md b/docs/guides/custom-components.md deleted file mode 100644 index 4f1c4a022..000000000 --- a/docs/guides/custom-components.md +++ /dev/null @@ -1,84 +0,0 @@ -# Custom Component Catalogs - -Extend A2UI by defining **custom catalogs** that include your own components alongside standard A2UI components. - -## Why Custom Catalogs? - -The A2UI Standard Catalog provides common UI elements (buttons, text fields, etc.), but your application might need specialized components: - -- **Domain-specific widgets**: Stock tickers, medical charts, CAD viewers -- **Third-party integrations**: Google Maps, payment forms, chat widgets -- **Brand-specific components**: Custom date pickers, product cards, dashboards - -**Custom catalogs** are collections of components that can include: -- Standard A2UI components (Text, Button, TextField, etc.) -- Your custom components (GoogleMap, StockTicker, etc.) -- Third-party components - -You register entire catalogs with your client application, not individual components. This allows agents and clients to agree on a shared, extended set of components while maintaining security and type safety. - -## How Custom Catalogs Work - -1. **Client Defines Catalog**: You create a catalog definition that lists both standard and custom components. -2. **Client Registers Catalog**: You register the catalog (and its component implementations) with your client app. -3. **Client Announces Support**: The client informs the agent which catalogs it supports. -4. **Agent Selects Catalog**: The agent chooses a catalog for a given UI surface. -5. **Agent Generates UI**: The agent generates component messages (`surfaceUpdate` in v0.8, `updateComponents` in v0.9) using components from that catalog by name. - -## Defining Custom Catalogs - -TODO: Add detailed guide for defining custom catalogs for each platform. - -**Web (Lit / Angular):** - -- [Authoring Custom Components](authoring-components.md): A detailed guide using Angular and rizzcharts as an example. -- How to define a catalog with both standard and custom components in Lit -- How to register the catalog with the A2UI client in Lit - - -**Flutter:** - -- How to define custom catalogs using GenUI -- How to register custom component renderers - -**See working examples:** - -- [Lit samples](https://github.com/google/a2ui/tree/main/samples/client/lit) -- [Angular samples](https://github.com/google/a2ui/tree/main/samples/client/angular) -- [Flutter GenUI docs](https://docs.flutter.dev/ai/genui) - -## Agent-Side: Using Components from a Custom Catalog - -Once a catalog is registered on the client, agents can use components from it in `surfaceUpdate` messages. - -The agent specifies which catalog to use via the `catalogId` in the `beginRendering` message. - -TODO: Add examples of: - -- How agents select catalogs -- How agents reference custom components from catalogs -- How catalog versioning works - -## Data Binding and Actions - -Custom components support the same data binding and action mechanisms as standard components: - -- **Data binding**: Custom components can bind properties to data model paths using JSON Pointer syntax -- **Actions**: Custom components can emit actions that the agent receives and handles - -## Security Considerations - -When creating custom catalogs and components: - -1. **Allowlist components**: Only register components you trust in your catalogs -2. **Validate properties**: Always validate component properties from agent messages -3. **Sanitize user input**: If components accept user input, sanitize it before processing -4. **Limit API access**: Don't expose sensitive APIs or credentials to custom components - -TODO: Add detailed security best practices and code examples. - -## Next Steps - -- **[Theming & Styling](theming.md)**: Customize the look and feel of components -- **[Component Reference](../reference/components.md)**: See all standard components -- **[Agent Development](agent-development.md)**: Build agents that use custom components diff --git a/docs/guides/defining-your-own-catalog.md b/docs/guides/defining-your-own-catalog.md new file mode 100644 index 000000000..4570009ef --- /dev/null +++ b/docs/guides/defining-your-own-catalog.md @@ -0,0 +1,58 @@ +# Defining Your Own Catalog + +While the [Basic Catalog](../specification/v0_9/json/basic_catalog.json) is useful for starting out and bootstrapping an application, most production applications will define their own catalog to reflect their specific design system. + +By defining your own catalog, you restrict the agent to using exactly the components and visual language that exist in your application, rather than generic inputs or buttons. + +## Why Define Your Own Catalog? + +Every A2UI surface is driven by a **Catalog**. A catalog is simply a JSON Schema file that tells the agent which components, functions, and themes are available for it to use. + +- **Design System Alignment**: Restrict the agent to using exactly the components and visual language that exist in your application. +- **Security and Type Safety**: You register entire catalogs with your client application, ensuring that only trusted components are rendered. +- **No Mappers Needed**: We recommend building catalogs that directly reflect your client's design system rather than trying to map a generic catalog (like the Basic Catalog) to it through an adapter. + +The Basic Catalog is just one example and is intentionally sparse to remain easily implementable by different renderers. + +## How It Works + +1. **Define the Catalog**: Create a catalog definition (JSON Schema) listing the components, functions, and styles your application supports. +2. **Register the Catalog**: Register the catalog and its corresponding component implementations (renderers) with your client application. +3. **Announce Support**: The client informs the agent which catalogs it supports (via `supportedCatalogIds`). +4. **Agent Selects Catalog**: The agent chooses a catalog for a given UI surface (via `catalogId` inside the creation message, like `createSurface`). +5. **Agent Generates UI**: The agent generates component messages using the components defined in that catalog by name. + +## Implementation Guide + +We recommend creating catalogs that directly map to your existing component library. + +=== "Web (Lit / Angular / React)" + + To implement your own catalog on the web: + - Create a JSON Schema containing your component definitions. + - Register your components with the `@a2ui/web` client. + - Provide the schema or reference ID to the agent. + + *Detailed guides for each framework coming soon.* + +=== "Flutter" + + To implement your own catalog in Flutter: + - Define a JSON Schema describing your widget properties. + - Map the schema to Flutter widgets using a custom renderer. + + *Detailed Flutter integration guide coming soon.* + +## Security Considerations + +When defining and registering catalogs: + +1. **Allowlist components**: Only register components you trust in your catalog definition. Don't expose components that offer dangerous capabilities (e.g., executing arbitrary scripts) unless strictly controlled. +2. **Validate properties**: Always validate component properties from agent messages to ensure they match expected type constraints. +3. **Sanitize text**: Avoid rendering un-sanitized content provided by the agent unless safe bounds are established. + +## Next Steps + +- **[Theming & Styling](theming.md)**: Customize the look and feel of components. +- **[Component Reference](../reference/components.md)**: Explore standard types that might be available for reuse. +- **[Agent Development](agent-development.md)**: Build agents that interact with your Catalog. diff --git a/docs/guides/theming.md b/docs/guides/theming.md index d51f556f2..46c3fab5d 100644 --- a/docs/guides/theming.md +++ b/docs/guides/theming.md @@ -182,6 +182,6 @@ Define reusable design tokens (colors, spacing, etc.) and reference them through ## Next Steps -- **[Custom Components](custom-components.md)**: Build custom components with your styling +- **[Defining Your Own Catalog](defining-your-own-catalog.md)**: Build custom components with your styling - **[Component Reference](../reference/components.md)**: See styling options for all components - **[Client Setup](client-setup.md)**: Set up the renderer in your app diff --git a/docs/introduction/who-is-it-for.md b/docs/introduction/who-is-it-for.md index 305b91ebd..e1c40c4aa 100644 --- a/docs/introduction/who-is-it-for.md +++ b/docs/introduction/who-is-it-for.md @@ -16,7 +16,7 @@ Build multi-agent platforms, enterprise assistants, or cross-platform apps where - Cross-platform: web, mobile, desktop - Interoperable: open source, same spec with multiple renderers -**Get started:** [Client Setup](../guides/client-setup.md) | [Theming](../guides/theming.md) | [Custom Components](../guides/custom-components.md) +**Get started:** [Client Setup](../guides/client-setup.md) | [Theming](../guides/theming.md) | [Defining Your Own Catalog](../guides/defining-your-own-catalog.md) ### 2. Agent Developers (Backend/AI) diff --git a/docs/reference/components.md b/docs/reference/components.md index f8703afaf..36f252606 100644 --- a/docs/reference/components.md +++ b/docs/reference/components.md @@ -646,5 +646,5 @@ npm start -- gallery [:material-code-json: Basic Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_9/basic_catalog.json) -- **[Custom Components Guide](../guides/custom-components.md)**: Build your own components +- **[Defining Your Own Catalog](../guides/defining-your-own-catalog.md)**: Build your own components - **[Theming Guide](../guides/theming.md)**: Style components to match your brand diff --git a/mkdocs.yaml b/mkdocs.yaml index 0d0486b6b..d7c041d92 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -52,10 +52,9 @@ nav: - Client Setup: guides/client-setup.md - Agent Development: guides/agent-development.md - Renderer Development: guides/renderer-development.md - - Custom Components: guides/custom-components.md + - Defining Your Own Catalog: guides/defining-your-own-catalog.md - Authoring Custom Components: guides/authoring-components.md - Theming & Styling: guides/theming.md - - A2UI over MCP: guides/a2ui_over_mcp.md - Reference: - Component Gallery: reference/components.md diff --git a/specification/v0_10/docs/a2ui_custom_functions.md b/specification/v0_10/docs/a2ui_custom_functions.md index 3538221cb..e31806e8c 100644 --- a/specification/v0_10/docs/a2ui_custom_functions.md +++ b/specification/v0_10/docs/a2ui_custom_functions.md @@ -1,14 +1,12 @@ -# Extending A2UI with Custom Functions +# Defining Custom Functions -A2UI functions are designed to be extensible. Third-party developers can define -their own function catalogs. +A2UI functions are defined inside a Catalog. When defining your own catalog, you can include custom functions that are specific to your application or design system. -This guide demonstrates how to create a `custom_catalog.json` that adds a string -`trim` function and a hardware query function (`getScreenResolution`). +This guide demonstrates how to define a string `trim` function and a hardware query function (`getScreenResolution`) in your catalog. -## 1. Define the Custom Catalog +## 1. Define the Catalog -Create a JSON Schema file (e.g., `custom_catalog.json`) that defines your +Create a JSON Schema file (e.g., `my_catalog.json`) that defines your function parameters. Use the `functions` property to define a map of function schemas. diff --git a/specification/v0_10/docs/a2ui_protocol.md b/specification/v0_10/docs/a2ui_protocol.md index 3026e3230..2c463d366 100644 --- a/specification/v0_10/docs/a2ui_protocol.md +++ b/specification/v0_10/docs/a2ui_protocol.md @@ -146,15 +146,15 @@ The [`server_to_client.json`] envelope schema is designed to be catalog-agnostic To validate A2UI messages: 1. **Basic Catalog**: Map `catalog.json` to `basic_catalog.json`. -2. **Custom Catalog**: Map `catalog.json` to your custom catalog file (e.g., `my_custom_catalog.json`). +2. **Client Catalog**: Map `catalog.json` to your own catalog file (e.g., `my_company_catalog.json`). This indirection allows the same core envelope schema to be used with any compliant component catalog without modification. -Custom catalogs can be used to define additional UI components or modify the behavior of existing components. To use a custom catalog, simply include it in the prompt in place of the basic catalog. It should have the same form as the basic catalog, and use common elements in the [`common_types.json`] schema. +Defining your own catalog allows you to restrict the agent to using exactly the components and visual language that exist in your application. To use your own catalog, simply include it in the prompt in place of the basic catalog. It should have the same form as the basic catalog and use common elements in the [`common_types.json`] schema. -### Validator compliance & custom catalogs +### Validator compliance when defining catalogs -To ensure that automated validators can verify the integrity of your UI tree (checking that parents reference existing children), custom catalogs MUST adhere to the following strict typing rules: +To ensure that automated validators can verify the integrity of your UI tree (checking that parents reference existing children), any catalog you define MUST adhere to the following strict typing rules: 1. **Single child references:** Any property that holds the ID of another component MUST use the `ComponentId` type defined in `common_types.json`. - Use: `"$ref": "common_types.json#/$defs/ComponentId"` @@ -347,7 +347,7 @@ This structure is designed to be both flexible and strictly validated. ### The component catalog -The set of available UI components and functions is defined in a **Catalog**. The basic catalog is defined in [`basic_catalog.json`]. This allows for different clients to support different sets of components and functions, including custom ones. Advanced use cases may want to define their own custom catalogs to support custom front end design systems or renderers. The server must generate messages that conform to the catalog understood by the client. +The set of available UI components and functions is defined in a **Catalog**. The basic catalog is defined in [`basic_catalog.json`]. While the Basic Catalog is useful for starting out, most production applications will define their own catalog to reflect their specific design system. The server must generate messages that conform to the catalog understood by the client. ### UI composition: the adjacency list model diff --git a/specification/v0_9/docs/a2ui_custom_functions.md b/specification/v0_9/docs/a2ui_custom_functions.md index 3538221cb..e31806e8c 100644 --- a/specification/v0_9/docs/a2ui_custom_functions.md +++ b/specification/v0_9/docs/a2ui_custom_functions.md @@ -1,14 +1,12 @@ -# Extending A2UI with Custom Functions +# Defining Custom Functions -A2UI functions are designed to be extensible. Third-party developers can define -their own function catalogs. +A2UI functions are defined inside a Catalog. When defining your own catalog, you can include custom functions that are specific to your application or design system. -This guide demonstrates how to create a `custom_catalog.json` that adds a string -`trim` function and a hardware query function (`getScreenResolution`). +This guide demonstrates how to define a string `trim` function and a hardware query function (`getScreenResolution`) in your catalog. -## 1. Define the Custom Catalog +## 1. Define the Catalog -Create a JSON Schema file (e.g., `custom_catalog.json`) that defines your +Create a JSON Schema file (e.g., `my_catalog.json`) that defines your function parameters. Use the `functions` property to define a map of function schemas. diff --git a/specification/v0_9/docs/a2ui_protocol.md b/specification/v0_9/docs/a2ui_protocol.md index 0caf57d60..f77d5a61c 100644 --- a/specification/v0_9/docs/a2ui_protocol.md +++ b/specification/v0_9/docs/a2ui_protocol.md @@ -151,15 +151,15 @@ The [`server_to_client.json`] envelope schema is designed to be catalog-agnostic To validate A2UI messages: 1. **Basic Catalog**: Map `catalog.json` to `basic_catalog.json`. -2. **Custom Catalog**: Map `catalog.json` to your custom catalog file (e.g., `my_custom_catalog.json`). +2. **Client Catalog**: Map `catalog.json` to your own catalog file (e.g., `my_company_catalog.json`). This indirection allows the same core envelope schema to be used with any compliant component catalog without modification. -Custom catalogs can be used to define additional UI components or modify the behavior of existing components. To use a custom catalog, simply include it in the prompt in place of the basic catalog. It should have the same form as the basic catalog, and use common elements in the [`common_types.json`] schema. +Defining your own catalog allows you to restrict the agent to using exactly the components and visual language that exist in your application. To use your own catalog, simply include it in the prompt in place of the basic catalog. It should have the same form as the basic catalog and use common elements in the [`common_types.json`] schema. -### Validator compliance & custom catalogs +### Validator compliance when defining catalogs -To ensure that automated validators can verify the integrity of your UI tree (checking that parents reference existing children), custom catalogs MUST adhere to the following strict typing rules: +To ensure that automated validators can verify the integrity of your UI tree (checking that parents reference existing children), any catalog you define MUST adhere to the following strict typing rules: 1. **Single child references:** Any property that holds the ID of another component MUST use the `ComponentId` type defined in `common_types.json`. - Use: `"$ref": "common_types.json#/$defs/ComponentId"` @@ -307,7 +307,7 @@ This structure is designed to be both flexible and strictly validated. ### The component catalog -The set of available UI components and functions is defined in a **Catalog**. The basic catalog is defined in [`basic_catalog.json`]. This allows for different clients to support different sets of components and functions, including custom ones. Advanced use cases may want to define their own custom catalogs to support custom front end design systems or renderers. The server must generate messages that conform to the catalog understood by the client. +The set of available UI components and functions is defined in a **Catalog**. The basic catalog is defined in [`basic_catalog.json`]. While the Basic Catalog is useful for starting out, most production applications will define their own catalog to reflect their specific design system. The server must generate messages that conform to the catalog understood by the client. ### UI composition: the adjacency list model diff --git a/specification/v0_9/docs/renderer_guide.md b/specification/v0_9/docs/renderer_guide.md index 693472094..89405bd46 100644 --- a/specification/v0_9/docs/renderer_guide.md +++ b/specification/v0_9/docs/renderer_guide.md @@ -375,10 +375,10 @@ Functions generally fall into a few common patterns: If a function returns a reactive stream, it MUST use an idiomatic listening mechanism that supports standard unsubscription. To properly support an AI agent, functions SHOULD include a schema to generate accurate client capabilities. -### Creating Custom Catalogs -Extensibility is a core feature of A2UI. It should be trivial to create a new catalog by extending an existing one, combining custom components with the standard set. +### Composing Your Own Catalog +You can define your own catalog by composing components and functions that reflect your design system. While you can build a catalog entirely from scratch, you can also import or combine definitions with the Basic Catalog to save time. -*Example of composing a custom catalog:* +*Example of composing a catalog:* ```python # Pseudocode myCustomCatalog = Catalog(