diff --git a/docs/concepts/components.md b/docs/concepts/components.md index 79d97bfa..877d4416 100644 --- a/docs/concepts/components.md +++ b/docs/concepts/components.md @@ -5,11 +5,13 @@ A2UI uses an **adjacency list model** for component hierarchies. Instead of nest ## Why Flat Lists? **Traditional nested approach:** + - LLM must generate perfect nesting in one pass - Hard to update deeply nested components - Difficult to stream incrementally **A2UI adjacency list:** + - ✅ Flat structure, easy for LLMs to generate - ✅ Send components incrementally - ✅ Update any component by ID @@ -39,7 +41,7 @@ Components reference children by ID, not by nesting. Every component has: -1. **ID**: Unique identifier (`"welcome-message"`) +1. **ID**: Unique identifier (`"welcome"`) 2. **Type**: Component type (`Text`, `Button`, `Card`) 3. **Properties**: Configuration specific to that type @@ -76,8 +78,8 @@ For each item in `/items`, render the `item-template`. See [Data Binding](data-b Components get their values two ways: -**Literal** - Fixed value: `{"text": {"literalString": "Welcome"}}` -**Data-bound** - From data model: `{"text": {"path": "/user/name"}}` +- **Literal** - Fixed value: `{"text": {"literalString": "Welcome"}}` +- **Data-bound** - From data model: `{"text": {"path": "/user/name"}}` LLMs can generate components with literal values or bind them to data paths for dynamic content. @@ -94,9 +96,9 @@ A surface is a complete, cohesive UI (form, dashboard, chat, etc.). ## Incremental Updates -**Add** - Send new `surfaceUpdate` with new component IDs -**Update** - Send `surfaceUpdate` with existing ID and new properties -**Remove** - Update parent's `children` list to exclude removed IDs +- **Add** - Send new `surfaceUpdate` with new component IDs +- **Update** - Send `surfaceUpdate` with existing ID and new properties +- **Remove** - Update parent's `children` list to exclude removed IDs The flat structure makes all updates simple ID-based operations. diff --git a/docs/concepts/data-binding.md b/docs/concepts/data-binding.md index 54da691f..a97448d6 100644 --- a/docs/concepts/data-binding.md +++ b/docs/concepts/data-binding.md @@ -64,8 +64,8 @@ Components bound to data paths automatically update when the data changes: {"id": "status", "component": {"Text": {"text": {"path": "/order/status"}}}} ``` -**Initial:** `/order/status` = "Processing..." → displays "Processing..." -**Update:** Send `dataModelUpdate` with `status: "Shipped"` → displays "Shipped" +- **Initial:** `/order/status` = "Processing..." → displays "Processing..." +- **Update:** Send `dataModelUpdate` with `status: "Shipped"` → displays "Shipped" No component updates needed—just data updates. @@ -99,8 +99,8 @@ Inside a template, paths are scoped to the array item: {"id": "product-name", "component": {"Text": {"text": {"path": "/name"}}}} ``` -For `/products/0`, `/name` resolves to `/products/0/name` → "Widget" -For `/products/1`, `/name` resolves to `/products/1/name` → "Gadget" +- For `/products/0`, `/name` resolves to `/products/0/name` → "Widget" +- For `/products/1`, `/name` resolves to `/products/1/name` → "Gadget" Adding/removing items automatically updates the rendered components. diff --git a/docs/concepts/data-flow.md b/docs/concepts/data-flow.md index 6bd81eab..99fe1bc8 100644 --- a/docs/concepts/data-flow.md +++ b/docs/concepts/data-flow.md @@ -22,7 +22,9 @@ A2UI defines a sequence of JSON messages that describe the UI. When streamed, th {"beginRendering":{"surfaceId":"main","root":"root-component"}} ``` -**Why this format?** A sequence of self-contained JSON objects is streaming-friendly, easy for LLMs to generate incrementally, and resilient to errors. +**Why this format?** + +A sequence of self-contained JSON objects is streaming-friendly, easy for LLMs to generate incrementally, and resilient to errors. ## Lifecycle Example: Restaurant Booking @@ -80,11 +82,11 @@ Users see UI building in real-time instead of staring at a spinner. ## Error Handling -**Malformed messages:** Skip and continue, or send error back to agent for correction -**Network interruptions:** Display error state, reconnect, agent resends or resumes +- **Malformed messages:** Skip and continue, or send error back to agent for correction +- **Network interruptions:** Display error state, reconnect, agent resends or resumes ## Performance -**Batching:** Buffer updates for 16ms, batch render together -**Diffing:** Compare old/new components, update only changed properties -**Granular updates:** Update `/user/name` not entire `/` model +- **Batching:** Buffer updates for 16ms, batch render together +- **Diffing:** Compare old/new components, update only changed properties +- **Granular updates:** Update `/user/name` not entire `/` model diff --git a/docs/introduction/who-is-it-for.md b/docs/introduction/who-is-it-for.md index 45be6fd2..f4cbf4d4 100644 --- a/docs/introduction/who-is-it-for.md +++ b/docs/introduction/who-is-it-for.md @@ -52,15 +52,15 @@ Do you ship your agent into other apps you don't necessarily control? ## When to Use A2UI -✅ **Agent-generated UI** - Core purpose -✅ **Multi-agent systems** - Standard protocol across trust boundaries -✅ **Cross-platform apps** - One agent, many renderers (web/mobile/desktop) -✅ **Security critical** - Declarative data, no code execution -✅ **Brand consistency** - Client controls styling - -❌ **Static websites** - Use HTML/CSS -❌ **Simple text-only chat** - Use Markdown -❌ **Remote widgets not integrated with client** - Use iframes, like MCP Apps +- ✅ **Agent-generated UI** - Core purpose +- ✅ **Multi-agent systems** - Standard protocol across trust boundaries +- ✅ **Cross-platform apps** - One agent, many renderers (web/mobile/desktop) +- ✅ **Security critical** - Declarative data, no code execution +- ✅ **Brand consistency** - Client controls styling + +- ❌ **Static websites** - Use HTML/CSS +- ❌ **Simple text-only chat** - Use Markdown +- ❌ **Remote widgets not integrated with client** - Use iframes, like MCP Apps -❌ **Rapid UI + Agent app built together** - Use AG UI / CopilotKit +- ❌ **Rapid UI + Agent app built together** - Use AG UI / CopilotKit diff --git a/docs/transports.md b/docs/transports.md index 992de634..84fbaa6a 100644 --- a/docs/transports.md +++ b/docs/transports.md @@ -71,8 +71,6 @@ You can use any transport that sends JSON: // TODO: Add an example ``` -``` - ## Next Steps - **[A2A Protocol Docs](https://a2a-protocol.org)**: Learn about A2A