docs: add A2UI basic catalog implementation guide for v0.9#823
docs: add A2UI basic catalog implementation guide for v0.9#823jacobsimionato merged 6 commits intogoogle:mainfrom
Conversation
| ### Text | ||
| Displays text content. | ||
|
|
||
| **Rendering Guidelines:** Text should be rendered using a Markdown parser when possible. If markdown rendering is unavailable or fails, gracefully fallback to rendering the raw text using the framework's default text primitive (e.g., `<span>` in HTML, `Text` in Compose/SwiftUI). |
There was a problem hiding this comment.
The spec says text supports simple markdown, so do we want to make room for renderers that don't?
Because raw Markdown will look really odd to someone who doesn't know what it is. I mean, it's readable (the whole point of the markdown standard), but it won't look how the author (human or LLM) intended.
There was a problem hiding this comment.
Agreed. Let's make the wording a little stronger, and say that the renderer should parse markdown in the text element.
| ### Video | ||
| A video player. | ||
|
|
||
| **Rendering Guidelines:** Render using a native video player component with user controls enabled. Ensure the video container spans the full width of the parent's container for responsiveness. |
There was a problem hiding this comment.
Do we want to talk about scrubbing? Is it required/allowed to enable scrubbing?
There was a problem hiding this comment.
Let's encourage scrubbing availability, though I think it's somewhat up to the implementer.
| ### AudioPlayer | ||
| An audio player. | ||
|
|
||
| **Rendering Guidelines:** Render using a native audio player component with user controls enabled. Like video, its container should span the full width of its parent. |
There was a problem hiding this comment.
Same as video re: scrubbing
| A control for selecting a numeric value within a range. | ||
|
|
||
| **Rendering Guidelines:** Render using the platform's native slider or seek bar component. Optionally display the current numeric value next to the slider track. | ||
| **Behavior & State:** Set `min` and `max` limits. Perform two-way binding, updating the numeric `value` path as the user drags the slider. |
There was a problem hiding this comment.
Might add something about the slider value: it's a number, which means it's not an integer. This is so that implementations work if the slider is 0->1 (a common case).
There was a problem hiding this comment.
Great idea.
|
|
||
| Functions provide client-side logic for validation, interpolation, and operations. As defined in the Architecture Guide, the reactivity of function arguments is generally handled by the Core Data Layer (specifically the Binder/Context layer). |
There was a problem hiding this comment.
Would it makes sense to mention web_core here? I mean, I guess that's web-only, but for most web implementations they won't want to implement their own version of the function reactivity, etc.
There was a problem hiding this comment.
Yeah good idea. Let's note that core libraries for each language typically provide a complete implementation of all the functions in the basic catalog, seeing as they are not specific to UI framework.
2 participants
Description of Changes
basic_catalog_implementation_guide.md) detailing how to visually and functionally implement the A2UI v0.9 Basic Catalog components and functions across Web, Mobile, and Desktop platforms.formatStringinterpolation engine.renderer_guide.mdto link to this new document, specifically adding it to the required ingestion context and basic catalog implementation steps for AI Agents.Rationale
Previously, the functional and visual expectations for implementing the Basic Catalog were vaguely scattered or entirely missing. Providing a detailed, framework-agnostic implementation guide ensures that developers and AI agents can build consistent, high-quality, cross-platform A2UI renderers. Specifically, codifying spacing rules and function reactivity reduces trial-and-error and ensures architectural alignment across different ecosystems.
Testing/Running Instructions
specification/v0_9/docs/basic_catalog_implementation_guide.mddocument for clarity and correctness.specification/v0_9/docs/renderer_guide.mdto ensure the integration and links are correct.