ADR-0013: Semantic application themes and native slots

Status: Accepted — HITL approved 2026-07-11 Date: 2026-07-11

Context

AgentsKit Chat needs one visual intent across DOM, native, and terminal hosts without moving framework primitives into the shared definition or recreating AgentsKit UI bindings.

Decision

@agentskit/chat owns a small runtime-validated semantic theme: colors, spacing, radius, and font family. Renderer packages translate it only through published AgentsKit seams:

• React maps to upstream --ak-* CSS custom properties and stable data-ak-* hooks.
• React Native maps to upstream style pass-throughs and native styles for application components.
• Ink maps supported colors to a complete upstream InkTheme and uses InkThemeProvider; spatial and typography tokens are intentionally unsupported by terminal capabilities.

Each renderer exposes native component slots for its container, message, input, thinking indicator, confirmation, and ChoiceList. Slots never enter the shared definition. Hosts needing fully headless state import the published useChat hook from their AgentsKit binding directly.

Default shells retain their documented accessibility and keyboard behavior. A host replacing a slot owns equivalent semantics.

Alternatives considered

1. A universal component tree — rejected because it would leak DOM/React Native/Ink primitives into core.
2. A second headless chat hook — rejected because AgentsKit already owns useChat, state, lifecycle, and cancellation.
3. A local design system — rejected because AgentsKit already publishes CSS variables, native style seams, and Ink theming.

Consequences

• One shared definition can be restyled without renderer conditionals.
• Mapping is capability-aware rather than pretending every platform supports every token.
• Slots remain idiomatic and type-safe per renderer.
• Replacing defaults transfers accessibility responsibility to the host.

Upstream adoption

Inspected AgentsKit React theme CSS and component attributes, React Native component style/testID pass-throughs, and Ink InkThemeProvider/InkTheme. Reused all of them directly. The missing React Native content/input text-style seams were added at the source in AgentsKit #1158/#1159 and released as @agentskit/react-native@0.4.4 via #1160 before integration. Added here only application token validation, mapping, and renderer-local slots. No upstream primitive or behavior is copied.