Epic: styling layers — bridge host themes into a2tea

[joestump-agent]

Tracking epic for the styling/theming work proposed in docs/proposals/styling-layers.md.

Context

The A2UI theming model works in layers: agents send semantic hints only (usageHint: "h1", button primary/borderless), the catalog maps hints to styled components and owns the theming solution (on the web: --a2ui-* CSS variables with minimal specificity), and the host/platform overrides those tokens.

a2tea is the catalog implementation for terminals, and it already has the right skeleton: render.Styles + DefaultStyles() + WithStyles (#31), monochrome by construction so the host theme wins. This epic completes that story so a host like crush can map its full semantic palette onto surfaces:

• complete the style token set (per-component slots + chrome glyphs — the terminal analog of the web catalog's CSS variables)
• honor more semantic hints from the basic catalog
• support lossless live restyling for hosts with runtime theme switching

Two invariants are not changing:

• DefaultStyles() stays monochrome — no color SGR in default output (pinned by render/styles_test.go)
• createSurface.theme stays a no-op, matching the spec (even the reference web basic catalog ignores it; design is open upstream in Consider renaming theme on createSurface to configuration and remove primaryColor from basic catalog a2ui-project/a2ui#1118)

Issues

Bug (ship first, independent):

• TextField variant: "obscured" renders the value in cleartext #55 — TextField obscured renders the value in cleartext

Core (in order):

• Expand render.Styles into a complete token set (component slots + Glyphs) #56 — expand Styles into a complete token set (slots + Glyphs)
• Add Surface.SetStyles for lossless live restyling #57 — Surface.SetStyles for lossless live restyling

Hint upgrades (parallel after #56):

• Give Button variant: "primary" a visual identity via ButtonPrimary slots #58 — Button primary visual identity via ButtonPrimary slots
• Optional per-level heading styles (H1–H5) #59 — optional per-level heading styles (H1–H5)
• Honor Image variant size hint (icon/avatar vs feature/header placeholders) #60 — honor Image variant size hint in placeholders

Docs:

• wire-format.md: audit and document every dropped hint (Weight, Accessibility, Checks, Align/Justify, field variants) #61 — wire-format.md audit of every dropped hint
• Website: add a Theming page documenting Styles, Glyphs, WithStyles, and SetStyles #62 — website Theming page (token reference + worked host example)
• Refresh stale AGENTS.md (styling architecture, events, interactivity, deps) #63 — refresh stale AGENTS.md

Standing:

• Tracking: createSurface.theme policy — watch upstream a2ui-project/a2ui#1118 #64 — createSurface.theme policy; watch upstream Consider renaming theme on createSurface to configuration and remove primaryColor from basic catalog a2ui-project/a2ui#1118

Sequencing

1. TextField variant: "obscured" renders the value in cleartext #55 (bug fix, independent of everything else)
2. Expand render.Styles into a complete token set (component slots + Glyphs) #56 (token set) — everything else styling-related builds on it
3. Add Surface.SetStyles for lossless live restyling #57 + Give Button variant: "primary" a visual identity via ButtonPrimary slots #58/Optional per-level heading styles (H1–H5) #59/Honor Image variant size hint (icon/avatar vs feature/header placeholders) #60 (parallelizable after Expand render.Styles into a complete token set (component slots + Glyphs) #56)
4. wire-format.md: audit and document every dropped hint (Weight, Accessibility, Checks, Align/Justify, field variants) #61/Website: add a Theming page documenting Styles, Glyphs, WithStyles, and SetStyles #62/Refresh stale AGENTS.md (styling architecture, events, interactivity, deps) #63 (docs, once the API is settled)

The consuming side (crush mapping its quickstyle palette onto these tokens, A2UI-over-MCP) is tracked in the crush fork — see docs/proposals/a2ui-mcp.md there.