A2UI SDK Implementation Guide (Phased Execution)
This skill provides expert instructions and sequences for AI agents or contributors tasked with implementing A2UI Core SDKs, Framework Adapters, or Agent/Inference SDKs in a new programming language or UI framework.
1. Core State SDK Phases
If you are building a new Core SDK (e.g., in Rust, Swift, Go, or C++), you must follow this sequence of phases:
Phase 1: Context & Schemas Ingestion
Thoroughly review:
blueprints/modules/a2ui_core.blueprint.md (for state and message structures).
specification/v1_0/json/common_types.json (dynamic binding schemas).
specification/v1_0/json/server_to_client.json (message envelopes).
specification/v1_0/catalogs/basic/catalog.json (target components catalog).
Phase 2: Technical Architecture Planning
Create a detailed, local architectural proposal detailing:
- Dependencies: Which Schema library and Observable/Reactive library will you use? Note that the reactive library must support both discrete event subscription and stateful, signal-like data streams (e.g., BehaviorSubject/Signal).
- Component APIs: How will you define the
ComponentApi interface in this language?
- Binding Strategy: How will you structure the abstract Core Binder Layer?
- STOP and obtain human reviewer approval on this plan before writing code.
Phase 3: Core Model Layer
Implement the framework-agnostic data and processor layers:
- Observables & Signals: Implement multi-cast reactive streams with clear unsubscribe mechanism to prevent leaks.
- Protocol Structures: Create strictly-typed native classes/structs representing
A2uiMessage envelopes and client capabilities with serialization/deserialization.
- DataModel & JSON Pointers: Implement relative/absolute path resolution, auto-vivification (auto-typing intermediate segments), and bubble/cascade path change notifications.
- Core State Models: Implement
ComponentModel, SurfaceComponentsModel, SurfaceModel, and SurfaceGroupModel.
- Context Mapping: Implement
DataContext and ComponentContext.
- MessageProcessor: Ingest incoming messages and mutate the state models. Generate
inlineCatalogs client capabilities.
- Verification: Write comprehensive unit tests for pointer cascading, JSON deserialization/validation, and message dispatching.
Phase 4: Foundational Basic Catalog Support
Bootstrap support for the Basic Catalog:
- Foundational Components: Define the pure API schemas and Binders for:
Text, Row, Column, Button, and TextField.
- Foundational Functions: Implement
formatString to interpret ${expression} syntaxes, supporting recursive token evaluations and reactive coercion.
- Verification: Ensure properties update reactively when underlying data paths emit notifications.
Phase 5: Complete Basic Catalog Support
- Full Components & Binders: Define core binders for all other components in
basic/catalog.json.
- Full Functions: Implement remaining basic mathematical, logical, and array operations.
- Validation: Ensure strict type coercion rules are satisfied and memory disposals work flawlessly.
2. Framework Adapter SDK Phases
If you are building a new UI Framework Adapter / Renderer (e.g., in Flutter/Dart, SwiftUI, Jetpack Compose, Vue, or Svelte), follow this sequence:
Phase 1: Ingestion & Core Integration
Review:
blueprints/modules/a2ui_framework_adapter.blueprint.md (View and rendering architecture).
specification/v1_0/docs/basic_catalog_implementation_guide.md (spacing, alignment, and typography specifications).
Phase 2: Architectural Plan
Draft a plan specifying:
- Component Registry: How components are dynamically resolved and instantiated.
- Surface Widget: How the root canvas mounts and recurses through the layout tree starting at
root.
- Observer/State Bridge: Which Strategy (Direct, Predefined Binders, or Automated wrappers) will connect core signals to native views.
- STOP and obtain human reviewer approval on this plan.
Phase 3: Adapter & Lifecycle Layer
- Implement
ComponentImplementation base traits/classes.
- Implement the framework-native
Surface entrypoint widget.
- Implement subscription management: lazy-subscribing only on mount, handling path stability updates, and strictly calling
dispose() on unmount.
Phase 4: Bootstrapping Basic Catalog Rendering
- Build native visual elements for:
Text, Row, Column, Button, and TextField.
- Bundle these elements into the first framework catalog adapter.
- Verify reactive layout properties dynamically.
Phase 5: Gallery Application Milestone
Build the Gallery App as a testing playground with:
- Left Column: Sample navigation.
- Center Column: Surface preview, JSON message stream, and step-by-step interactive message stepper.
- Right Column: Live data model inspect pane and action logger.
- Load the 5 foundational verification examples:
00_simple-text.json, 00_row-layout.json, 00_complex-layout.json, 00_interactive-button.json, and 00_simple-login-form.json.
- STOP and obtain human reviewer approval of the UI and visual rendering performance.
Phase 6: Full Catalog Support
- Implement all remaining widgets (e.g. Card, Image, List, etc.) and validation traits like
Checkable.
- Update the Gallery App to support all official examples in
specification/v1_0/catalogs/basic/examples/.
- Run visual parity and event action tests to verify correctness.
1---2name: a2ui-implement-new-sdks-for-client-language3description: Step-by-step phased instructions for building new A2UI Core SDKs, Framework Adapters, and Inference SDKs from scratch in any client language.4metadata:5 source: https://skillmd.com/skills/google/a2ui-implement-new-sdks-for-client-language6---78# A2UI SDK Implementation Guide (Phased Execution)910This skill provides expert instructions and sequences for AI agents or contributors tasked with implementing A2UI Core SDKs, Framework Adapters, or Agent/Inference SDKs in a new programming language or UI framework.1112---1314## **1. Core State SDK Phases**1516If you are building a new **Core SDK** (e.g., in Rust, Swift, Go, or C++), you must follow this sequence of phases:1718### **Phase 1: Context & Schemas Ingestion**1920Thoroughly review:2122- `blueprints/modules/a2ui_core.blueprint.md` (for state and message structures).23- `specification/v1_0/json/common_types.json` (dynamic binding schemas).24- `specification/v1_0/json/server_to_client.json` (message envelopes).25- `specification/v1_0/catalogs/basic/catalog.json` (target components catalog).2627### **Phase 2: Technical Architecture Planning**2829Create a detailed, local architectural proposal detailing:3031- **Dependencies**: Which Schema library and Observable/Reactive library will you use? Note that the reactive library must support both discrete event subscription and stateful, signal-like data streams (e.g., BehaviorSubject/Signal).32- **Component APIs**: How will you define the `ComponentApi` interface in this language?33- **Binding Strategy**: How will you structure the abstract Core Binder Layer?34- _STOP and obtain human reviewer approval on this plan before writing code._3536### **Phase 3: Core Model Layer**3738Implement the framework-agnostic data and processor layers:39401. **Observables & Signals**: Implement multi-cast reactive streams with clear unsubscribe mechanism to prevent leaks.412. **Protocol Structures**: Create strictly-typed native classes/structs representing `A2uiMessage` envelopes and client capabilities with serialization/deserialization.423. **DataModel & JSON Pointers**: Implement relative/absolute path resolution, auto-vivification (auto-typing intermediate segments), and bubble/cascade path change notifications.434. **Core State Models**: Implement `ComponentModel`, `SurfaceComponentsModel`, `SurfaceModel`, and `SurfaceGroupModel`.445. **Context Mapping**: Implement `DataContext` and `ComponentContext`.456. **MessageProcessor**: Ingest incoming messages and mutate the state models. Generate `inlineCatalogs` client capabilities.467. **Verification**: Write comprehensive unit tests for pointer cascading, JSON deserialization/validation, and message dispatching.4748### **Phase 4: Foundational Basic Catalog Support**4950Bootstrap support for the Basic Catalog:5152- **Foundational Components**: Define the pure API schemas and Binders for: `Text`, `Row`, `Column`, `Button`, and `TextField`.53- **Foundational Functions**: Implement `formatString` to interpret `${expression}` syntaxes, supporting recursive token evaluations and reactive coercion.54- **Verification**: Ensure properties update reactively when underlying data paths emit notifications.5556### **Phase 5: Complete Basic Catalog Support**5758- **Full Components & Binders**: Define core binders for all other components in `basic/catalog.json`.59- **Full Functions**: Implement remaining basic mathematical, logical, and array operations.60- **Validation**: Ensure strict type coercion rules are satisfied and memory disposals work flawlessly.6162---6364## **2. Framework Adapter SDK Phases**6566If you are building a new **UI Framework Adapter / Renderer** (e.g., in Flutter/Dart, SwiftUI, Jetpack Compose, Vue, or Svelte), follow this sequence:6768### **Phase 1: Ingestion & Core Integration**6970Review:7172- `blueprints/modules/a2ui_framework_adapter.blueprint.md` (View and rendering architecture).73- `specification/v1_0/docs/basic_catalog_implementation_guide.md` (spacing, alignment, and typography specifications).7475### **Phase 2: Architectural Plan**7677Draft a plan specifying:7879- **Component Registry**: How components are dynamically resolved and instantiated.80- **Surface Widget**: How the root canvas mounts and recurses through the layout tree starting at `root`.81- **Observer/State Bridge**: Which Strategy (Direct, Predefined Binders, or Automated wrappers) will connect core signals to native views.82- _STOP and obtain human reviewer approval on this plan._8384### **Phase 3: Adapter & Lifecycle Layer**8586- Implement `ComponentImplementation` base traits/classes.87- Implement the framework-native `Surface` entrypoint widget.88- Implement subscription management: lazy-subscribing only on mount, handling path stability updates, and strictly calling `dispose()` on unmount.8990### **Phase 4: Bootstrapping Basic Catalog Rendering**9192- Build native visual elements for: `Text`, `Row`, `Column`, `Button`, and `TextField`.93- Bundle these elements into the first framework catalog adapter.94- Verify reactive layout properties dynamically.9596### **Phase 5: Gallery Application Milestone**9798Build the **Gallery App** as a testing playground with:99100- Left Column: Sample navigation.101- Center Column: Surface preview, JSON message stream, and step-by-step interactive message stepper.102- Right Column: Live data model inspect pane and action logger.103- Load the 5 foundational verification examples: `00_simple-text.json`, `00_row-layout.json`, `00_complex-layout.json`, `00_interactive-button.json`, and `00_simple-login-form.json`.104- _STOP and obtain human reviewer approval of the UI and visual rendering performance._105106### **Phase 6: Full Catalog Support**107108- Implement all remaining widgets (e.g. Card, Image, List, etc.) and validation traits like `Checkable`.109- Update the Gallery App to support all official examples in `specification/v1_0/catalogs/basic/examples/`.110- Run visual parity and event action tests to verify correctness.