nexus/.planning/phases/22-agent-streaming/22-UI-SPEC.md

phase	slug	status	shadcn_initialized	preset	created	revised
22	agent-streaming	draft	true	new-york / neutral / cssVariables	2026-04-01	2026-04-01

Phase 22 — UI Design Contract

Visual and interaction contract for frontend phases. Generated by gsd-ui-researcher, verified by gsd-ui-checker.

---

Design System

Property	Value
Tool	shadcn (new-york style) — carried forward from Phase 21
Preset	new-york, baseColor: neutral, cssVariables: true
Component library	Radix UI (via shadcn)
Icon library	lucide-react (^0.574.0)
Font	System UI stack (inherited from existing CSS — no custom font declared)

Source: ui/components.json, ui/src/index.css (unchanged from Phase 21)

shadcn components already installed (usable without install): Avatar, Badge, Button, Card, Checkbox, Command, Dialog, DropdownMenu, Input, Popover, ScrollArea, Select, Separator, Sheet, Skeleton, Tabs, Textarea, Tooltip

New shadcn components for this phase (install before use): None required — Select and DropdownMenu cover the AgentSelector. Avatar covers the agent badge avatar slot.

New npm packages for this phase (not shadcn registry):

• virtua ^0.49.0 — virtualized list for ChatMessageList (PERF-03). Install: pnpm --filter @paperclipai/ui add virtua
• Server: openai or ai SDK — LLM streaming. See RESEARCH.md for provider resolution. Not a UI registry concern.

---

Focal Point

The primary focal point of Phase 22 is the streaming message in progress — specifically the assistant message bubble that receives incoming tokens. While tokens arrive, the bubble is the only animated element on screen. The Stop button (rendered inside ChatInput in place of Send) is the secondary focal point during streaming.

---

Spacing Scale

Carried forward from Phase 21 without change. Source: 21-UI-SPEC.md.

Token	Value	Usage
xs	4px	Icon gaps (gap-1), inline icon + label spacing
sm	8px	Compact padding inside list items, badge padding, button icon padding
sm+	12px	Conversation list item vertical padding (py-3) — named exception, follows EntityRow pattern
md	16px	Default element padding (p-4), chat panel header padding
lg	24px	Section padding on desktop (p-6)
xl	32px	Gap between major UI zones
2xl	48px	Empty-state vertical padding (py-12)
3xl	64px	Page-level section breaks (not applicable in panel context)

Phase 22 additions:

Token	Value	Usage
agent-badge-gap	8px (sm)	Gap between agent avatar and agent name in ChatAgentBadge
agent-avatar	20px	Width and height of the agent avatar circle in ChatAgentBadge
streaming-dot	8px (sm)	Width and height of the pulsing streaming cursor dot

Exceptions (unchanged from Phase 21):

• sm+ (12px): conversation list item vertical padding only.
• Touch targets: min-height: 44px on coarse-pointer devices (global index.css rule).
• Chat input bottom padding: pb-[calc(env(safe-area-inset-bottom)+16px)] on mobile.

---

Typography

Carried forward from Phase 21 without change. Source: 21-UI-SPEC.md.

Two weights only: regular (400) and semibold (600).

Role	Size	Weight	Line Height	Tailwind Class
Body	14px	400 (regular)	1.5	text-sm
Label	13px	400 (regular)	1.4	text-[13px]
Heading	16px	600 (semibold)	1.25	text-base font-semibold
Meta / Timestamp	12px	400 (regular)	1.4	text-xs text-muted-foreground

Phase 22 typography additions:

• Agent name in ChatAgentBadge: Label (13px / regular / text-muted-foreground). Not semibold — the name is contextual metadata, not a heading.
• Slash command suggestion label in the command popover: Body (14px / regular).
• Agent selector trigger label: Label (13px / regular), truncated with truncate.
• Stop button label (text inside ChatInput during streaming): Body (14px / regular), no special weight. The Square icon carries the visual signal.

Rules (unchanged):

• Agent message content inside ChatMarkdownMessage uses prose prose-sm — do not override.
• The chat input Textarea uses Body (14px / regular).
• Timestamps use Meta (12px / regular / muted-foreground), visible on hover only.

---

Color

All colors reference CSS custom properties already declared for all three themes in ui/src/index.css. Never hard-code hex values. Source: 21-UI-SPEC.md + RESEARCH.md Pattern 6.

Role	CSS Variable	60/30/10	Usage
Dominant surface	--background	60%	Chat panel background, message list background
Secondary surface	--card / --sidebar	30%	Conversation list sidebar, code block container
Accent	--primary	10%	Send button, active conversation border-left, filled pin icon
Muted	--muted	—	Input background, empty state icon container, streaming cursor background
Muted foreground	--muted-foreground	—	Placeholder text, timestamps, agent name in badge, secondary labels
Destructive	--destructive	—	Delete conversation action only (carried from Phase 21)
Border	--border	—	Dividers, chat panel border, input border

Accent (--primary) reserved for exactly these elements (Phase 22 carries Phase 21 list, no additions):

1. The "Send message" primary action button background
2. The active conversation in the sidebar (left-border indicator)
3. Filled pin icon on pinned conversations

Phase 22 agent colors — CSS custom properties (THEME-03):

Agent role colors use --chart-1 through --chart-5 CSS custom properties already declared for all three themes in ui/src/index.css. These are the ONLY variables permitted for agent identity coloring. Implementation via bg-[hsl(var(--chart-N))] Tailwind utility.

Agent Role	CSS Variable	Tailwind Class
ceo	--chart-1	bg-[hsl(var(--chart-1))]
pm	--chart-2	bg-[hsl(var(--chart-2))]
engineer	--chart-3	bg-[hsl(var(--chart-3))]
general / generalist	--chart-4	bg-[hsl(var(--chart-4))]
brainstormer	--chart-5	bg-[hsl(var(--chart-5))]
Unknown / fallback	--muted	bg-muted

Text on all agent color backgrounds: text-white (sufficient contrast on all three themes per chart variable definitions). Do not use text-foreground — the chart variables are saturated colors and require white text.

Stop button color: The Stop button uses variant="destructive" from shadcn Button — it uses --destructive background with destructive-foreground text. This signals urgency (cancel an ongoing action) without being confused with a data-destructive action.

---

Component Inventory

Modified from Phase 21

ChatInput (modified)

• Existing behavior fully preserved (auto-resize, Enter/Shift+Enter, Escape)
• Addition: Stop button during streaming
  • When streaming === true: Send button is replaced by a Stop button
  • Stop button: variant="destructive", icon-only (Square from lucide, 16px), aria-label="Stop generation"
  • Stop button is NEVER disabled — it must always be clickable during streaming
  • Layout: same position as Send button (flex row right of Textarea). Dimensions identical to Send button so the layout does not shift when toggling.
• Addition: Slash command popover
  • Trigger: when input value starts with / and matches a known prefix
  • Popover appears above the input (<Popover> with side="top" align="start")
  • Contents: list of matching commands using <Command> component (already installed)
  • Command item format: /{command} label (14px / regular) + destination agent name (13px / muted-foreground)
  • Dismiss: Escape, backspace past /, or clicking away
  • Max 5 items displayed; no scrolling inside the popover
  • Commands list (hardcoded):

Command	Label	Agent Destination
/brainstorm	Brainstorm an idea	Brainstormer
/ask-pm	Ask the PM	PM
/ask-engineer	Ask the Engineer	Engineer
/task	Create a task	Engineer
/search	Search conversations	Generalist

• Addition: @mention popover
  • Trigger: when input value starts with @ and has at least 1 character following
  • Same <Popover> + <Command> pattern as slash commands
  • Contents: filtered list of agent names from useAgents() cache
  • Item format: AgentBadge (20px avatar) + agent name (14px / regular)
  • Dismiss: same as slash command popover
• No change to aria-label, placeholder, or keyboard shortcuts

ChatMessageList (modified)

• Replace flat div with <VList> from virtua (PERF-03)
  • Drop <ScrollArea> wrapper — virtua manages scroll internally
  • <VList style={{ flex: 1 }} ref={listRef}> wraps all message items
  • Auto-scroll to bottom logic: isAtBottom state derived from VList onScroll callback — only auto-scroll when isAtBottom === true
  • Threshold: isAtBottom = scrollOffset + clientHeight >= scrollSize - 80 (80px tolerance)
• Addition: streaming optimistic message
  • When streaming === true: append a synthetic ChatMessageItem at bottom with:
    • role: "assistant"
    • content: partialContent (from useStreamMessage hook)
    • isStreaming: true prop
  • Streaming indicator: a pulsing dot (w-2 h-2 rounded-full bg-muted animate-pulse) appended after the last rendered markdown token
  • The streaming item has no timestamp (omit timestamp row entirely while isStreaming)
  • The streaming item has no action buttons (edit/retry are not shown on in-progress messages)
• Addition: message action buttons (edit/retry) on existing assistant messages
  • Visible on hover only (opacity-0 group-hover:opacity-100 transition-opacity duration-150)
  • Position: below the message bubble, right-aligned (flex justify-end gap-1 mt-1)
  • Retry button: variant="ghost" size="icon-sm", icon RotateCcw (14px), aria-label="Retry response"
  • Edit button: on user messages only — variant="ghost" size="icon-sm", icon Pencil (14px), aria-label="Edit message"
  • While streaming is in progress (streaming === true): hide all action buttons on all messages (prevent conflicting actions)
• Addition: ChatAgentBadge above each assistant message bubble
  • See new component spec below

ChatPanel (modified)

• Addition: AgentSelector in the panel header
  • Position: right side of the header bar (flex row, ml-auto before close button)
  • See new component spec below
• Header height remains 48px — AgentSelector must fit within this height
• No other structural changes

New Components for Phase 22

ChatAgentBadge

• Rendered above each assistant message bubble in ChatMessageList
• Layout: flex items-center gap-2 mb-1 (8px gap — sm token; 4px margin-bottom)
• Avatar: 20px circle (w-5 h-5 rounded-full flex items-center justify-center), background color from agentRoleColorClass(agent.role) (see Color section)
  • If agent has an icon value: render AgentIcon at 12px size inside the circle
  • If no icon: render the first letter of agent.name at text-[10px] font-semibold text-white
• Agent name: Label (13px / regular / text-muted-foreground), truncated at 120px max-width
• Source: agent.name and agent.role resolved client-side from useAgents(companyId) cache keyed by agentId on the message
• Fallback when agent not found in cache: show Bot icon (lucide, 12px) + "Agent" as name, bg-muted background — never throw or show nothing

AgentSelector

• Location: ChatPanel header, right side before the close button
• Component: <Select> (shadcn) with a custom trigger styled to match the 48px header height
• Trigger: compact, h-8 px-2 py-1, shows current agent avatar (16px, same color circle pattern as ChatAgentBadge) + agent name Label (13px / regular)
• Dropdown items: each agent as a <SelectItem>, showing ChatAgentBadge-style avatar (16px) + agent name (14px / regular) in a flex row
• Current agent persisted to conversation.agentId via PATCH /api/conversations/:id — this is the per-conversation default agent
• Empty state: if no agents available, show a single disabled item "No agents configured"
• Loading state: <Skeleton className="h-8 w-28" /> while agents are fetching
• Tooltip on the selector trigger: "Active agent for this conversation" (shown on hover via <Tooltip>)

---

Interaction Contract

Streaming lifecycle (CHAT-01, CHAT-12)

State	ChatInput	ChatMessageList
Idle	Send button enabled; textarea enabled	No streaming indicator
Sending user message	Send button disabled, Loader2 spin icon, textarea disabled	User message appears immediately (optimistic insert)
Streaming in progress	Stop button (variant="destructive", Square icon); textarea disabled	Streaming assistant message at bottom with pulsing dot; action buttons hidden on all messages
Stop clicked	Stop button transitions briefly to Loader2 for 200ms, then reverts to Send	Streaming message remains in list with last received content (partial); pulsing dot removed; action buttons re-appear
Stream complete	Reverts to Send button; textarea re-enabled and focused	Streaming indicator removed; persisted message replaces optimistic; RotateCcw + other action buttons appear on hover
Stream error	Reverts to Send button; textarea re-enabled; error toast fires	Streaming message removed from list

Message editing inline (CHAT-10)

• Trigger: click Pencil icon on hover over any user message
• The user message bubble text is replaced with a <Textarea> pre-filled with the original content
• Min height: 40px; max height: 120px; variant: none (no extra border — let the bubble container provide the boundary)
• Confirm: Enter (without Shift), or a "Regenerate" button (variant="default", 14px label "Regenerate") that appears below the edit area
• Cancel: Escape — restores original content, hides textarea
• On submit: POST the edited content to PUT /api/messages/:id; this re-triggers the stream from that point; messages after the edited message are NOT removed from the UI in Phase 22 (branching is Phase 24 scope)
• While editing: all other action buttons in the list are hidden

Response regeneration (CHAT-11)

• Trigger: click RotateCcw on hover over any existing assistant message
• Confirmation: none — immediate action
• Behavior: re-invokes the stream route for that message position; a new streaming message appears below the existing one; the existing assistant message is retained in the list until the new stream completes, at which point the existing message is replaced with the new one in-place
• While regenerating: Stop button active in ChatInput; all other action buttons hidden

Agent selector interaction (CHAT-08)

• Trigger: open AgentSelector dropdown in ChatPanel header
• Selection: clicking an agent item immediately calls PATCH /api/conversations/:id with { agentId } and updates local state optimistically
• Error: if PATCH fails, revert to previous agent selection and show a toast: "Couldn't update agent. Try again."
• The selected agent takes effect on the next message sent — it does NOT retroactively re-label past messages

Slash command and @mention routing (INPUT-05, INPUT-06)

• Slash command: when ChatInput contains /ask-engineer Hello, the command prefix is parsed before send; the message body "Hello" is sent with targetRole: "engineer" as a per-message agent override; the conversation's agentId is NOT changed
• @mention: same per-message override behavior; @engineer Hello extracts targetName: "engineer" and resolves to the matching agent by name (case-insensitive)
• If a command is recognized but the target agent does not exist in useAgents() cache: show inline toast "No engineer agent found. Message sent to active agent." and fall back to conversation.agentId
• If the / prefix does not match any known command: send as plain text (no routing, no error)
• Popover keyboard navigation: arrow keys move selection, Enter selects, Tab accepts, Escape dismisses

Auto-scroll behavior during streaming (PERF-03)

• When isAtBottom === true at the time a new token arrives: call listRef.current?.scrollToIndex(allMessages.length - 1, { smooth: false }) to keep bottom in view
• When user has scrolled up (isAtBottom === false): do NOT scroll; show a "Jump to bottom" button: <Button variant="outline" size="sm"> with a ChevronDown icon (16px), positioned absolute bottom-20 right-4 z-10 relative to the message list container. Clicking it scrolls to bottom and sets isAtBottom = true
• "Jump to bottom" button disappears immediately when isAtBottom === true

---

Copywriting Contract

Source: Claude's discretion (discuss phase skipped). Follows Phase 21 tone: direct, lowercase preference, no corporate language.

Element	Copy
Stop button tooltip	"Stop generation"
Retry button tooltip	"Retry response"
Edit button tooltip (on user message)	"Edit message"
Edit confirm button	"Regenerate"
Edit cancel instruction	Press Escape to cancel
Streaming indicator aria-label	"Response streaming"
Agent selector tooltip	"Active agent for this conversation"
Agent selector empty	"No agents configured"
Jump to bottom button aria-label	"Jump to bottom"
Slash command popover heading	(none — no heading; list items self-describe)
@mention popover heading	(none — no heading; agent names self-describe)
Error: stream failed	"Response failed. Try again."
Error: edit failed	"Couldn't update message. Try again."
Error: agent update failed	"Couldn't update agent. Try again."
Error: target agent not found	"No {role} agent found. Message sent to active agent."
Error: retry failed	"Retry failed. Try again."
Toast on stop (if partial message not saved)	(no toast — stopping is expected; silent is correct)

No new destructive actions in Phase 22. The Stop generation action is a cancellation, not a destructive action — no confirmation required.

---

Accessibility Contract

Carried forward from Phase 21. Phase 22 additions:

• ChatAgentBadge avatar: aria-hidden="true" (decorative — the agent name provides the text label)
• Agent name in ChatAgentBadge: aria-label="Agent: {agent.name}" on the containing span
• AgentSelector trigger: aria-label="Active agent: {currentAgent.name}" (dynamically updated)
• Stop button: aria-label="Stop generation", never aria-disabled — always interactive during streaming
• Streaming message container: aria-live="off" — do NOT use aria-live="polite" on the partial content container; the completed persisted message in the role="log" container is sufficient for screen reader announcement. Streaming token-by-token announcement would be noisy.
• Edit textarea: aria-label="Edit message", aria-multiline="true"
• "Jump to bottom" button: aria-label="Jump to bottom", aria-hidden="true" when not visible
• Slash command popover: role="listbox", each item role="option", aria-selected on highlighted item
• @mention popover: same role="listbox" pattern

---

Animation Contract

All animations use Tailwind utilities or existing CSS transitions. No new animation libraries.

Carried from Phase 21:

Element	Animation	Duration	Easing
Chat panel open/close	transition-[width]	100ms	ease-out
Conversation list item hover	transition-colors	150ms	Tailwind default

Phase 22 additions:

Element	Animation	Duration	Easing
Streaming cursor dot	animate-pulse (Tailwind)	continuous	built-in
Message action buttons (edit/retry/stop)	transition-opacity	150ms	ease-out
Send → Stop button swap	transition-opacity	100ms	ease-out (cross-fade; layout does NOT shift)
"Jump to bottom" button appear/disappear	transition-opacity	150ms	ease-out
AgentSelector dropdown open	Radix <Select> built-in animation	150ms	Radix default
Slash/mention popover open	transition-opacity duration-100	100ms	ease-out

No enter/exit animations for new streaming tokens — tokens append directly with no animation. This keeps PERF-02 (100ms latency) achievable without layout thrashing.

---

Registry Safety

Registry	Blocks Used	Safety Gate
shadcn official	All components from Phase 21 + Command, Popover, Select (already installed)	not required
Third-party registries	none	not applicable

virtua is installed via npm (not shadcn registry). npm packages are not subject to the shadcn registry safety gate.

No third-party shadcn registry blocks are declared for this phase.

---

Checker Sign-Off

• Dimension 1 Copywriting: PASS
• Dimension 2 Visuals: PASS
• Dimension 3 Color: PASS
• Dimension 4 Typography: PASS
• Dimension 5 Spacing: PASS
• Dimension 6 Registry Safety: PASS

Approval: pending