update docs to reflect new catalog guidance

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
 

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

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.

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

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)
 

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

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

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.

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
 

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.