Theming A2UI

A2UI lets an agent request semantic components while the host application controls their implementation. The agent can ask for a heading or primary button; it should not invent arbitrary CSS.

Semantic properties

The v0.9.1 Basic Catalog uses constrained properties such as the variant on Text and Button:

{"id":"warning","component":"Text","text":"Review this change","variant":"h2"}
{"id":"confirm-label","component":"Text","text":"Confirm"}
{"id":"confirm","component":"Button","child":"confirm-label","variant":"primary","action":{"event":{"name":"confirmChange"}}}

These values express intent, not pixels. The renderer maps them to the host design system’s typography, color, spacing, focus, and motion tokens.

Theme ownership

Keep the mapping in reviewed renderer or component code. The agent should not select raw class names, inject style blocks, or provide unrestricted colors and dimensions. If a custom Catalog exposes appearance options, keep them enumerated and validate them like every other property.

Dark mode is not automatic: the host must define and test a dark theme. Verify contrast, focus visibility, system color preferences, reduced motion, zoom, and high-contrast modes. Generated content can be longer than design fixtures, so test wrapping and overflow in every supported language.

Catalog-specific behavior

Theme fields and component variants can change between protocol and Catalog versions. Pin the Catalog and consult the exact v0.9.1 Basic Catalog schema. Custom components should reuse host tokens rather than creating a parallel styling system.