New in v2.0

Agentic UX Components New Builder Component

A new suite of components for BrainStorm's AI agent experiences. The agent (codenamed BrainStorm AI) helps admins understand adoption data, create flows, and surface insights. These components must feel trusted, calm, and purposeful — never flashy.

Pick your component first — never hand-roll agent UI: all agentic patterns have builders. Match the zone and moment to the right component.

Zone / Moment	Component	Use when…
Empty chat state	`buildStarterCards()`	2–4 prompt cards with icon + title + description; shown before first message
After agent response — follow-up chips	`buildSuggestedPrompts()`	Short ≤ 6-word chips inviting the next question
Before agent response — agent working	`buildAgentActivity()`	Collapsible thinking + tool-use trace shown while agent is running
Agent response body	`buildAgentMsg()`	Narrative text + optional embedded charts in the chat thread
AI artifact surfaced in chat thread	`buildAgentActionCard()`	Flow draft, report, or object created by agent — accept / edit / dismiss
Recommendations in a report zone (not in chat)	`buildRecommendedActions()`	1–4 recommended actions with evidence + CTA, outside the chat thread
Follow-up action buttons below a response	`buildChatFooter()`	1–3 action buttons anchored below the agent's last message

12.2 — Agent Message Block Component

The Agent Message Block renders a full AI response: brand avatar, response body, optional follow-up action suggestions, and thumbs-up/down feedback row. Use buildAgentMsg() via .bsn-agent-msg-mount — never hardcode the avatar, bubble, or feedback row.

Builder: buildAgentMsg(cfg) via .bsn-agent-msg-mount
Config: body (HTML string) · actions (array of label strings, renders as suggestion pills with arrow icons) · class (extra CSS)
Rules: Always pair with buildAgentActivity() above when the agent did non-trivial reasoning. Feedback row is always rendered. Max 3 action suggestions.

12.3 — Agent Chat Interface

Full chat interface with header, message thread, and fully interactive BrainStorm AI input bar. Click the textarea to focus (State 2), type to trigger the send button (State 3), click the paperclip to add file attachments (State 4), hover the send button for the hover state (State 5). Suggestion chips update contextually at each state. The state badge above the input tracks the current state in real time.

BrainStorm AI AI

BrainStorm adoption intelligence · Connected to your workspace

Why is Teams adoption low in the Engineering department?

Jordan · Just now

Querying adoption data Engineering · last 30 days Done

Analyzing completion patterns Comparing against org avg.

Engineering is at 31% completion — 22 points below your org average of 53%. Here's what I found:

• Drop-off point: 68% of Eng users start the "Meetings & Collaboration" module but exit at the Teams calling setup step.

• Time gap: Eng users typically wait 4+ days between steps vs. 1.2 days org-wide.

• No manager nudge: Engineering managers haven't activated the completion reminder flow.

Create a targeted flow for Eng

Enable manager reminders

View full Eng report

Was this helpful?

BrainStorm AI · Just now

State 1 — Empty (resting)

Suggestions

12.3 — BrainStorm AI Input States Component

The input bar transitions through five states. All states share the same Salt background bar and storm-input-shell component. The shell changes shape, the attach button changes weight, the send button appears/disappears, and chips update contextually. Use buildStorm() via .bsn-storm-mount — never hardcode.

State 1 — Empty (resting)

View all enrolled users View all customers

Shell border: --border-default · Attach button: transparent/flat (resting class) · Send button: hidden · Placeholder: --text-muted · Suggestions: 2 generic chips

State 2 — Focused (contextual suggestions expand)

Upload content to BrainStorm Add customer accounts Enable content Configure content enrollment rules Create a flow

Shell border: --border-focus · Ring: --focus-ring · Chips expand to full admin-contextual set

State 3 — Typing (send button appears, suggestions update contextually)

Set end-user auto-enrollment criteria for {CourseTitle} Notify customer account admins about {courseTitle}

Attach button upgrades to active state (--agent-bg fill, no resting class) · Send button appears (--color-alpine bg, --color-bsi-yellow icon) · Typed text: --text-primary · Suggestions narrow to match typed intent

State 4 — Files attached (shell expands, border-radius reduces)

videoName Here1.mp4

videoName Here2.mp4

videoName Here5.mp4

Upload content to BrainStorm Add customer accounts

Class has-attachments added to shell → radius collapses from --radius-pill to --radius-card · Attachment tray renders above text row · File chips: --color-salt bg, --agent-border border, Alpine icon bg · Remove button: --color-alpine fill, hover --color-canyonlands

State 5 — Send hover (pointer cursor, send button hover)

Enroll users based on {criteria} Enroll users based on {criteria}

Send button hover: --color-alpine at 85% opacity + transform:scale(1.05) via --transition-spring · Send button active: transform:scale(.95) · Cursor: pointer over send button

Live — buildStorm() mount (interactive)

Focus the textarea → focus ring appears (CSS :focus-within). Type → send button appears, attach button loses .resting. Clear text → reverts.

Spec: Salt background bar · storm-input-shell max-width 42.5rem, border --border-default 1.5px, --radius-pill · Focus: --border-focus + --focus-ring · has-attachments modifier collapses radius to --radius-card · Attach button: resting = transparent/--text-muted, active = --agent-bg/--color-alpine · Send button: --color-alpine bg, --color-bsi-yellow icon, hidden until typing · Suggestion chips: --agent-bg background — never white or Salt · Pinned to bottom via flex-shrink:0 — NEVER position:fixed · Use buildStorm() via .bsn-storm-mount — never hardcode.

12.4 — Agent Activity Trace Component

A collapsible trace of agent thinking + tool-use steps, surfaced above or before an agent message in chat. Collapsed by default to keep the chat thread clean; click the header to expand and inspect the work. Use buildAgentActivity() via .bsn-agent-activity-mount — never hardcode the thinking bubble or tool-use blocks.

Thinking state — agent is still processing

Complete state — agent has finished its work

Click either trace above to expand it and see the full thinking + tool-use detail.

Spec: No outer container chrome in either state · Header = inline button, padding 2px 0, gap 8px · Leading caret = fa-chevron-right at 9px in --text-disabled, rotates 90° on expand to point down · Status text = 12px --text-muted when collapsed, Alpine when expanded; italic + regular weight on state=thinking, medium otherwise · Duration = 11px tabular-nums in --text-disabled, preceded by a · separator · Body messages are quiet text rows — no bubble, no block, no border. Inside .bsn-agent-activity-body the .thinking-bubble renders as italic 12px --text-muted (no rgba bg, no border, no bouncing dots), and each .tool-use-block renders as a single line — 11px --text-disabled leading icon, 12px --text-muted label, trailing 10px Uinta "Done" tag or small spinner for running steps. Rows stack with 4px gap under the header's var(--space-4) left indent · Avatar = showAvatar: false by default; the trace usually sits next to an agent message that already shows the brand identity. Collapsed by default.

12.5 — Agent Action Cards Component

When the agent creates something (a flow draft, a report, a suggested audience) it surfaces it in an action card within the chat thread. Cards are actionable — the user can accept, edit, or dismiss. Sibling to §12.11 Recommended Action Cards (different anatomy, different job). Use buildAgentActionCard() via .bsn-agent-action-card-mount — never hardcode.

Flow draft generated by agent

Insight report generated by agent

Spec: White card · 1.5px --agent-border · --radius-card · --shadow-sm · header bg --agent-bg, uppercase letter-spacing 1px, --color-alpine text · body padding --space-4 --space-5 · footer border-top --border-default · Max 3 footer actions (primary/outline/ghost) · Render only inside the chat thread — for report-zone recommendation cards use buildRecommendedActions() (§12.11) · Use buildAgentActionCard() via .bsn-agent-action-card-mount — never hardcode.

12.6 — Suggested Prompts & Actions Component

Inline suggestion chips appear after agent responses and on the empty chat state. They scaffold the user into useful queries without requiring them to know what to ask.

Suggested follow-ups after a response:

Mount point:

<div class="bsn-suggested-prompts-mount" data-bsn-suggested-prompts='{"ariaLabel":"…","items":[{"label":"…","icon":"fa-plus","value":"…"}]}'></div>

Config: items[] (required: label; optional: icon = FA name, value = emitted as data-value for click handlers), ariaLabel, class. Renders into the existing .agent-suggestions / .agent-suggestion CSS so the visual is identical to the hardcoded original. NEVER hardcode .agent-suggestions markup. Sibling component: buildStarterCards() for the empty-state starter cards beneath.

Empty state starter prompts:

Analyze my adoption data Understand completion rates, drop-offs, and trends

Create a flow from scratch Describe what you want, I'll draft the flow

Find at-risk users Identify who needs intervention before they disengage

Summarize last month Get an executive summary of adoption performance

12.7 — Agent Task List Component

When the agent performs a multi-step agentic workflow, it surfaces a task list so the user understands what's happening. Each step has a clear state. Use buildAgentTaskList() via .bsn-agent-task-list-mount — never hardcode.

Builder: buildAgentTaskList(cfg) via .bsn-agent-task-list-mount
Config: label (optional heading) · tasks[]: each task has label and status (done · running · pending)
States: Done = Alpine check in white circle · Running = Wasatch spinner · Pending = empty grey ring · Status text auto-matches state.

12.8 — Citations & Source References Component

When the agent cites data sources, it uses numbered superscript badges inline, with an expandable citations panel below the message. Use buildAgentCitations() via .bsn-agent-citations-mount — never hardcode.

Builder: buildAgentCitations(cfg) via .bsn-agent-citations-mount
Config: text (HTML string with inline <span class="agent-citation"><span class="citation-badge">N</span></span> superscripts) · sources[]: each has source and excerpt
Rules: Sources panel always appears below the bubble when sources is non-empty. Badge numbers must correspond to inline citation order.

12.9 — Proactive Agent Nudges Component

The agent can surface proactive notifications outside of chat — e.g., in the dashboard or notification center — when it detects adoption risk or opportunities. Use buildAgentNudge() via .bsn-agent-nudge-mount — never hardcode.

Builder: buildAgentNudge(cfg) via .bsn-agent-nudge-mount
Config: variant (warning · success · info · danger · default) · title · text · actions[] (label, variant)
Rules: Variant controls left-border color, icon background color, and default icon. Never override the border color manually — use the variant system.

12.10 — Agent Handoff Notice Component

When the agent reaches the limits of what it can do autonomously and needs the admin to take action, it surfaces a clear handoff notice. Use buildAgentHandoff() via .bsn-agent-handoff-mount — never hardcode.

Builder: buildAgentHandoff(cfg) via .bsn-agent-handoff-mount
Config: title · text · icon (FA name, default arrow-right-arrow-left) · actions[] (label, variant)
Rules: Icon always renders in BSI Yellow on Alpine background. Title is always an action directive, not a passive label. Max 2 action buttons.

12.11 — Recommended Action Cards Component

When the agent recommends an action you could take based on what the data shows, it surfaces it in a Recommended Action Card in the report's recommendations zone. Cards are workflow handoffs — primary CTA commits the action; secondary link verifies the cohort first. Sibling to §12.5 Agent Action Cards (different anatomy, different job). Two layout variants share the same builder and data shape — switch via "layout": "grid" | "row". Use buildRecommendedActions() via .bsn-recommended-actions-mount — never hardcode.

Variant A — Grid layout default · dashboard feel

Variant B — Row layout compact · title + evidence only · ~52px per row

Spec: Both variants share the same data shape and the same builder — switch via "layout": "grid" | "row". White surface · 1px --border-default · --radius-card · --shadow-sm. Grid (default): 3-up repeat(3, minmax(0, 1fr)), gap --space-4, card padding --space-5; collapses to 1-col below 1080px. Row: single-column flex list, gap --space-2 between rows, each row grid with padding var(--space-2) var(--space-4) and target height ~52px; the leading count in the evidence line is a clickable Wasatch .bsn-recommended-action-row-count; below 720px the CTA reflows beneath the text block. No hover state on the card/row itself — buttons inside are the affordances · Min 1, max 4 cards (recommend 3) · Use buildRecommendedActions() via .bsn-recommended-actions-mount — never hardcode.

12.13 — Chat Follow-Up Footer Component

The Chat Follow-Up Footer closes an AI-generated response with a "What would you like to do next?" prompt and 2–5 suggested action pills. Use buildChatFooter() via .bsn-chat-footer-mount — never hardcode.

Builder: buildChatFooter(cfg) via .bsn-chat-footer-mount
Config: label (default "What would you like to do next?") · actions (array of {label} objects, 2–5 max)
When to use: Appears at the bottom of AI-generated content pages (AI Insights template). Not used on standard report pages. Pill labels should read as natural conversational continuations — "Show me the trend over time" not "View trend chart".

12.12 — Agentic Token Reference

Token	Value	Usage
--agent-bg	rgba(35,64,59,.06)	Agent message backgrounds, card headers
--agent-border	rgba(35,64,59,.15)	Agent message borders, action card borders
--thinking-bg	rgba(158,187,208,.18)	Thinking bubble background — Bonneville
--thinking-border	rgba(90,135,195,.35)	Thinking bubble border — Wasatch
--tool-use-bg	rgba(90,135,195,.08)	Tool use indicator background
--tool-use-border	rgba(90,135,195,.25)	Tool use indicator border
--chat-user-bg	var(--color-alpine)	User message bubble
--chat-agent-bg	#ffffff	Agent message bubble

Avatar Component

Agent or user avatar. agent renders the branded mark; user shows initials. Sizes sm/md.

Mount point: <div class="bsn-avatar-mount" data-bsn-avatar='{…}'></div> — rendered via buildAvatar(). Auto-generated from ssot/components/avatar/.