A2UI Theming: Plumb brand.json palette into A2UI surface at session init

[pkras]

Summary

brand.json has a palette (colors, fonts, logo). A2UI surfaces support theming. But there's no explicit plumbing that feeds the brand palette into the A2UI surface at session init. The brand styling section of the original RFC (#2904) proposed this, but it wasn't covered in the #906 implementation.

What's Needed

• Spec note or example showing how brand.json palette fields map to A2UI theme tokens during si_initiate_session
• Clarify whether the host or the SI agent is responsible for resolving brand palette → A2UI theme
• Consider whether this belongs in si-capabilities.json (e.g. a2ui.brand_theme_source) or is purely guidance

Ref: #2904 (original RFC), #906 (implementation PR)

[bokelley]

Triage

Classification: Feature request (spec + docs)
Bucket(s): spec / protocol, web / site / docs
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Real question is resolution locus. Host instinct: host resolves brand.json.palette → A2UI theme tokens at session init, because host owns chrome contrast/accessibility. What's needed at init: palette handoff mechanism, a contract that the SI agent honors provided tokens, and a fallback when palette is absent. A hard brand_theme_source schema field is overkill — an a2ui.theming: { resolver: "host"|"agent", token_version } object in si-capabilities.json is the MVP spec addition. That IS a schema change (minor bump). Needs @bokelley: is theming a capability or an assumption?
• docs-expert: Architectural decision first — a2ui.brand_theme_source as a schema field changes the protocol (minor bump + changeset); pure guidance doesn't. Resolve that before drafting. Then land inside the consolidated a2ui.mdx page alongside A2UI Rendering Guidance: Document disclosure/chrome separation #2919/Document A2UI user-action to SI session event mapping #2920.

My take: Both experts converge on "spec-vs-guidance" as the core call and lean toward a minimal si-capabilities.theming object over a heavier brand_theme_source field. Flagging for @bokelley ruling on (a) capability-declared vs conventional, and (b) host-resolves vs agent-resolves. Once that lands, the doc follow-up is small.

@bokelley, your call: a2ui.theming capability (minor bump) or pure guidance in the A2UI integration guide?

---

Triaged by Claude Code. Session: https://claude.ai/code/1c1fb33b-fecb-4d12-b1db-01a2d5f4f49b

---

Generated by Claude Code

[bokelley]

Triage

Classification: Spec question / feature request
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Architectural call, not docs — (a) resolution locus (host vs SI agent) changes the trust model; (b) whether to add a2ui.brand_theme_source to si-capabilities.json is a minor schema change needing an RFC-scoped decision. RFC RFC: A2UI Integration for Sponsored Intelligence Rendering #2904 proposed this; PR Add A2UI + MCP Apps support to Sponsored Intelligence #906 deliberately omitted — that omission needs a product call.
• docs-expert: A doc PR today would invent protocol. Natural home for the eventual content is a theming section in docs/sponsored-intelligence/specification.mdx + crosswalk in docs/brand-protocol/brand-json.mdx, but token mapping doesn't exist in surface.json or si-capabilities.json yet.

My take: Two decisions needed before anything ships: (1) host or SI agent resolves brand palette → A2UI theme tokens, and (2) is the resolver selection declarative (new si-capabilities.json field) or implicit (guidance only). @bokelley, your call — or punt to a follow-up RFC.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01JRhYh1t6yh59x8DCXEWVG8

---

Generated by Claude Code

[bokelley]

Drafted theming guidance as part of the consolidated A2UI integration page in #3761 — brand.json palette/typography → A2UI theme tokens, with the host as resolver (because it owns its component catalog and a11y floors). Bundled with #2919 and #2920 since they're three views of the same host/brand boundary. Marked draft + needs-wg-review.