Onboarding Patterns
The first-contact moment when an AI agent introduces itself to a new user. These patterns govern capability disclosure, incremental trust escalation, and task completion tracking — the UX that makes agentic authority legible and human override always possible.
Agent-initiated action, authority, ACTIVATE state. Red = the agent is asserting something.
Human validation required. Gold = a person must decide before this proceeds.
Processing / in-progress states. Blue = the agent or system is working on this.
AgentIntroductionCard
The first thing a user sees when an AI agent enters their workspace. Discloses identity, trust tier, and every capability the agent will use — before it does anything. The single most important trust moment in the agentic lifecycle.
Every read, write, and transact action is listed before the agent takes any action.
The 5-tier trust system tells the user exactly what precedent backs this agent's authority.
Actions requiring explicit approval are badged in gold — no surprise executions.
Agent-initiated vs human-initiated flows have distinct visual treatment so the user always knows who initiated contact.
Monitors cash positions, drafts payment instructions, and produces 7-day forecasts. Operates under your approval thresholds — all write and transact actions require your explicit sign-off.
| Prop | Type | Default | Description |
|---|---|---|---|
| agentName | string | — | Full display name of the agent. |
| agentRole | string | — | Short role label (e.g. 'Treasury Analyst'). |
| agentDescription | string | — | 1–2 sentence plain-language explanation of what the agent does and why the user should trust it. |
| trustTier | 1 | 2 | 3 | 4 | 5 | — | Current trust tier from 1 (UNTRUSTED) to 5 (ORCHESTRATOR). Determines the tier badge color and description. |
| capabilities | AgentCapabilityItem[] | — | List of capabilities grouped by class: read / write / transact. Items with requiresApproval=true display a gold APPROVAL REQUIRED badge. |
| surface | 'card' | 'panel' | 'modal' | 'card' | Adjusts layout width. Panel/modal stretch to full width of their container. |
| context | 'agent-initiated' | 'human-initiated' | 'agent-initiated' | Changes the header label. Agent-initiated uses agency red; human-initiated uses surface-inverse. |
| onApprove | () => void | — | Called when the user clicks ACTIVATE AGENT. |
| onDismiss | () => void | — | Called when the user dismisses the introduction. |
ProgressivePermissionFlow
Trust is earned incrementally. This pattern models the read → write → transact escalation path, making each step visible and each approval an explicit human decision. The agent can never claim a higher capability class without passing through every preceding step.
| Class | Icon | Color token | Examples | Default approval gate |
|---|---|---|---|---|
| read | ○ | --ds-text-secondary | View balances, query history, read FX rates | None — implicit on activation |
| write | ◑ | --ds-color-temporal | Draft payments, update forecasts, create proposals | Required per escalation step |
| transact | ● | --ds-color-agency | Execute FX, submit wires, initiate settlements | Required per transaction |
Required to analyze cash positions and produce accurate forecasts. No data is modified.
Allows drafting payment instructions and updating forecast parameters. All write actions are queued for human review before execution.
Enables below-threshold FX conversions and wire initiation. Requests are individually approval-gated.
| Prop | Type | Default | Description |
|---|---|---|---|
| agentName | string | — | Agent display name shown in the header. |
| steps | PermissionStep[] | — | Ordered list of permission escalation steps. Each step has a level, justification, and actions unlocked. |
| activeStepIndex | number | — | Zero-based index of the step currently awaiting approval. Renders with a gold validation border. |
| onApprove | (level: PermissionLevel) => void | — | Called with the approved permission level when user approves the active step. |
| onDeny | (level: PermissionLevel) => void | — | Called with the denied permission level when user denies the active step. |
| compact | boolean | false | Hides justifications and action lists. Use in sidebar or constrained-width contexts. |
OnboardingChecklist
Agentic task completion tracker for first-run onboarding sequences. Every completed item carries provenance — evidence of who completed it and why it's valid. Blocked items surface human action requirements without hiding system state.
The progress bar and item count give users a clear picture of where they are in the setup flow at all times.
Items completed by the agent are labeled with the agent's name and timestamp. The user always knows what the agent did.
Each completed item links to the data, approvals, or agent actions that confirm its completion. Auditable by design.
Blocked items show exactly what is needed to unblock them. No mystery states — the human always knows what to do next.
| Status | Icon | Color | Meaning |
|---|---|---|---|
| pending | ○ | --ds-text-muted | Not yet started. MARK DONE / SKIP controls visible if handlers are provided. |
| in-progress | ◔ | --ds-color-temporal | Agent is actively working on this item. Pulse animation on the icon. |
| done | ● | --ds-color-outcome-positive | Completed. Agent attribution and timestamp shown. Provenance links expand on click. |
| skipped | — | --ds-text-muted | User explicitly skipped. Title strikes through. Counted as complete for progress purposes. |
| blocked | ⚑ | --ds-color-agency | Cannot proceed. Red flag icon. Expanded detail shows the blocker reason and required human action. |
| Prop | Type | Default | Description |
|---|---|---|---|
| title | string | 'Onboarding Checklist' | Section heading shown above the progress bar. |
| items | OnboardingChecklistItem[] | — | Checklist items. Each carries a status, optional agent attribution, completedAt timestamp, and provenance refs. |
| onMarkDone | (id: string) => void | — | When provided, pending items display a MARK DONE button for human-initiated completion. |
| onSkip | (id: string) => void | — | When provided, pending items display a SKIP button. |
| showProvenance | boolean | true | Show provenance references in the expanded item detail. Set false for stripped-down checklists. |