A2UI / Design Language
Interaction States
The emotional and visual language for AI-human interaction moments. Every state has a semantic color, an emotional register, and a copy convention. These rules govern how agency is communicated — clearly, without fear.
Emotional Register
Three colors. Three meanings. No exceptions.
Color in A2UI is semantic, not decorative. Each hue carries a meaning that must be consistent across every surface. Using red for loading or gold for errors destroys the trust signal the system is building.
Agency Red
Authority & Action
Something is being done on the user's behalf. Real-world consequences. Reserve exclusively for committed actions — never for loading or passive states.
Temporal Blue
Processing & Uncertainty
Something is in-flight or unknown. Time is a factor. The outcome has not yet been decided. Covers both mechanical retrieval (loading) and active reasoning (thinking).
Validation Gold
Trust & Confirmation
A judgment is being made — by the user (confirming) or by the agent on a second attempt (recovery). Gold signals the threshold between uncertainty and resolution.
Error uses --ds-color-error, not --ds-color-agency. These are distinct hues. Agency red means “AI is acting”; error red means “something failed.” They must not be confused.
State Vocabulary
Six States. Complete Coverage.
Every AI interaction moment maps to exactly one of these states. Each has a precise definition, a color contract, and copy conventions that cannot be mixed.
System is fetching data from an external source. The agent has not yet begun reasoning. This is a mechanical wait, not a decision moment.
Copy Examples
Do
- Use passive voice — system is fetching, not agent deciding
- Show source of data when relevant
- Include estimated time for long waits
Don't
- Use agency red — nothing is being decided
- Say 'AI is loading' — say 'Retrieving' or 'Fetching'
Agent is actively reasoning. Data is available but a conclusion has not been reached. Outcome is uncertain. The user is watching the agent work.
Copy Examples
Do
- Name the domain being analyzed
- Show intermediate outputs when possible
- Convey analysis in progress, not action in progress
Don't
- Use action verbs that imply commitment ('Executing…', 'Sending…')
- Show confidence scores until the thinking state resolves
Agent is taking a real-world action with consequence. This is the most trust-critical state. Users must be able to identify exactly what is happening and why.
Copy Examples
Do
- State the action precisely: verb + object + magnitude
- Show the authorization chain (who approved this)
- Include a reversibility indicator if applicable
Don't
- Use softening language that obscures the action
- Omit the scope (e.g. 'Processing…' without amount/target)
- Use this state for passive data retrieval
Agent has reached a decision gate and is awaiting human confirmation. The action is described but not yet committed. The user holds authority here.
Copy Examples
Do
- State the consequence clearly before the CTA
- Include confidence level and reasoning summary
- Make the approval scope explicit (what exactly is being approved)
Don't
- Bury consequence details below the CTA
- Use confirming state for informational messages that need no action
- Pre-select approve — default must be neutral
A failure has occurred. May be system-level (API timeout) or policy-level (limit breach). The error state must differentiate between agent failure and system failure.
Copy Examples
Do
- Name the failure precisely — what failed and why
- Distinguish between recoverable and terminal errors
- Provide a clear next action: retry / escalate / contact support
Don't
- Use generic 'Something went wrong' copy
- Use agency red (--ds-color-agency) — error uses --ds-color-error (distinct hue)
- Leave the user without a path forward
Agent detected a failure and is actively attempting to recover. Distinct from error (terminal) — recovery implies the agent has a plan and is executing it.
Copy Examples
Do
- Show the recovery strategy, not just that recovery is happening
- Include attempt count or next-step timing where available
- Transition to success or escalation — never leave recovery open-ended
Don't
- Reuse error copy in recovery — the emotional register is different
- Loop silently — always surface retry count or deadline
Scenario Scripts
State Sequences in Practice
Real A2UI handoff moments composed from the state vocabulary. Each scenario shows the correct state sequence, copy, and annotation notes for engineers implementing these flows.
Payment Approval Gate
Agent identifies a payment batch, reasons over it, surfaces for approval, executes on confirmation.
Limit Breach Escalation
Agent detects a policy breach mid-action, errors, then escalates via a confirming handoff.
Morning Brief Surface
Agent loads context, reasons over priorities, and surfaces the operating surface for the day.
Agent Handoff
Analysis agent completes reasoning and hands off to execution agent with a trust chain.
Settlement Recovery
Settlement fails on first attempt; agent retries, exhausts retries, escalates to ops.
Trust Guidelines
Making Agency Feel Trustworthy, Not Frightening
Agency red is powerful. Used incorrectly it signals threat. Used correctly it signals authority under human control. These rules maintain the distinction.
Show what, not just that
"Executing payment run — 14 payments · $42.8M" not "Processing." Users must see the scope of what the agent is doing.
Reserve red for committed actions only
Loading and thinking are blue. Confirmation is gold. Red appears only when the agent is taking a real-world action with consequence. Diluting red with informational use destroys the signal.
Surface the authorization chain
Acting states should name who authorized the action: "authorized by CFO · 09:44 UTC" or "L3 policy gate: cleared." This makes authority traceable.
Expose reversibility when it exists
If an action can be undone, say so near the acting state: "Undo window: 5 minutes." If it cannot, the acting state copy should communicate finality.
Never show model internals in user-facing states
Context token counts, logprobs, and sampling parameters are not user-facing copy. Thinking state shows analysis domain, not model mechanics.
Keep confirming neutral by default
The approve/confirm action must never be pre-selected. Default UI state must be neutral — the user must act to proceed. This is a trust contract, not a UX optimization.
Use soft verbs for thinking, strong verbs for acting
"Reviewing…", "Analyzing…", "Identifying…" convey reasoning without commitment. "Executing…", "Submitting…", "Initiating…" convey action. Match verb weight to state weight.
Recovery must always resolve
A recovery state left open-ended implies the agent is stuck. Always transition to success, escalation, or a terminal error with next steps. Never leave the user watching infinite recovery.
Implementation Reference
// AI Interaction State — token map
const STATE_TOKEN = {
loading: "var(--ds-color-temporal)", // blue — system retrieval
thinking: "var(--ds-color-temporal)", // blue — agent reasoning
acting: "var(--ds-color-agency)", // red — committed action
confirming: "var(--ds-color-validation)", // gold — human gate
error: "var(--ds-color-error)", // red — failure (distinct hue)
recovery: "var(--ds-color-validation)", // gold — agent retry/escalation
} as const;
type InteractionState = keyof typeof STATE_TOKEN;
// Copy convention examples
const STATE_COPY: Record<InteractionState, string[]> = {
loading: ["Fetching {source}…"],
thinking: ["Analyzing {domain}…", "Reviewing {subject}…"],
acting: ["Executing {action} — {scope}"],
confirming: ["This {action} requires your approval."],
error: ["{Subject} failed — {reason}."],
recovery: ["Retrying via {strategy} — attempt {n}/{max}."],
};