A portable UX contract, not a skin
The pattern language for AI agents
Agentic patterns with machine-readable specs. Each pattern ships with a UX spec the harness can read, not just markup — guardrails for what to render, when, and why.
Ask about a pattern, or try one below…
Create Agent
A two-step wizard card for naming an agent, picking its icon, and selecting which event sources activate it.
New agent
Name your agent
Give it a name, instructions, and an icon.
- Require approvalHuman must approve before any write action
- Read-only by defaultCannot push code or send messages directly
- Limit to 1 action per triggerPrevents runaway loops on rapid events
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import {
Antenna,
AtSign,
Bot,
Brain,
Check,
ChevronRight,
Code2,
Compass,
Cpu,
Database,
Eye,
FlaskConical,
GitBranch,
Globe,
Layers,
Lightbulb,
Plus,
Rocket,
Search,
Server,
Shield,
ShieldAlert,
ShieldOff,
Sparkles,
Star,
Terminal,
Webhook,
Wrench,
X,
Zap,
} from "lucide-react";
import { cn } from "@/lib/utils";
// ── Trigger sources ──────────────────────────────────────────────────────────
interface TriggerField {
id: string;
label: string;
type: "text" | "select";
placeholder?: string;
options?: { value: string; label: string }[];
}
export const TRIGGER_SOURCES = [
{
id: "github" as const,
label: "GitHub",
icon: GitBranch,
description: "Issues, pull requests, and labels",
fields: [
{
id: "repo",
label: "Repository",
type: "text" as const,
placeholder: "e.g. carlosmarch/ai-patterns",
},
{
id: "event",
label: "Event",
type: "select" as const,
options: [
{ value: "issue-labeled", label: "Issue labeled" },
{ value: "pr-opened", label: "PR opened" },
{ value: "pr-merged", label: "PR merged" },
],
},
] satisfies TriggerField[],
},
{
id: "slack" as const,
label: "Slack",
icon: AtSign,
description: "Mentions, messages, and reactions",
fields: [
{
id: "channel",
label: "Channel",
type: "text" as const,
placeholder: "e.g. #design-requests",
},
{
id: "event",
label: "Trigger on",
type: "select" as const,
options: [
{ value: "mention", label: "Agent mentioned" },
{ value: "keyword", label: "Keyword match" },
],
},
] satisfies TriggerField[],
},
{
id: "figma" as const,
label: "Figma",
icon: Layers,
description: "Frame status changes and comments",
fields: [
{
id: "scope",
label: "Files",
type: "select" as const,
options: [
{ value: "any", label: "Any Figma file" },
{ value: "specific", label: "Specific file URL" },
],
},
{
id: "event",
label: "Event",
type: "select" as const,
options: [
{ value: "ready-for-dev", label: "Frame ready for dev" },
{ value: "comment", label: "New comment" },
],
},
] satisfies TriggerField[],
},
] as const;
export type TriggerSourceId = (typeof TRIGGER_SOURCES)[number]["id"];
// ── Agent icons ───────────────────────────────────────────────────────────────
export const AGENT_ICONS = [
{ id: "bot" as const, icon: Bot, label: "Bot" },
{ id: "sparkles" as const, icon: Sparkles, label: "Sparkles" },
{ id: "zap" as const, icon: Zap, label: "Zap" },
{ id: "brain" as const, icon: Brain, label: "Brain" },
{ id: "rocket" as const, icon: Rocket, label: "Rocket" },
] as const;
export const EXTRA_AGENT_ICONS = [
{ id: "cpu" as const, icon: Cpu, label: "CPU" },
{ id: "globe" as const, icon: Globe, label: "Globe" },
{ id: "terminal" as const, icon: Terminal, label: "Terminal" },
{ id: "code2" as const, icon: Code2, label: "Code" },
{ id: "wrench" as const, icon: Wrench, label: "Wrench" },
{ id: "search" as const, icon: Search, label: "Search" },
{ id: "eye" as const, icon: Eye, label: "Eye" },
{ id: "star" as const, icon: Star, label: "Star" },
{ id: "database" as const, icon: Database, label: "Database" },
{ id: "server" as const, icon: Server, label: "Server" },
{ id: "lightbulb" as const, icon: Lightbulb, label: "Lightbulb" },
{ id: "compass" as const, icon: Compass, label: "Compass" },
{ id: "flask" as const, icon: FlaskConical, label: "Flask" },
{ id: "antenna" as const, icon: Antenna, label: "Antenna" },
] as const;
export const ALL_AGENT_ICONS = [...AGENT_ICONS, ...EXTRA_AGENT_ICONS];
export type AgentIconId = (typeof ALL_AGENT_ICONS)[number]["id"];
// ── Guardrails ────────────────────────────────────────────────────────────────
export interface Guardrail {
id: string;
label: string;
description: string;
icon: React.ComponentType<{ className?: string }>;
enabled: boolean;
}
export const DEFAULT_GUARDRAILS: Guardrail[] = [
{
id: "approval-required",
label: "Require approval",
description: "Human must approve before any write action",
icon: ShieldAlert,
enabled: true,
},
{
id: "read-only",
label: "Read-only by default",
description: "Cannot push code or send messages directly",
icon: ShieldOff,
enabled: true,
},
{
id: "rate-limit",
label: "Limit to 1 action per trigger",
description: "Prevents runaway loops on rapid events",
icon: Shield,
enabled: false,
},
];
// ── Payload ───────────────────────────────────────────────────────────────────
export interface SelectedTrigger {
sourceId: TriggerSourceId;
config: Record<string, string>;
}
export interface CustomTrigger {
id: string;
name: string;
event: string;
}
export interface CreateAgentPayload {
name: string;
instructions: string;
iconId: AgentIconId;
guardrails: { id: string; enabled: boolean }[];
triggers: SelectedTrigger[];
customTriggers: CustomTrigger[];
}
// ── Props ─────────────────────────────────────────────────────────────────────
export interface CreateAgentProps {
onCreateAgent?: (payload: CreateAgentPayload) => void;
className?: string;
}
// ── Component ─────────────────────────────────────────────────────────────────
export function CreateAgent({ onCreateAgent, className }: CreateAgentProps) {
const [step, setStep] = React.useState<0 | 1>(0);
const [direction, setDirection] = React.useState<1 | -1>(1);
const [name, setName] = React.useState("");
const [instructions, setInstructions] = React.useState("");
const [iconId, setIconId] = React.useState<AgentIconId>("bot");
const [selectedSources, setSelectedSources] = React.useState<TriggerSourceId[]>([]);
const [triggerConfigs, setTriggerConfigs] = React.useState<
Partial<Record<TriggerSourceId, Record<string, string>>>
>({});
const [customTriggers, setCustomTriggers] = React.useState<CustomTrigger[]>([]);
const [showMoreIcons, setShowMoreIcons] = React.useState(false);
const [guardrailStates, setGuardrailStates] = React.useState<Record<string, boolean>>(
Object.fromEntries(DEFAULT_GUARDRAILS.map((g) => [g.id, g.enabled]))
);
const selectedIcon = ALL_AGENT_ICONS.find((i) => i.id === iconId)!;
const SelectedIconComp = selectedIcon.icon;
function goToStep1() {
setDirection(1);
setStep(1);
}
function goToStep0() {
setDirection(-1);
setStep(0);
}
function toggleSource(id: TriggerSourceId) {
setSelectedSources((prev) =>
prev.includes(id) ? prev.filter((s) => s !== id) : [...prev, id]
);
}
function setTriggerField(sourceId: TriggerSourceId, fieldId: string, value: string) {
setTriggerConfigs((prev) => ({
...prev,
[sourceId]: { ...prev[sourceId], [fieldId]: value },
}));
}
function addCustomTrigger() {
setCustomTriggers((prev) => [
...prev,
{ id: `custom-${Date.now()}`, name: "", event: "" },
]);
}
function updateCustomTrigger(id: string, field: keyof Omit<CustomTrigger, "id">, value: string) {
setCustomTriggers((prev) =>
prev.map((t) => (t.id === id ? { ...t, [field]: value } : t))
);
}
function removeCustomTrigger(id: string) {
setCustomTriggers((prev) => prev.filter((t) => t.id !== id));
}
function toggleGuardrail(id: string) {
setGuardrailStates((prev) => ({ ...prev, [id]: !prev[id] }));
}
function buildPayload(): CreateAgentPayload {
return {
name: name.trim() || "Unnamed Agent",
instructions: instructions.trim(),
iconId,
guardrails: DEFAULT_GUARDRAILS.map((g) => ({ id: g.id, enabled: guardrailStates[g.id] ?? g.enabled })),
triggers: selectedSources.map((sourceId) => ({
sourceId,
config: triggerConfigs[sourceId] ?? {},
})),
customTriggers,
};
}
const variants = {
enter: (dir: number) => ({ x: dir * 16, opacity: 0 }),
center: { x: 0, opacity: 1 },
exit: (dir: number) => ({ x: dir * -16, opacity: 0 }),
};
return (
<div suppressHydrationWarning className={cn("w-full max-w-xs overflow-hidden rounded-2xl border bg-card", className)}>
{/* Header preview */}
<div className="flex items-center justify-between gap-3 border-b px-4 py-3">
<div className="flex min-w-0 items-center gap-2">
<span className="flex size-7 shrink-0 items-center justify-center rounded-full bg-muted text-muted-foreground">
<SelectedIconComp className="size-3.5" />
</span>
<p className="truncate text-sm font-semibold text-foreground">
{name.trim() || "New agent"}
</p>
</div>
<div className="flex shrink-0 items-center gap-1" aria-hidden>
{[0, 1].map((i) => (
<span
key={i}
className={cn(
"block h-1.5 rounded-full transition-all duration-200",
step === i ? "w-4 bg-foreground" : "w-1.5 bg-muted-foreground/30"
)}
/>
))}
</div>
</div>
{/* Steps */}
<div className="relative overflow-hidden">
<AnimatePresence initial={false} custom={direction} mode="wait">
{step === 0 ? (
<motion.div
key="step-identity"
custom={direction}
variants={variants}
initial="enter"
animate="center"
exit="exit"
transition={{ duration: 0.15, ease: "easeInOut" }}
className="px-4 pb-4 pt-3"
>
<p className="text-sm font-semibold">Name your agent</p>
<p className="mt-0.5 text-xs text-muted-foreground">
Give it a name, instructions, and an icon.
</p>
<input
type="text"
value={name}
onChange={(e) => setName(e.target.value)}
placeholder="e.g. AI-Patterns"
aria-label="Agent name"
className="mt-3 w-full rounded-lg border bg-background px-3 py-2 text-sm outline-none ring-ring placeholder:text-muted-foreground/50 focus-visible:ring-2"
/>
<textarea
value={instructions}
onChange={(e) => setInstructions(e.target.value)}
placeholder="e.g. When a GitHub issue is labeled pattern-request in carlosmarch/ai-patterns, triage it and suggest a matching component."
aria-label="Agent instructions"
rows={3}
className="mt-2 w-full resize-none rounded-lg border bg-background px-3 py-2 text-sm outline-none ring-ring placeholder:text-muted-foreground/50 focus-visible:ring-2"
/>
<ul className="mt-3 divide-y rounded-xl border">
{DEFAULT_GUARDRAILS.map(({ id, label, description, icon: Icon }) => {
const enabled = guardrailStates[id] ?? false;
return (
<li key={id} className="flex items-center gap-3 px-3 py-2.5">
<span className={cn("flex size-6 shrink-0 items-center justify-center rounded text-muted-foreground")}>
<Icon className="size-3.5" />
</span>
<span className="min-w-0 flex-1">
<span className="block text-xs font-medium">{label}</span>
<span className="block text-[11px] text-muted-foreground">{description}</span>
</span>
<button
type="button"
role="switch"
aria-checked={enabled}
aria-label={label}
onClick={() => toggleGuardrail(id)}
className={cn(
"relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
enabled ? "bg-foreground" : "bg-muted"
)}
>
<motion.span
aria-hidden
className="pointer-events-none inline-block h-4 w-4 rounded-full bg-background shadow-sm"
animate={{ x: enabled ? 16 : 0 }}
transition={{ type: "spring", stiffness: 500, damping: 30 }}
/>
</button>
</li>
);
})}
</ul>
<div className="mt-3 space-y-1.5">
<div className="flex items-center gap-1.5">
{AGENT_ICONS.map(({ id, icon: Icon, label }) => (
<button
key={id}
type="button"
aria-label={label}
aria-pressed={iconId === id}
onClick={() => setIconId(id)}
className={cn(
"flex size-8 items-center justify-center rounded-lg transition-colors",
iconId === id
? "bg-foreground text-background"
: "bg-muted text-muted-foreground hover:text-foreground"
)}
>
<Icon className="size-4" />
</button>
))}
<button
type="button"
aria-label={showMoreIcons ? "Show fewer icons" : "Show more icons"}
aria-expanded={showMoreIcons}
onClick={() => setShowMoreIcons((v) => !v)}
className={cn(
"flex size-8 items-center justify-center rounded-lg transition-colors",
showMoreIcons
? "bg-muted text-foreground"
: "bg-muted text-muted-foreground hover:text-foreground"
)}
>
<Plus className={cn("size-4 transition-transform duration-150", showMoreIcons && "rotate-45")} />
</button>
</div>
<AnimatePresence initial={false}>
{showMoreIcons && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.15, ease: "easeInOut" }}
className="overflow-hidden"
>
<div className="flex flex-wrap gap-1.5 pt-0.5">
{EXTRA_AGENT_ICONS.map(({ id, icon: Icon, label }) => (
<button
key={id}
type="button"
aria-label={label}
aria-pressed={iconId === id}
onClick={() => { setIconId(id); setShowMoreIcons(false); }}
className={cn(
"flex size-8 items-center justify-center rounded-lg transition-colors",
iconId === id
? "bg-foreground text-background"
: "bg-muted text-muted-foreground hover:text-foreground"
)}
>
<Icon className="size-4" />
</button>
))}
</div>
</motion.div>
)}
</AnimatePresence>
</div>
<button
type="button"
onClick={goToStep1}
className="mt-4 flex w-full items-center justify-center gap-1.5 rounded-lg bg-foreground px-4 py-2 text-sm font-medium text-background transition-opacity hover:opacity-90"
>
Choose triggers
<ChevronRight className="size-3.5" />
</button>
<button
type="button"
onClick={() => onCreateAgent?.(buildPayload())}
className="mt-2 w-full text-center text-xs text-muted-foreground transition-colors hover:text-foreground"
>
Skip triggers
</button>
</motion.div>
) : (
<motion.div
key="step-triggers"
custom={direction}
variants={variants}
initial="enter"
animate="center"
exit="exit"
transition={{ duration: 0.15, ease: "easeInOut" }}
className="px-4 pb-4 pt-3"
>
<p className="text-sm font-semibold">Choose triggers</p>
<p className="mt-0.5 text-xs text-muted-foreground">
Select the sources that activate this agent.
</p>
<ul className="mt-3 flex flex-col gap-2">
{TRIGGER_SOURCES.map(({ id, label, icon: Icon, description, fields }) => {
const isSelected = selectedSources.includes(id);
const config = triggerConfigs[id] ?? {};
return (
<li key={id} className={cn("rounded-xl border transition-colors", isSelected ? "border-foreground/20 bg-muted/40" : "")}>
{/* Toggle row */}
<button
type="button"
aria-pressed={isSelected}
onClick={() => toggleSource(id)}
className="flex w-full items-center gap-3 px-3 py-2.5 text-left"
>
<span className="flex size-7 shrink-0 items-center justify-center rounded-md border bg-background text-muted-foreground">
<Icon className="size-3.5" />
</span>
<span className="min-w-0 flex-1">
<span className="block text-xs font-medium">{label}</span>
<span className="block text-[11px] text-muted-foreground">{description}</span>
</span>
<span
className={cn(
"flex size-4 shrink-0 items-center justify-center rounded-full border transition-colors",
isSelected
? "border-foreground bg-foreground text-background"
: "border-muted-foreground/30"
)}
>
{isSelected && <Check className="size-2.5" strokeWidth={3} />}
</span>
</button>
{/* Expanded config */}
<AnimatePresence initial={false}>
{isSelected && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.15, ease: "easeInOut" }}
className="overflow-hidden"
>
<div className="flex flex-col gap-2 border-t px-3 pb-3 pt-2.5">
{fields.map((field) => (
<div key={field.id} className="flex flex-col gap-1">
<label className="text-[11px] font-medium text-muted-foreground">
{field.label}
</label>
{field.type === "text" ? (
<input
type="text"
value={config[field.id] ?? ""}
onChange={(e) => setTriggerField(id, field.id, e.target.value)}
placeholder={field.placeholder}
className="w-full rounded-md border bg-background px-2.5 py-1.5 text-xs outline-none ring-ring placeholder:text-muted-foreground/40 focus-visible:ring-2"
/>
) : (
<select
value={config[field.id] ?? field.options?.[0]?.value ?? ""}
onChange={(e) => setTriggerField(id, field.id, e.target.value)}
className="w-full rounded-md border bg-background px-2.5 py-1.5 text-xs outline-none ring-ring focus-visible:ring-2"
>
{field.options?.map((opt) => (
<option key={opt.value} value={opt.value}>
{opt.label}
</option>
))}
</select>
)}
</div>
))}
</div>
</motion.div>
)}
</AnimatePresence>
</li>
);
})}
</ul>
{/* Custom triggers */}
<AnimatePresence initial={false}>
{customTriggers.map((ct) => (
<motion.div
key={ct.id}
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.15, ease: "easeInOut" }}
className="overflow-hidden"
>
<div className="mt-2 rounded-xl border border-foreground/20 bg-muted/40">
<div className="flex items-center gap-2 px-3 py-2.5">
<span className="flex size-7 shrink-0 items-center justify-center rounded-md border bg-background text-muted-foreground">
<Webhook className="size-3.5" />
</span>
<span className="flex-1 text-xs font-medium text-muted-foreground">
Custom trigger
</span>
<button
type="button"
aria-label="Remove custom trigger"
onClick={() => removeCustomTrigger(ct.id)}
className="flex size-5 items-center justify-center rounded text-muted-foreground/50 transition-colors hover:text-foreground"
>
<X className="size-3.5" />
</button>
</div>
<div className="flex flex-col gap-2 border-t px-3 pb-3 pt-2.5">
<div className="flex flex-col gap-1">
<label className="text-[11px] font-medium text-muted-foreground">
Name
</label>
<input
type="text"
value={ct.name}
onChange={(e) => updateCustomTrigger(ct.id, "name", e.target.value)}
placeholder="e.g. Webhook received"
className="w-full rounded-md border bg-background px-2.5 py-1.5 text-xs outline-none ring-ring placeholder:text-muted-foreground/40 focus-visible:ring-2"
/>
</div>
<div className="flex flex-col gap-1">
<label className="text-[11px] font-medium text-muted-foreground">
Event source
</label>
<input
type="text"
value={ct.event}
onChange={(e) => updateCustomTrigger(ct.id, "event", e.target.value)}
placeholder="e.g. POST /webhooks/my-agent"
className="w-full rounded-md border bg-background px-2.5 py-1.5 text-xs outline-none ring-ring placeholder:text-muted-foreground/40 focus-visible:ring-2"
/>
</div>
</div>
</div>
</motion.div>
))}
</AnimatePresence>
<button
type="button"
onClick={addCustomTrigger}
className="mt-2 flex w-full items-center gap-1.5 rounded-lg border border-dashed px-3 py-2 text-xs text-muted-foreground transition-colors hover:border-foreground/30 hover:text-foreground"
>
<Plus className="size-3.5" />
Add custom trigger
</button>
<div className="mt-3 flex gap-2">
<button
type="button"
onClick={goToStep0}
className="flex-1 rounded-lg border px-4 py-2 text-sm font-medium transition-colors hover:bg-muted"
>
Back
</button>
<button
type="button"
onClick={() => onCreateAgent?.(buildPayload())}
className="flex-1 rounded-lg bg-foreground px-4 py-2 text-sm font-medium text-background transition-opacity hover:opacity-90"
>
Create agent
</button>
</div>
</motion.div>
)}
</AnimatePresence>
</div>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Create Agent
## Summary
A 2-step wizard card for creating a named, icon-identified agent and selecting which external event sources activate it. Step 1 captures identity (name and icon); Step 2 captures trigger sources. On completion it emits a typed payload that maps directly onto the Agent Triggers panel.
## When to use
- First-time agent creation where no agent exists yet.
- Onboarding flows that walk users through setting up their first automation.
- An agent catalog screen with an "Add agent" entry point that opens an inline or sheet-level wizard.
## When not to use
- Editing an existing agent's trigger sources — use the Agent Triggers pattern directly, which has per-trigger toggles and a "Finish setup" inline action.
- When only one trigger source is possible. Presenting a multi-select of one option adds unnecessary friction; skip to a single confirmation step instead.
- When agent creation is complex enough to require a full-page form (multiple steps beyond identity and triggers, required integrations, permissions review, etc.).
## Anatomy
1. **Header preview row** — always visible across both steps. Shows the currently selected icon in a rounded avatar, the live agent name (or "New agent" placeholder), and two step-progress dots.
2. **Step 1 — Identity** — a title/subtitle label pair, a text input for the agent name, a row of five icon-picker buttons (Bot, Sparkles, Zap, Brain, Rocket), and a full-width "Choose triggers →" CTA.
3. **Step 2 — Triggers** — a title/subtitle label pair, a `<ul>` of trigger source cards (each with a bordered icon square, a label and description, and a trailing checkmark circle), and a two-button footer with "Back" (outline) and "Create agent" (filled).
## Behavior
- The header preview row updates in real time: the name reflects every keystroke; the icon swaps immediately on selection. This gives users continuous feedback on how the finished agent will appear elsewhere in the product.
- Icon selection is immediate with no confirm step — clicking a picker button applies it at once.
- Trigger source cards are multi-select toggle buttons. The user may select zero, one, or all sources; there is no minimum enforcement in the component (enforce constraints in the consuming view if needed).
- Navigating from Step 1 to Step 2 slides content in from the right; navigating back slides from the left. AnimatePresence with `mode="wait"` ensures the outgoing step fully exits before the incoming step enters.
- "Create agent" is the terminal action. It fires `onCreateAgent` with a payload of `{ name, iconId, triggerSources }` and hands control entirely to the parent. The component itself has no post-creation state.
- The "Back" button does not reset Step 1 state — name and icon choices are preserved across forward/back navigation.
## Content guidelines
- Agent names should be short proper nouns or noun phrases that describe the agent's role, not its mechanism: "Pattern Bot", "Deploy Guard", "Design Review" — not "github-trigger-agent-v2".
- The placeholder text "e.g. Pattern Bot" demonstrates the expected format; replace it with a placeholder appropriate to the product domain.
- Trigger source labels name the platform (GitHub, Slack, Figma). Descriptions name the event type that fires the agent, not the agent's response: "Issues, pull requests, and labels" not "Monitors your repo and responds to issues".
- The "Create agent" button label should always say exactly that — avoid "Save", "Done", or "Finish", which imply the agent already exists.
## Accessibility
- The name input has a visible `<p>` label ("Name your agent") immediately above it and an `aria-label` attribute for programmatic association.
- Each icon-picker button has an `aria-label` naming the icon (e.g. "Sparkles") and `aria-pressed` reflecting selection state.
- Each trigger source card is a `<button>` with `aria-pressed` reflecting whether it is selected.
- The step-progress dots in the header are `aria-hidden` — they are a decorative visual indicator, not a navigation control.
- Step transitions use motion that respects `prefers-reduced-motion` via Motion's default behavior; the `duration: 0.15` transitions are brief enough that they cause minimal disruption even without the media-query guard.
## Related patterns
- **Agent Triggers** — the panel displayed after a successful `onCreateAgent` callback. The payload from Create Agent maps directly to Agent Triggers' `title`, `agent`, and `triggers` props.
- **Setup Checklist** — use for multi-step onboarding of a whole product or feature area when several independent tasks must be completed, not a single wizard with two sequential screens.
- **Invite Members** — shares the "create something new" modal shape: header preview, multi-step form, terminal action. Reference for visual consistency when both patterns appear in the same product.
Agent Triggers
A configuration panel for listing and toggling the external events that activate an agent, with a manual run control.
AI-Patterns
When should this agent run?
Issue labeled pattern-request in carlosmarch/ai-patterns
When AI-Patterns is mentioned in #design-requests
Frame marked ready for dev in any Figma file
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { AtSign, GitBranch, GitPullRequest, Layers, Play, Plus } from "lucide-react";
import { cn } from "@/lib/utils";
export interface AgentTrigger {
id: string;
icon: React.ComponentType<{ className?: string }>;
event: string;
context: string;
enabled: boolean;
needsSetup?: boolean;
}
export interface AgentAvatar {
name: string;
src?: string;
icon?: React.ComponentType<{ className?: string }>;
}
export interface AgentTriggersProps {
title?: string;
description?: string;
agent?: AgentAvatar;
triggers?: AgentTrigger[];
onRunAgent?: () => void;
onToggle?: (id: string, enabled: boolean) => void;
onAddTrigger?: (platformId?: string) => void;
onFinishSetup?: (id: string) => void;
className?: string;
}
const QUICK_ADD_PLATFORMS = [
{ id: "github", label: "GitHub", icon: GitBranch },
{ id: "slack", label: "Slack", icon: AtSign },
{ id: "figma", label: "Figma", icon: Layers },
] as const;
export const DEFAULT_TRIGGERS: AgentTrigger[] = [
{
id: "github-issue",
icon: GitPullRequest,
event: "Issue labeled pattern-request",
context: "in carlosmarch/ai-patterns",
enabled: true,
},
{
id: "slack-mention",
icon: AtSign,
event: "When AI-Patterns is mentioned",
context: "in #design-requests",
enabled: true,
},
{
id: "figma-ready",
icon: Layers,
event: "Frame marked ready for dev",
context: "in any Figma file",
enabled: false,
needsSetup: true,
},
];
function Avatar({ agent }: { agent: AgentAvatar }) {
return (
<span className="flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-full bg-muted text-muted-foreground">
{agent.src ? (
<img src={agent.src} alt={agent.name} className="size-full object-cover" />
) : agent.icon ? (
<agent.icon className="size-4" />
) : (
<span className="text-xs font-semibold">
{agent.name.split(" ").map((w) => w[0]).slice(0, 2).join("").toUpperCase()}
</span>
)}
</span>
);
}
function Toggle({ enabled, onChange }: { enabled: boolean; onChange: (v: boolean) => void }) {
return (
<button
type="button"
role="switch"
aria-checked={enabled}
onClick={() => onChange(!enabled)}
className={cn(
"relative inline-flex h-5 w-9 shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-150 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
enabled ? "bg-foreground" : "bg-muted"
)}
>
<motion.span
aria-hidden
className="pointer-events-none inline-block h-4 w-4 rounded-full bg-background shadow-sm"
animate={{ x: enabled ? 16 : 0 }}
transition={{ type: "spring", stiffness: 500, damping: 30 }}
/>
</button>
);
}
export function AgentTriggers({
title = "Triggers",
description = "When should this agent run?",
agent,
triggers: initialTriggers = DEFAULT_TRIGGERS,
onRunAgent,
onToggle,
onAddTrigger,
onFinishSetup,
className,
}: AgentTriggersProps) {
const [triggers, setTriggers] = React.useState(initialTriggers);
const [running, setRunning] = React.useState(false);
function handleToggle(id: string, value: boolean) {
setTriggers((prev) => prev.map((t) => (t.id === id ? { ...t, enabled: value } : t)));
onToggle?.(id, value);
}
function handleRun() {
if (running) return;
setRunning(true);
onRunAgent?.();
setTimeout(() => setRunning(false), 2200);
}
return (
<div className={cn("w-full max-w-xs overflow-hidden rounded-2xl border bg-card", className)}>
<div className="flex items-start justify-between gap-3 px-4 pb-3 pt-4">
<div className="flex min-w-0 items-center gap-2.5">
{agent && <Avatar agent={agent} />}
<div className="min-w-0">
<p className="text-sm font-semibold">{title}</p>
<p className="text-xs text-muted-foreground">{description}</p>
</div>
</div>
<button
type="button"
onClick={handleRun}
disabled={running}
className={cn(
"flex shrink-0 items-center gap-1.5 rounded-full border px-3 py-1.5 text-xs font-medium transition-colors disabled:pointer-events-none",
running ? "border-transparent bg-foreground text-background" : "hover:bg-accent"
)}
>
<Play className={cn("size-3 transition-all", running ? "fill-current" : "fill-none stroke-current")} />
<AnimatePresence mode="wait" initial={false}>
<motion.span
key={running ? "running" : "idle"}
initial={{ opacity: 0, y: 3 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -3 }}
transition={{ duration: 0.1 }}
>
{running ? "Running…" : "Run agent"}
</motion.span>
</AnimatePresence>
</button>
</div>
<ul className="divide-y border-t">
{triggers.map((trigger) => (
<li key={trigger.id} className="flex items-center gap-3 px-4 py-2.5">
<span className="flex size-6 shrink-0 items-center justify-center rounded text-muted-foreground">
<trigger.icon className="size-3.5" />
</span>
<p className="min-w-0 flex-1 text-xs leading-snug">
<span className="font-medium">{trigger.event}</span>{" "}
<span className="text-muted-foreground">{trigger.context}</span>
</p>
<div className="flex shrink-0 items-center gap-2">
{trigger.needsSetup && !trigger.enabled && (
<button
type="button"
onClick={() => onFinishSetup?.(trigger.id)}
className="text-[11px] text-muted-foreground underline underline-offset-2 transition-colors hover:text-foreground"
>
Finish setup
</button>
)}
<Toggle enabled={trigger.enabled} onChange={(v) => handleToggle(trigger.id, v)} />
</div>
</li>
))}
</ul>
<div className="flex items-center gap-2 border-t px-4 py-2.5">
<button
type="button"
onClick={() => onAddTrigger?.()}
className="flex items-center gap-1.5 text-xs text-muted-foreground transition-colors hover:text-foreground"
>
<Plus className="size-3.5" />
Add trigger
</button>
<div className="ml-0.5 flex items-center gap-0.5">
{QUICK_ADD_PLATFORMS.map(({ id, label, icon: Icon }) => (
<button
key={id}
type="button"
aria-label={`Add ${label} trigger`}
onClick={() => onAddTrigger?.(id)}
className="flex size-5 items-center justify-center rounded text-muted-foreground/50 transition-colors hover:text-muted-foreground"
>
<Icon className="size-3.5" />
</button>
))}
</div>
</div>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Agent Triggers
## Summary
A configuration panel listing the external events that cause an agent to run automatically, each with an on/off toggle and an optional "Finish setup" prompt for incomplete integrations. A "Run agent" button lets the user fire the agent on demand outside of any trigger, and a footer row provides one-click entry points for adding new trigger sources.
## When to use
- In an agent or automation settings panel where users define when a workflow should start.
- When an agent can be connected to multiple external sources (GitHub, Slack, Figma, etc.) and users need to pick which ones activate it.
- Alongside an agent canvas or workflow builder, as the entry-point node configuration.
## When not to use
- For simple scheduled or time-based recurrence — use a cron or schedule picker instead; event-based and time-based triggers have different mental models and should not share this component.
- When there is only ever one possible trigger — a list of one is not a list; use a single connection widget or toggle.
- As a general settings list. This component is about activation conditions, not preferences.
## Anatomy
- Header: a title ("Triggers") and a subtitle ("When should this agent run?") scoped to the agent being configured.
- Run agent button: an outlined play button in the header that fires the agent manually, independent of any trigger. It enters a transient "Running…" state while the agent executes.
- Trigger list: one row per trigger, each containing an icon that identifies the source, an event name in medium weight followed by a muted location context ("in Slack", "in carlosmarch/ai-patterns"), and a toggle on the trailing edge.
- Finish setup label: a small underlined text link that appears before the toggle when a trigger has been added but not yet fully configured. Enables the trigger rather than completing setup inline — that flow belongs in a dedicated integration modal.
- Add trigger footer: a "＋ Add trigger" text button plus icon shortcuts for common source platforms (GitHub, Slack, Figma). Both lead to the same source-picker; the icons are just accelerators for recognized integrations.
## Behavior
- Toggling a trigger on/off is immediate and optimistic — the UI updates before the server round-trip. If the save fails, revert and surface an error.
- "Finish setup" shows only when `needsSetup` is true and the trigger is currently off. Once the user enables the trigger (completing setup), the label disappears.
- Run agent is a one-shot control: clicking it disables the button and swaps its label to "Running…" until the run resolves, then restores the idle state. It does not reflect ongoing trigger-based runs.
- The trigger list is non-reorderable — triggers fire in parallel on any matching event, so order has no semantic meaning.
- Adding a new trigger appends it to the list in a needs-setup state with the toggle off; the "Finish setup" label appears immediately.
## Content guidelines
- Event names are short noun phrases or gerunds that describe the inbound event, not the agent's response to it: "Issue labeled pattern-request", "Frame marked ready for dev". Start with the noun (Issue, Frame, Message) so items scan consistently when the list grows.
- The context string names the specific location in sentence-case with no trailing period: "in carlosmarch/ai-patterns", "in any Figma file".
- Platform icons should match the brand icon for the integration, not a generic glyph. When a brand icon isn't available, use a domain-appropriate generic (a hashtag for channels, an @ for mention events).
## Accessibility
- The toggle must be a `<button role="switch" aria-checked={enabled}>` — not a styled `<div>` — so screen readers announce the state change.
- Each toggle must have an accessible label. Since the label is provided by the adjacent row text, use `aria-labelledby` pointing to the event name element, or wrap the row in a `<label>`.
- "Finish setup" must be keyboard reachable and announce where it leads: `aria-label="Finish setup for Frame marked ready for dev"`.
- The quick-add platform icons in the footer are icon-only buttons; each must carry an `aria-label` naming the platform ("Add GitHub trigger").
## Related patterns
- Flowchart: the canvas-level counterpart — Agent Triggers configures the entry-point event, while the Flowchart node describes what conditions gate the work that follows.
- Tool Approval: also governs what an agent is allowed to do, but at the per-call level rather than the activation level.
- Setup Checklist: shares the "incomplete step" affordance (the Finish setup label) — use Setup Checklist when onboarding a whole agent for the first time; use Agent Triggers when managing an already-running agent's event sources.
Human in the Loop Question
A compact dialog that pauses an agent mid-task to collect a structured choice — radio options, a free-text fallback, skip/continue controls, and multi-step pagination.
How should the agent handle ambiguous user intent?
1/3
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { ChevronLeft, ChevronRight, X } from "lucide-react";
import { cn } from "@/lib/utils";
import { ToolCallChip } from "@/registry/loaders/tool-call-chip/component";
export interface HitlOption {
id: string;
label: string;
}
export interface HitlQuestion {
id: string;
question: string;
options: HitlOption[];
freeTextPlaceholder?: string;
}
export interface HumanInTheLoopProps {
questions: HitlQuestion[];
onSubmit?: (answers: Record<string, string>) => void;
onSkip?: () => void;
onClose?: () => void;
/** Called ~500 ms after the resolved chip shows "success". */
onDone?: () => void;
className?: string;
}
export function HumanInTheLoop({
questions,
onSubmit,
onSkip,
onClose,
onDone,
className,
}: HumanInTheLoopProps) {
const [step, setStep] = React.useState(0);
const [answers, setAnswers] = React.useState<Record<string, string>>({});
const [done, setDone] = React.useState(false);
const [chipStatus, setChipStatus] = React.useState<"running" | "success">("running");
React.useEffect(() => {
if (!done) return;
const t1 = setTimeout(() => setChipStatus("success"), 1200);
const t2 = setTimeout(() => onDone?.(), 1700);
return () => { clearTimeout(t1); clearTimeout(t2); };
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [done]);
const current = questions[step];
const total = questions.length;
const selected = answers[current.id];
const isFreeText = selected?.startsWith("free:");
const freeTextValue = isFreeText ? selected.slice(5) : "";
function selectOption(optionId: string) {
setAnswers((prev) => ({ ...prev, [current.id]: optionId }));
}
function setFreeText(value: string) {
setAnswers((prev) => ({ ...prev, [current.id]: `free:${value}` }));
}
function handleContinue() {
if (step < total - 1) {
setStep((s) => s + 1);
} else {
setDone(true);
onSubmit?.(answers);
}
}
function handleSkip() {
if (step < total - 1) {
setStep((s) => s + 1);
} else {
onSkip?.();
}
}
if (done) {
return (
<motion.div
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.18 }}
className={cn("w-full max-w-xs", className)}
>
<ToolCallChip
kind="code"
verb="Resuming"
target="agent task"
status={chipStatus}
result="Agent task resumed"
/>
</motion.div>
);
}
return (
<motion.div
key={step}
initial={{ opacity: 0, y: 6 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.18 }}
className={cn("w-full max-w-xs overflow-visible rounded-2xl border bg-card", className)}
>
{/* Header */}
<div className="flex items-start gap-2 px-4 pt-4 pb-3">
<p className="flex-1 text-xs font-semibold leading-snug">{current.question}</p>
{onClose && (
<button
type="button"
onClick={onClose}
aria-label="Dismiss question"
className="mt-0.5 shrink-0 rounded-md p-0.5 text-muted-foreground transition-colors hover:text-foreground"
>
<X className="size-3.5" />
</button>
)}
</div>
{/* Options */}
<div className="space-y-0 px-4 pb-3">
{current.options.map((option) => {
const isSelected = selected === option.id;
return (
<button
key={option.id}
type="button"
onClick={() => selectOption(option.id)}
className="flex w-full items-center gap-2.5 rounded-lg px-1 py-1.5 text-left transition-colors hover:bg-accent"
>
<span
className={cn(
"flex size-4 shrink-0 items-center justify-center rounded-full border-[1.5px] transition-colors",
isSelected
? "border-foreground bg-foreground"
: "border-muted-foreground/40"
)}
>
{isSelected && <span className="size-1.5 rounded-full bg-white" />}
</span>
<span
className={cn(
"text-xs transition-colors",
isSelected ? "font-medium text-foreground" : "text-muted-foreground"
)}
>
{option.label}
</span>
</button>
);
})}
{/* Free-text fallback */}
{current.freeTextPlaceholder !== undefined && (
<div className="flex items-center gap-2.5 px-1 pt-1.5">
<span
className={cn(
"flex size-4 shrink-0 items-center justify-center rounded-full border-[1.5px] transition-colors",
isFreeText && freeTextValue
? "border-blue-500 bg-blue-500"
: "border-muted-foreground/40"
)}
>
{isFreeText && freeTextValue && (
<span className="size-1.5 rounded-full bg-white" />
)}
</span>
<input
type="text"
value={freeTextValue}
placeholder={current.freeTextPlaceholder}
onChange={(e) => setFreeText(e.target.value)}
onFocus={() => {
if (!isFreeText) setFreeText("");
}}
className="flex-1 bg-transparent text-xs text-muted-foreground placeholder:text-muted-foreground/50 outline-none focus:text-foreground"
/>
</div>
)}
</div>
{/* Footer */}
<div className="flex items-center gap-2 border-t px-4 py-3">
{/* Prev / step count / next */}
<div className="flex items-center gap-0.5">
<button
type="button"
onClick={() => setStep((s) => s - 1)}
disabled={step === 0}
aria-label="Previous question"
className="rounded p-0.5 text-muted-foreground transition-colors hover:text-foreground disabled:pointer-events-none disabled:opacity-30"
>
<ChevronLeft className="size-3.5" />
</button>
<span className="tabular-nums text-xs text-muted-foreground">
{step + 1}/{total}
</span>
<button
type="button"
onClick={() => setStep((s) => s + 1)}
disabled={step === total - 1}
aria-label="Next question"
className="rounded p-0.5 text-muted-foreground transition-colors hover:text-foreground disabled:pointer-events-none disabled:opacity-30"
>
<ChevronRight className="size-3.5" />
</button>
</div>
<div className="ml-auto flex items-center gap-2">
<button
type="button"
onClick={handleSkip}
className="rounded-full px-3.5 py-1.5 text-[11px] font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
Skip
</button>
<button
type="button"
onClick={handleContinue}
disabled={!selected || (isFreeText && !freeTextValue)}
className="rounded-full bg-foreground px-4 py-1.5 text-[11px] font-medium text-background transition-colors hover:bg-foreground/90 disabled:cursor-not-allowed disabled:opacity-40"
>
Continue
</button>
</div>
</div>
</motion.div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Human in the Loop Question
## Summary
A compact dialog that pauses an agent mid-task to collect a structured choice from the user — a set of radio options, an optional free-text fallback, and skip/continue controls. When more than one question is needed, a step counter opens a dropdown list so the user can see what's coming and jump between questions. Once all questions are answered the dialog resolves into a compact confirmation row and the agent proceeds.
## When to use
- The agent has reached a decision point where the output depends on a preference only the user can supply (a strategy choice, a scope decision, a threshold).
- The agent needs input before taking an action that is hard to reverse or would require significant rework if the wrong assumption is made.
- You want to front-load a short sequence of configuration questions at the start of a long autonomous run, so the agent can work uninterrupted afterward.
## When not to use
- For binary yes/no confirmation of a specific pending action — use Tool Approval, which is purpose-built for that pattern and carries the literal call details the user needs to see.
- When the agent can make a safe, recoverable assumption and ask forgiveness rather than permission — unnecessary interruptions erode trust in the agent.
- For long or complex surveys; cap the sequence at three to five questions. If more input is required, break the task into distinct phases with a planning step first.
- As a substitute for proper onboarding; don't use this pattern to collect user preferences that should have been gathered during setup.
## Anatomy
- **Question header**: the question text and an optional close/dismiss button.
- **Option list**: radio-style buttons; each shows a filled circle when selected. Label text shifts from muted to full contrast on selection.
- **Free-text fallback** (optional): an inline text input that acts as a write-in option; selecting it deselects the preset options.
- **Step indicator**: a `n/total` counter with a chevron that opens a step-list dropdown; answered steps show a filled checkmark, the current step is highlighted, future steps are dimmed.
- **Action row**: Skip (ghost) and Continue (primary blue); Continue is disabled until a choice is made.
- **Resolved state**: after the final question, the dialog transitions to a single confirmation row ("Got it — continuing the task.").
## Behavior
- Clicking Continue advances to the next question with a short fade-slide transition, or submits on the final step.
- Clicking Skip advances without recording an answer; the agent uses a default for that question.
- The step-list dropdown lets the user jump back to any question and change their answer before submitting.
- The free-text input captures focus and activates as the selected option; its radio indicator fills when the field has content.
- The dialog entry animates in (fade + slide up) so it feels like an insertion in the flow rather than a blocking overlay.
- After submit, the dialog transitions to the resolved state and is replaced after a short delay by the agent's next output.
## Guardrails
- The Continue button must remain disabled until the user has made a selection — either a preset option or a free-text entry with at least one character. Never auto-advance on selection without an explicit tap.
- Skip must never silently drop a question that the agent requires to proceed. If a question is mandatory, remove Skip and show a hint explaining why an answer is needed.
- Cap the sequence at five questions. Beyond that, the interruption feels like a form rather than a clarification and should be replaced by a dedicated settings or planning step.
- Do not show this pattern for decisions the agent can safely reverse or re-ask later. Reserve it for choices that meaningfully fork the agent's path or whose cost to undo is high.
- Never pre-select an option on the user's behalf. A pre-selected radio implies a default; if a default is acceptable, document it in the agent's behavior and skip the question entirely.
- The free-text fallback must not be the only option. It signals "none of the above" — if every question needs an open answer, a chat prompt is more appropriate than this pattern.
## Content guidelines
- Questions should be concrete decision points, not open-ended prompts ("Which model should handle reasoning tasks?" not "What do you prefer?").
- Option labels should be short noun phrases or brief imperatives (five words or fewer); avoid starting with a verb that duplicates the question's verb.
- The free-text placeholder should be the literal string "Something else..." — this signals write-in without over-explaining.
- Skip implies the agent has a sensible default; don't show it if skipping the question would leave the agent in an undefined state.
- Keep the entire sequence to three questions or fewer when possible; if the sequence must be longer, show a progress indicator.
## Accessibility
- Each option must be a real `<button>` element — not a styled `<div>` — so it's reachable and activatable by keyboard.
- The step-list dropdown uses `aria-haspopup` and `aria-expanded` on its trigger, and closes on Escape or an outside click.
- Continue's `disabled` state must be communicated beyond color alone — the button text remains legible and the label unchanged.
- The free-text input must have a visible label or an `aria-label`; the placeholder alone is not sufficient for accessibility.
- Avoid auto-advancing on radio selection without an explicit Continue click — screen readers and keyboard users need a stable target.
## Related patterns
- **Tool Approval** handles the narrower case of approving or denying a specific pending tool call; Human in the Loop handles open-ended preference collection.
- **Create Agent** is a broader wizard pattern for structured multi-field setup; use it when the questions involve text fields, toggles, and pickers rather than single-choice options.
Multi-Agent Trace
A tree of parallel sub-agent tasks, each with its own status and step list.
4 agents working
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { Check, ChevronDown, Loader2, X } from "lucide-react";
import { cn } from "@/lib/utils";
export interface AgentStep {
label: string;
meta?: string;
}
export type AgentStatus = "queued" | "running" | "done" | "error";
export interface Agent {
id: string;
name: string;
icon?: React.ComponentType<{ className?: string }>;
status: AgentStatus;
currentStep?: string;
elapsedSeconds?: number;
steps: AgentStep[];
subAgents?: Agent[];
}
export interface MultiAgentTraceProps {
agents: Agent[];
className?: string;
}
function countActive(agents: Agent[]): number {
return agents.reduce((n, a) => {
const self = a.status === "running" || a.status === "queued" ? 1 : 0;
return n + self + (a.subAgents ? countActive(a.subAgents) : 0);
}, 0);
}
function countFailed(agents: Agent[]): number {
return agents.reduce((n, a) => {
return n + (a.status === "error" ? 1 : 0) + (a.subAgents ? countFailed(a.subAgents) : 0);
}, 0);
}
function countTotal(agents: Agent[]): number {
return agents.reduce((n, a) => n + 1 + (a.subAgents ? countTotal(a.subAgents) : 0), 0);
}
export function MultiAgentTrace({ agents, className }: MultiAgentTraceProps) {
const active = countActive(agents);
const failed = countFailed(agents);
const total = countTotal(agents);
const allResolved = active === 0;
return (
<div className={cn("w-full overflow-hidden rounded-2xl border bg-card", className)}>
<div aria-live="polite" className="flex items-center gap-2 border-b px-4 py-3 text-xs font-medium">
{!allResolved ? (
<Loader2 className="size-3.5 animate-spin text-muted-foreground" aria-hidden />
) : failed > 0 ? (
<X className="size-3.5 text-destructive" aria-hidden />
) : (
<Check className="size-3.5 text-emerald-600 dark:text-emerald-400" aria-hidden />
)}
<span>
{!allResolved
? `${active} agent${active === 1 ? "" : "s"} working`
: `Done — ${total - failed}/${total} complete`}
</span>
</div>
<ul className="divide-y">
{agents.map((agent) => (
<AgentRow key={agent.id} agent={agent} />
))}
</ul>
</div>
);
}
function AgentRow({ agent, depth = 0 }: { agent: Agent; depth?: number }) {
const [open, setOpen] = React.useState(false);
const hasContent = agent.steps.length > 0 || (agent.subAgents?.length ?? 0) > 0;
return (
<li>
<button
type="button"
onClick={() => setOpen((v) => !v)}
aria-expanded={open}
disabled={!hasContent}
className="flex w-full items-center gap-3 px-4 py-3 text-left disabled:cursor-default"
style={{ paddingLeft: depth > 0 ? `${1 + depth * 1.5}rem` : undefined }}
>
<StatusIcon status={agent.status} icon={agent.icon} />
<div className="min-w-0 flex-1">
<p className="text-xs font-medium">{agent.name}</p>
{agent.currentStep && (
<p className="truncate text-[11px] text-muted-foreground">{agent.currentStep}</p>
)}
</div>
{typeof agent.elapsedSeconds === "number" && (
<span className="shrink-0 font-mono text-xs text-muted-foreground">
{agent.elapsedSeconds}s
</span>
)}
{hasContent && (
<ChevronDown
className={cn(
"size-4 shrink-0 text-muted-foreground transition-transform",
open && "rotate-180"
)}
/>
)}
</button>
<AnimatePresence initial={false}>
{open && hasContent && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2, ease: "easeInOut" }}
className="overflow-hidden"
>
{agent.steps.length > 0 && (
<ul
className="px-4 pb-3 pl-11"
style={{ paddingLeft: depth > 0 ? `${2.75 + depth * 1.5}rem` : undefined }}
>
{agent.steps.map((step, i) => (
<li key={i} className="flex gap-3">
<div className="flex flex-col items-center">
<span className="flex size-4 shrink-0 items-center justify-center rounded-full bg-muted">
<Check className="size-2.5 text-muted-foreground" />
</span>
{(i < agent.steps.length - 1 || (agent.subAgents?.length ?? 0) > 0) && (
<span className="my-1 w-px flex-1 bg-border" />
)}
</div>
<p className="pb-3 text-xs text-foreground/90">
{step.label}
{step.meta && (
<span className="ml-1.5 text-muted-foreground">{step.meta}</span>
)}
</p>
</li>
))}
</ul>
)}
{agent.subAgents && agent.subAgents.length > 0 && (
<ul className="border-t divide-y">
{agent.subAgents.map((sub) => (
<AgentRow key={sub.id} agent={sub} depth={depth + 1} />
))}
</ul>
)}
</motion.div>
)}
</AnimatePresence>
</li>
);
}
function StatusIcon({
status,
icon: Icon,
}: {
status: AgentStatus;
icon?: React.ComponentType<{ className?: string }>;
}) {
if (status === "running") {
return (
<span className="relative flex size-6 shrink-0 items-center justify-center rounded-full bg-muted">
{Icon ? (
<>
<Icon className="size-3.5 text-muted-foreground" aria-label="Running" />
<span className="absolute -bottom-0.5 -right-0.5 flex size-2.5 items-center justify-center rounded-full bg-card ring-1 ring-border">
<Loader2 className="size-1.5 animate-spin text-muted-foreground" />
</span>
</>
) : (
<Loader2 className="size-3.5 animate-spin text-muted-foreground" aria-label="Running" />
)}
</span>
);
}
if (status === "error") {
return (
<span className="flex size-6 shrink-0 items-center justify-center rounded-full bg-destructive/10 text-destructive">
{Icon ? <Icon className="size-3.5" aria-label="Error" /> : <X className="size-3.5" aria-label="Failed" />}
</span>
);
}
if (status === "done") {
return (
<span className="relative flex size-6 shrink-0 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
{Icon ? (
<>
<Icon className="size-3.5" aria-label="Done" />
<span className="absolute -bottom-0.5 -right-0.5 flex size-2.5 items-center justify-center rounded-full bg-card ring-1 ring-border">
<Check className="size-1.5 text-emerald-600 dark:text-emerald-400" />
</span>
</>
) : (
<Check className="size-3.5" aria-label="Done" />
)}
</span>
);
}
return (
<span className="flex size-6 shrink-0 items-center justify-center rounded-full bg-muted" aria-label="Queued">
{Icon ? (
<Icon className="size-3.5 text-muted-foreground/50" />
) : (
<span className="size-1.5 rounded-full bg-muted-foreground" />
)}
</span>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Multi-Agent Trace
## Summary
A tree/list view of an orchestrator's parallel sub-agent tasks — each with its own name, live status, current-step label, and collapsible step list — so the user can watch several agents work at once instead of inferring parallel progress from one linear trace. The multi-agent counterpart to Expandable Trace.
## When to use
- An orchestrating agent has dispatched more than one sub-agent or task concurrently, and the user benefits from seeing each one's independent progress and outcome.
- Any workflow where sub-agents can finish in a different order than they started, or one can fail while others keep going — a single linear trace can't represent that.
## When not to use
- For a single agent working through one sequence of steps — use Expandable Trace; wrapping one linear sequence in this pattern adds structure with nothing to show for it.
- When "sub-agents" are actually just sequential steps of one process dressed up as separate agents — if they run one after another, they read better as a single trace.
## Anatomy
- Root header: an aggregate status line ("3 agents working" while running, "Done — 3/3 complete" once finished) with a count.
- Per-agent row: a status icon (queued/running/done/error), the agent's name or role, a short current-step label, elapsed time, and an expand chevron.
- Expanded body: that agent's own step list, in the same step-row language as Expandable Trace.
## Behavior
- Each row updates independently — one agent completing, failing, or still running has no effect on any other row's state or label.
- The root header aggregates live: it reflects "N agents working" while any are active, and collapses to a static summary once all have resolved.
- Expanding one row never collapses another — several can be open simultaneously, since the agents themselves are independent.
- A failed sub-agent's row gets a distinct error tint and icon and stays visible rather than disappearing, so the user knows it needs attention.
## Content guidelines
- Agent names are short role labels ("Research agent", "Code agent"), not full descriptions of what they're doing — the current-step label carries that.
- Current-step labels follow the same present-tense, short-phrase convention as Thinking Loader and Tool Call Chip ("Reading docs", not "It is currently reading the documentation").
## Accessibility
- Each row's expand toggle exposes `aria-expanded`.
- Status changes are announced through a single `aria-live="polite"` region on the root header, not per row, so simultaneous updates from several agents don't spam assistive tech.
- Status is conveyed by icon and text together, never color alone, since red/green distinctions must survive a color-blind or grayscale viewing.
## Related patterns
- Expandable Trace is the single-agent, linear counterpart this pattern extends to parallel work.
- Tool Call Chip is what an individual step inside one agent's row typically looks like when that step is a specific tool call.
Thinking Loader
A loader with a shimmering label and a live elapsed-time counter.
Thinking0s
"use client";
import * as React from "react";
import { Brain } from "lucide-react";
import { AnimatePresence, motion } from "motion/react";
import { cn } from "@/lib/utils";
const DEFAULT_WORDS = [
"Thinking",
"Reasoning",
"Pondering",
"Analyzing",
"Considering",
"Working it out",
];
export interface ThinkingLoaderProps {
/** Words to cycle through as the label. Defaults to a set of generic synonyms. */
words?: string[];
/** How often the label changes, in ms. */
interval?: number;
className?: string;
}
export function ThinkingLoader({
words = DEFAULT_WORDS,
interval = 6000,
className,
}: ThinkingLoaderProps) {
const elapsed = useElapsedSeconds();
const word = useCyclingWord(words, interval);
return (
<div
className={cn("flex items-center gap-1 px-4 py-3 text-muted-foreground", className)}
>
<Brain className="size-3.5 shrink-0" aria-hidden />
<ShimmerWord word={word} />
<span className="ml-auto flex items-center font-mono text-xs tabular-nums">
<SlidingNumber value={elapsed} />s
</span>
</div>
);
}
function useCyclingWord(words: string[], interval: number) {
const [index, setIndex] = React.useState(0);
React.useEffect(() => {
if (words.length <= 1) return;
const id = window.setInterval(() => {
setIndex((i) => (i + 1) % words.length);
}, interval);
return () => window.clearInterval(id);
}, [words, interval]);
return words[index % words.length];
}
function useElapsedSeconds() {
const [elapsed, setElapsed] = React.useState("0");
React.useEffect(() => {
const start = Date.now();
const id = window.setInterval(() => {
setElapsed(Math.floor((Date.now() - start) / 1000).toString());
}, 1000);
return () => window.clearInterval(id);
}, []);
return elapsed;
}
function ShimmerWord({ word }: { word: string }) {
return (
<span className="relative inline-block h-[1.2em] overflow-hidden text-xs font-medium">
<AnimatePresence mode="popLayout" initial={false}>
<motion.span
key={word}
className="inline-block whitespace-nowrap bg-clip-text text-transparent"
style={{
backgroundImage:
"linear-gradient(90deg, var(--muted-foreground) 30%, var(--foreground) 50%, var(--muted-foreground) 70%)",
backgroundSize: "200% 100%",
}}
initial={{ y: 10, opacity: 0, backgroundPositionX: "150%" }}
animate={{ y: 0, opacity: 1, backgroundPositionX: "-50%" }}
exit={{ y: -10, opacity: 0 }}
transition={{
y: { duration: 0.08, ease: "easeOut" },
opacity: { duration: 0.08, ease: "easeOut" },
backgroundPositionX: { repeat: Infinity, repeatType: "loop", duration: 1.4, ease: "linear", repeatDelay: 0.8 },
}}
>
{word}
</motion.span>
</AnimatePresence>
</span>
);
}
/** Each digit slides up and out when it changes, and the new one slides up into place. */
function SlidingNumber({ value }: { value: string }) {
return (
<span className="inline-flex">
{value.split("").map((char, i) => (
<span key={i} className="relative inline-block h-[1.2em] w-[0.62em] overflow-hidden">
<AnimatePresence mode="popLayout" initial={false}>
<motion.span
key={`${i}-${char}`}
initial={{ y: 10, opacity: 0 }}
animate={{ y: 0, opacity: 1 }}
exit={{ y: -10, opacity: 0 }}
transition={{ duration: 0.25, ease: "easeOut" }}
className="absolute inset-0 flex items-center justify-center"
>
{char}
</motion.span>
</AnimatePresence>
</span>
))}
</span>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Thinking Loader
## Summary
An inline status indicator shown while an agent is working on a response: a small looping glyph, a shimmering verb label, and a live elapsed-time counter. It tells the user the system is alive and roughly how long it has been going, without claiming a specific progress percentage it doesn't have.
## When to use
- Any moment an agent or background process is working and the duration is unknown or variable (LLM generation, tool calls, search, a long-running job).
- As the "in progress" half of a working → done sequence (see Related).
## When not to use
- When you actually know a determinate progress percentage — use a progress bar instead, it's more honest and more useful.
- As a permanent decoration left running after the work is actually done. The instant work finishes, replace this component with a completed-state summary; do not just freeze or hide it in place.
- More than one active at a time in the same conversation/view. One "the system is working" signal per turn.
## Anatomy
- Brain icon: a plain, solid glyph — it doesn't shimmer, so it stays legible as a fixed anchor next to the moving label.
- Shimmering label: a present-participle verb or short phrase describing the current activity, cycling through a small set of synonyms ("Thinking", "Reasoning", "Pondering", ...) on a timer.
- Elapsed-time counter: whole seconds, counting up from 0s.
## Behavior
- Starts counting the instant work begins.
- The label cycles to the next word in its list every 6 seconds, fading/sliding out the old word and in the new one — the shimmer (a single sweep, pause, repeat, not a relentless loop) communicates "still working" even between word changes.
- If real sub-step information is available ("Thinking" → "Searching" → "Writing"), drive the label from that instead of the generic cycle.
- The counter's changed digit animates in place (a short roll/slide) rather than the whole number re-rendering, so it doesn't read as flicker.
- On completion, replace the whole component with a result — for an agent trace, that's typically the collapsed header of an Expandable Trace ("Thought for 4 seconds").
## Content guidelines
- Each word is one or two words, present-participle or short verb phrase, no punctuation.
- Keep it truthful: don't cycle through "Searching" unless a search is actually happening.
## Accessibility
- Wrap in an `aria-live="polite"` region so screen readers announce label changes without interrupting other content.
- Don't rely on the animated counter alone to signal "still working" for assistive tech — the live-region label carries that meaning.
- Respect `prefers-reduced-motion`: keep the counter (it's informational) but reduce or remove the shimmer motion.
## Related patterns
- Expandable Trace is the "done" counterpart — replace this component with that one the moment work completes.
Expandable Trace
A collapsible "Thought for Xs" summary that expands into a step-by-step trace.
Reading the component's UX doc
Comparing it against similar patterns
Checking accessibility noteskeyboard + reduced motion
Scaffolding the component
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { Check, ChevronDown, Sparkles } from "lucide-react";
import { cn } from "@/lib/utils";
export interface TraceStep {
label: string;
meta?: string;
}
export interface ExpandableTraceProps {
durationSeconds?: number;
steps: TraceStep[];
defaultOpen?: boolean;
className?: string;
}
export function ExpandableTrace({
durationSeconds = 4,
steps,
defaultOpen = false,
className,
}: ExpandableTraceProps) {
const [open, setOpen] = React.useState(defaultOpen);
return (
<div className={className}>
<button
type="button"
onClick={() => setOpen((v) => !v)}
aria-expanded={open}
className="flex w-full items-center gap-2 px-4 py-3 text-left text-xs font-medium"
>
<Sparkles className="size-4 text-muted-foreground" />
<span>Thought for {durationSeconds} seconds</span>
<ChevronDown
className={cn(
"ml-auto size-4 text-muted-foreground transition-transform duration-200",
open && "rotate-180"
)}
/>
</button>
<AnimatePresence initial={false}>
{open && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2, ease: "easeInOut" }}
className="overflow-hidden"
>
<ul className="px-4 pb-4">
{steps.map((step, i) => (
<li key={i} className="flex gap-3">
<div className="flex flex-col items-center">
<span className="flex size-4 shrink-0 items-center justify-center rounded-full bg-muted">
<Check className="size-2.5 text-muted-foreground" />
</span>
{i < steps.length - 1 && <span className="my-1 w-px flex-1 bg-border" />}
</div>
<p className="pb-3 text-xs text-foreground/90">
{step.label}
{step.meta && (
<span className="ml-1.5 text-muted-foreground">{step.meta}</span>
)}
</p>
</li>
))}
</ul>
</motion.div>
)}
</AnimatePresence>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Expandable Trace
## Summary
A collapsed-by-default summary line ("Thought for N seconds") that expands into a checklist of the discrete steps an agent took to produce its answer. It gives curious users a way to audit the reasoning without forcing everyone to read it by default.
## When to use
- Right after an agent finishes a multi-step task (tool calls, reasoning, search, edits) and you want to offer transparency without cluttering the default view.
- When the steps have a natural, ordered sequence with a clear notion of "done" per step.
## When not to use
- For a single atomic action with no real sub-steps — there's nothing meaningful to expand into; just state the result.
- As a substitute for real error handling. If a step failed, show that explicitly as a distinct state on that step (not by silently omitting it).
- Auto-expanded by default in a dense feed. Default collapsed keeps the primary answer scannable; only auto-expand when the user asked to see reasoning, or in a dedicated debugging surface.
## Anatomy
- Header button: icon + "Thought for N seconds" + chevron. The entire header is the toggle target, not just the chevron.
- Collapsible body: a vertical list of steps, each with a completion mark, a short label, and optional trailing metadata (e.g. "6 sources").
- A connecting line between steps so they read as one continuous sequence, not disconnected items.
## Behavior
- Collapsed by default.
- Expand/collapse animates height smoothly rather than snapping instantly.
- The step list is a static historical record once rendered — it does not keep updating live. Use the Thinking Loader for the in-progress version of this information.
- The duration shown in the header is fixed once the run is complete; it does not keep counting like the Thinking Loader's timer does.
## Content guidelines
- Step labels are short, neutral action phrases ("Reading the uploaded document"), not first-person narration ("I read the uploaded document").
- Trailing metadata should be a single scannable fact, not another full sentence.
## Accessibility
- The header button needs `aria-expanded` reflecting current state.
- The whole component must be operable by keyboard (Enter/Space on the header toggles it).
- Never hide information the user needs to trust or act on the primary answer exclusively inside the collapsed trace — the answer must stand on its own without expanding this.
## Related patterns
- Thinking Loader is the "in progress" counterpart — this component is what it becomes once work finishes.
Streaming Text
A streamed answer with inline sources, actions, and follow-ups.
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { Check, Copy, Globe, ThumbsDown, ThumbsUp } from "lucide-react";
export type StreamSegment = { type: "text"; content: string } | { type: "source"; label: string };
export interface StreamingTextProps {
segments: StreamSegment[];
/** Milliseconds between each revealed character. */
speed?: number;
followUps?: string[];
onComplete?: () => void;
className?: string;
}
type Token = { type: "char"; value: string } | { type: "source"; value: string };
function tokenize(segments: StreamSegment[]): Token[] {
const tokens: Token[] = [];
for (const segment of segments) {
if (segment.type === "text") {
for (const char of segment.content) tokens.push({ type: "char", value: char });
} else {
tokens.push({ type: "source", value: segment.label });
}
}
return tokens;
}
export function StreamingText({ segments, speed = 18, followUps, onComplete, className }: StreamingTextProps) {
const tokens = React.useMemo(() => tokenize(segments), [segments]);
const [count, setCount] = React.useState(0);
const done = count >= tokens.length;
React.useEffect(() => {
if (count >= tokens.length) return;
const id = window.setTimeout(() => setCount((c) => c + 1), speed);
return () => window.clearTimeout(id);
}, [count, tokens.length, speed]);
React.useEffect(() => {
if (done) onComplete?.();
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [done]);
const nodes: React.ReactNode[] = [];
let buffer = "";
let key = 0;
for (let i = 0; i < count; i++) {
const token = tokens[i];
if (token.type === "char") {
buffer += token.value;
} else {
if (buffer) {
nodes.push(<React.Fragment key={key++}>{buffer}</React.Fragment>);
buffer = "";
}
nodes.push(<SourceChip key={key++} label={token.value} />);
}
}
if (buffer) nodes.push(<React.Fragment key={key++}>{buffer}</React.Fragment>);
const plainText = segments.map((s) => (s.type === "text" ? s.content : "")).join("");
return (
<div className={className}>
<p className="text-sm leading-relaxed text-foreground/90">
{nodes}
{!done && <BlinkingCursor />}
</p>
{done && (
<motion.div
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.2 }}
className="mt-3 flex flex-wrap items-center gap-1.5"
>
<ActionButtons text={plainText} />
{followUps?.length ? (
<>
<span className="mx-1 h-4 w-px bg-border" />
{followUps.map((label) => (
<button
key={label}
type="button"
className="rounded-full border px-3 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground"
>
{label}
</button>
))}
</>
) : null}
</motion.div>
)}
</div>
);
}
function BlinkingCursor() {
return (
<motion.span
aria-hidden
className="ml-0.5 inline-block h-3.5 w-[2px] translate-y-[2px] bg-foreground"
animate={{ opacity: [1, 1, 0, 0] }}
transition={{ duration: 1, repeat: Infinity, times: [0, 0.5, 0.5, 1], ease: "linear" }}
/>
);
}
function SourceChip({ label }: { label: string }) {
return (
<span className="mx-1 inline-flex -translate-y-px items-center gap-1 rounded-full border bg-muted px-2 py-0.5 align-middle text-xs">
<span className="flex size-3.5 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
<Globe className="size-2.5" />
</span>
<span className="font-mono text-muted-foreground">{label}</span>
</span>
);
}
function ActionButtons({ text }: { text: string }) {
const [copied, setCopied] = React.useState(false);
async function handleCopy() {
await navigator.clipboard.writeText(text);
setCopied(true);
window.setTimeout(() => setCopied(false), 1500);
}
return (
<div className="flex items-center gap-0.5 text-muted-foreground">
<button
type="button"
onClick={handleCopy}
aria-label="Copy"
className="rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground"
>
{copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
</button>
<button
type="button"
aria-label="Good response"
className="rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground"
>
<ThumbsUp className="size-3.5" />
</button>
<button
type="button"
aria-label="Bad response"
className="rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground"
>
<ThumbsDown className="size-3.5" />
</button>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Streaming Text
## Summary
An answer that reveals itself progressively, as if it's being generated live, with inline source citations that appear at their exact position in the text — followed by quick actions and follow-up suggestions once the stream finishes.
## When to use
- Displaying an LLM-generated answer as it's actually produced (or a scripted approximation of that for a demo).
- Answers that cite specific sources inline, where the citation should feel attached to the exact claim it supports rather than listed separately at the end.
## When not to use
- Content the user already has in full, such as re-rendering a past message when a conversation reloads — show it fully formed, don't replay the reveal animation.
- Very long documents (multiple paragraphs+), where a full character-by-character reveal just delays reading. Consider revealing by paragraph/chunk instead.
- Attaching follow-up suggestion chips to content that isn't actually actionable — don't add them out of habit.
## Anatomy
- Streamed body text.
- Inline source chip(s): a small pill with an icon and a domain/source name, appearing inline mid-sentence.
- A cursor at the current write position, visible only while streaming.
- Post-stream action row: copy, thumbs up/down.
- Post-stream follow-up suggestion chips.
## Behavior
- Text reveals at a constant, fast pace — slow enough to read as "live", fast enough that it never feels like a gimmick or an artificial delay.
- A source chip appears as a whole unit at its position; it does not itself type in character by character.
- The cursor disappears the instant streaming completes.
- The action row and follow-up chips appear only after the stream finishes, never during — so they don't compete for attention while the user is still reading.
- Follow-up chips are optional next steps the user can click, not required actions.
## Content guidelines
- Citations are short (a domain or short source name), not a full URL.
- Follow-up suggestions are phrased as something the user would say next, in their voice ("Show trend chart"), not the agent's voice ("I can show a trend chart").
## Accessibility
- The streaming region should be an `aria-live="polite"` region; announcing every character is disruptive, so throttle or announce only on completion.
- Respect `prefers-reduced-motion` by rendering the full text immediately instead of animating the character reveal.
- The cursor is decorative — mark it `aria-hidden`.
## Related patterns
- Often follows a Thinking Loader / Expandable Trace pair: loader while working, trace for the audit trail, this component for the actual answer.
Prompt Bar
A composer with @ sources, / commands, a model picker, and dictation.
Write a message...
Try typing @ to reference a source or / for commands.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { ChevronDown, ChevronRight, Folder, Link2, Mic, Paperclip, Plus } from "lucide-react";
import { cn } from "@/lib/utils";
import { StopGenerationButton, type GenerationState } from "../../buttons/stop-generation-button/component";
import { Attachment, AttachmentChip } from "../../uploads/attachment-chip/component";
export type PromptBarVariant = "rounded" | "pill";
export interface PromptBarItem {
id: string;
label: string;
description?: string;
}
export interface PromptBarProps {
variant?: PromptBarVariant;
placeholder?: string;
sources?: PromptBarItem[];
commands?: PromptBarItem[];
models?: PromptBarItem[];
onSubmit?: (value: string) => void;
className?: string;
}
const defaultSources: PromptBarItem[] = [
{ id: "docs", label: "Docs" },
{ id: "codebase", label: "Codebase" },
{ id: "web", label: "Web" },
{ id: "figma", label: "Figma" },
];
const defaultCommands: PromptBarItem[] = [
{ id: "summarize", label: "/summarize", description: "Summarize the thread" },
{ id: "draft", label: "/draft", description: "Draft a reply" },
{ id: "translate", label: "/translate", description: "Translate this message" },
];
const defaultModels: PromptBarItem[] = [
{ id: "model-5", label: "Model 5" },
{ id: "model-5-mini", label: "Model 5 mini" },
{ id: "model-4", label: "Model 4" },
];
interface Trigger {
type: "source" | "command";
query: string;
start: number;
}
function getActiveTrigger(text: string): Trigger | null {
const match = text.match(/(?:^|\s)([@/])(\S*)$/);
if (!match) return null;
const [full, symbol, query] = match;
return {
type: symbol === "@" ? "source" : "command",
query: query.toLowerCase(),
start: text.length - full.length + full.indexOf(symbol),
};
}
const CHIP_CLASS =
"inline-block rounded-sm bg-primary/10 text-primary px-1.5 py-1 text-xs font-medium leading-none select-none align-middle mx-px mb-1 mr-1";
export function PromptBar({
variant = "rounded",
placeholder = "Write a message...",
sources = defaultSources,
commands = defaultCommands,
models = defaultModels,
onSubmit,
className,
}: PromptBarProps) {
const [model, setModel] = React.useState(models[0]?.label ?? "");
const [modelOpen, setModelOpen] = React.useState(false);
const [dictating, setDictating] = React.useState(false);
const [activeIndex, setActiveIndex] = React.useState(0);
const [suppressed, setSuppressed] = React.useState(false);
const [generationState, setGenerationState] = React.useState<GenerationState>("idle");
const [textBeforeCursor, setTextBeforeCursor] = React.useState("");
const [hasContent, setHasContent] = React.useState(false);
const [attachments, setAttachments] = React.useState<Attachment[]>([]);
const [attachMenuOpen, setAttachMenuOpen] = React.useState(false);
const editorRef = React.useRef<HTMLDivElement>(null);
const fileInputRef = React.useRef<HTMLInputElement>(null);
const modelMenuRef = useClickOutside<HTMLDivElement>(() => setModelOpen(false));
const attachMenuRef = useClickOutside<HTMLDivElement>(() => setAttachMenuOpen(false));
const isDisabled = generationState === "generating";
function addAttachments(files: FileList | null) {
if (!files) return;
const next: Attachment[] = Array.from(files).map((f) => ({
id: `${f.name}-${Date.now()}-${Math.random()}`,
name: f.name,
size: f.size,
progress: 100,
status: "done" as const,
previewUrl: f.type.startsWith("image/") ? URL.createObjectURL(f) : undefined,
}));
setAttachments((prev) => [...prev, ...next]);
}
function removeAttachment(id: string) {
setAttachments((prev) => {
const att = prev.find((a) => a.id === id);
if (att?.previewUrl) URL.revokeObjectURL(att.previewUrl);
return prev.filter((a) => a.id !== id);
});
}
const trigger = getActiveTrigger(textBeforeCursor);
const suggestions = trigger
? (trigger.type === "source" ? sources : commands).filter((item) =>
item.label
.toLowerCase()
.replace(/^\//, "")
.includes(trigger.query.replace(/^\//, ""))
)
: [];
const showSuggestions = Boolean(trigger) && !suppressed && suggestions.length > 0;
const canSend = hasContent || attachments.length > 0;
const triggerKey = trigger ? `${trigger.type}:${trigger.start}` : null;
const prevTriggerKeyRef = React.useRef(triggerKey);
if (triggerKey !== prevTriggerKeyRef.current) {
prevTriggerKeyRef.current = triggerKey;
if (activeIndex !== 0) setActiveIndex(0);
if (suppressed) setSuppressed(false);
}
React.useEffect(() => {
if (generationState !== "generating") return;
const id = window.setTimeout(() => setGenerationState("idle"), 2600);
return () => window.clearTimeout(id);
}, [generationState]);
function getTextBeforeCursor(): string {
const sel = window.getSelection();
const el = editorRef.current;
if (!sel?.rangeCount || !el) return "";
const cursorRange = sel.getRangeAt(0);
const range = document.createRange();
range.setStart(el, 0);
range.setEnd(cursorRange.startContainer, cursorRange.startOffset);
const frag = range.cloneContents();
let text = "";
frag.childNodes.forEach((node) => {
if (node.nodeType === Node.TEXT_NODE) {
text += node.textContent ?? "";
} else if (node instanceof HTMLElement && node.dataset.chip === "true") {
text += `@${node.dataset.label}`;
}
});
return text;
}
function serializeEditor(): string {
const el = editorRef.current;
if (!el) return "";
let text = "";
el.childNodes.forEach((node) => {
if (node.nodeType === Node.TEXT_NODE) {
text += node.textContent ?? "";
} else if (node instanceof HTMLElement && node.dataset.chip === "true") {
text += `@${node.dataset.label}`;
}
});
return text.trim();
}
function updateEditorState() {
const el = editorRef.current;
if (!el) return;
const hasText = (el.textContent ?? "").trim().length > 0;
const hasChips = el.querySelector("[data-chip]") !== null;
setHasContent(hasText || hasChips);
setTextBeforeCursor(getTextBeforeCursor());
}
function handlePaste(e: React.ClipboardEvent<HTMLDivElement>) {
e.preventDefault();
const text = e.clipboardData.getData("text/plain");
document.execCommand("insertText", false, text);
}
function insertChip(item: PromptBarItem) {
const sel = window.getSelection();
const el = editorRef.current;
if (!sel?.rangeCount || !el) return;
const range = sel.getRangeAt(0);
const container = range.startContainer;
const offset = range.startOffset;
// Delete the @query text from the current text node
if (container.nodeType === Node.TEXT_NODE) {
const text = container.textContent ?? "";
const textBefore = text.slice(0, offset);
const atIndex = textBefore.lastIndexOf("@");
if (atIndex !== -1) {
container.textContent = text.slice(0, atIndex) + text.slice(offset);
const newRange = document.createRange();
newRange.setStart(container, atIndex);
newRange.collapse(true);
sel.removeAllRanges();
sel.addRange(newRange);
}
}
const chip = document.createElement("span");
chip.contentEditable = "false";
chip.dataset.chip = "true";
chip.dataset.label = item.label;
chip.textContent = `@${item.label}`;
chip.className = CHIP_CLASS;
const insertRange = sel.getRangeAt(0);
insertRange.insertNode(chip);
// Place cursor in a text node right after the chip
const space = document.createTextNode(" ");
const afterRange = document.createRange();
afterRange.setStartAfter(chip);
afterRange.insertNode(space);
afterRange.setStartAfter(space);
afterRange.collapse(true);
sel.removeAllRanges();
sel.addRange(afterRange);
updateEditorState();
el.focus();
}
function handleSubmit() {
const content = serializeEditor();
if ((!content && attachments.length === 0) || isDisabled) return;
onSubmit?.(content);
if (editorRef.current) editorRef.current.innerHTML = "";
setHasContent(false);
setTextBeforeCursor("");
attachments.forEach((a) => { if (a.previewUrl) URL.revokeObjectURL(a.previewUrl); });
setAttachments([]);
setGenerationState("generating");
}
function handleKeyDown(e: React.KeyboardEvent<HTMLDivElement>) {
if (showSuggestions) {
if (e.key === "ArrowDown") {
e.preventDefault();
setActiveIndex((i) => (i + 1) % suggestions.length);
return;
}
if (e.key === "ArrowUp") {
e.preventDefault();
setActiveIndex((i) => (i - 1 + suggestions.length) % suggestions.length);
return;
}
if (e.key === "Enter" || e.key === "Tab") {
e.preventDefault();
insertChip(suggestions[activeIndex]);
return;
}
if (e.key === "Escape") {
e.preventDefault();
setSuppressed(true);
return;
}
}
if (e.key === "Enter" && !e.shiftKey) {
e.preventDefault();
handleSubmit();
}
}
return (
<div className={cn("relative w-full", className)}>
<AnimatePresence>
{showSuggestions && (
<motion.div
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: 4 }}
transition={{ duration: 0.12 }}
className="absolute bottom-full left-0 z-10 mb-2 w-full max-w-xs overflow-hidden rounded-xl border bg-popover shadow-md"
>
{suggestions.map((item, i) => (
<button
key={item.id}
type="button"
onMouseDown={(e) => {
e.preventDefault();
insertChip(item);
}}
className={cn(
"flex w-full flex-col items-start gap-0.5 px-3 py-2 text-left text-sm",
i === activeIndex ? "bg-accent text-accent-foreground" : "hover:bg-accent/60"
)}
>
<span className="font-medium">
{trigger?.type === "source" ? `@${item.label}` : item.label}
</span>
{item.description && (
<span className="text-xs text-muted-foreground">{item.description}</span>
)}
</button>
))}
</motion.div>
)}
</AnimatePresence>
<div
className={cn(
"flex flex-wrap items-end gap-1.5 border bg-card p-2.5 shadow-sm sm:flex-nowrap sm:gap-1 sm:p-2",
variant === "pill" ? "rounded-3xl sm:rounded-full" : "rounded-2xl"
)}
>
<input
ref={fileInputRef}
type="file"
multiple
className="hidden"
onChange={(e) => addAttachments(e.target.files)}
onClick={(e) => { (e.target as HTMLInputElement).value = ""; }}
/>
<div ref={attachMenuRef} className="relative order-2 shrink-0 sm:order-none">
<button
type="button"
onClick={() => setAttachMenuOpen((v) => !v)}
className="flex size-8 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
aria-label="Add attachment"
>
<Plus className="size-4" />
</button>
<AnimatePresence>
{attachMenuOpen && (
<motion.div
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: 4 }}
transition={{ duration: 0.12 }}
className="absolute bottom-full left-0 z-20 mb-1.5 w-52 overflow-hidden rounded-xl border bg-popover shadow-md"
>
<button
type="button"
onMouseDown={(e) => { e.preventDefault(); fileInputRef.current?.click(); setAttachMenuOpen(false); }}
className="flex w-full items-center gap-2.5 px-3 py-2.5 text-sm hover:bg-accent"
>
<Paperclip className="size-4 text-muted-foreground" />
Upload files or images
</button>
<button type="button" className="flex w-full items-center gap-2.5 px-3 py-2.5 text-sm text-muted-foreground hover:bg-accent hover:text-foreground">
<Link2 className="size-4" />
Connectors
<ChevronRight className="ml-auto size-3.5" />
</button>
<button type="button" className="flex w-full items-center gap-2.5 px-3 py-2.5 text-sm text-muted-foreground hover:bg-accent hover:text-foreground">
<Folder className="size-4" />
Projects
<ChevronRight className="ml-auto size-3.5" />
</button>
</motion.div>
)}
</AnimatePresence>
</div>
<div className="relative order-1 w-full min-w-0 basis-full sm:order-none sm:w-auto sm:flex-1">
<AnimatePresence initial={false}>
{attachments.length > 0 && (
<motion.div
initial={{ opacity: 0, height: 0 }}
animate={{ opacity: 1, height: "auto" }}
exit={{ opacity: 0, height: 0 }}
transition={{ duration: 0.15 }}
className="overflow-hidden"
>
<ul className="flex gap-2 overflow-x-auto pt-2 pr-2 pb-2">
{attachments.map((att) => (
<AttachmentChip key={att.id} attachment={att} onRemove={removeAttachment} />
))}
</ul>
</motion.div>
)}
</AnimatePresence>
<div className="relative">
<div
ref={editorRef}
contentEditable={!isDisabled}
suppressContentEditableWarning
role="textbox"
aria-multiline="true"
aria-label={placeholder}
onInput={updateEditorState}
onKeyDown={handleKeyDown}
onPaste={handlePaste}
className={cn(
"max-h-40 min-h-[1.5rem] overflow-x-hidden overflow-y-auto break-words bg-transparent py-1.5 text-sm outline-none leading-normal",
isDisabled && "pointer-events-none text-muted-foreground"
)}
/>
{!hasContent && (
<span className="pointer-events-none absolute left-0 top-1.5 text-sm text-muted-foreground">
{placeholder}
</span>
)}
</div>
</div>
<div ref={modelMenuRef} className="relative order-2 ml-auto shrink-0 sm:order-none sm:ml-0">
<button
type="button"
onClick={() => setModelOpen((v) => !v)}
className="flex items-center gap-1 rounded-full px-2 py-1.5 text-sm font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
{model}
<ChevronDown className={cn("size-3.5 transition-transform", modelOpen && "rotate-180")} />
</button>
<AnimatePresence>
{modelOpen && (
<motion.div
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: 4 }}
transition={{ duration: 0.12 }}
className="absolute bottom-full right-0 z-10 mb-2 w-40 overflow-hidden rounded-xl border bg-popover shadow-md"
>
{models.map((m) => (
<button
key={m.id}
type="button"
onClick={() => {
setModel(m.label);
setModelOpen(false);
}}
className={cn(
"block w-full px-3 py-2 text-left text-sm hover:bg-accent",
m.label === model && "font-medium"
)}
>
{m.label}
</button>
))}
</motion.div>
)}
</AnimatePresence>
</div>
<button
type="button"
onClick={() => setDictating((v) => !v)}
aria-pressed={dictating}
aria-label="Toggle dictation"
className={cn(
"relative order-2 flex size-8 shrink-0 items-center justify-center rounded-full transition-colors sm:order-none",
dictating ? "text-destructive" : "text-muted-foreground hover:bg-accent hover:text-foreground"
)}
>
{dictating && (
<motion.span
className="absolute inset-0 rounded-full bg-destructive/20"
animate={{ scale: [1, 1.4], opacity: [0, 0.6, 0] }}
transition={{ duration: 1.2, repeat: Infinity, ease: "easeOut" }}
/>
)}
<Mic className="size-4" />
</button>
<StopGenerationButton
state={generationState}
disabled={!canSend}
onSubmit={handleSubmit}
onStop={() => setGenerationState("idle")}
className="order-2 sm:order-none"
/>
</div>
</div>
);
}
function useClickOutside<T extends HTMLElement>(onOutside: () => void) {
const ref = React.useRef<T>(null);
React.useEffect(() => {
function handle(e: MouseEvent) {
if (ref.current && !ref.current.contains(e.target as Node)) onOutside();
}
document.addEventListener("mousedown", handle);
return () => document.removeEventListener("mousedown", handle);
}, [onOutside]);
return ref;
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Prompt Bar
## Summary
The primary text composer for talking to an agent: a single input that also supports inline `@`-mentions of context/sources, `/`-slash commands, a model picker, and voice dictation, all without leaving the text field.
## When to use
- The main input for a chat/agent interface where users need to both type free text and quickly reference structured things (files, people, data sources) or trigger canned actions inline.
## When not to use
- A simple, single-purpose text field with no mentions, commands, or model choice — use a plain input. Don't add this pattern's complexity where none of it is needed.
- A model picker when the product only ever has one model — remove unused affordances rather than showing a picker with a single option.
## Anatomy
- Leading add/attach action.
- Auto-growing text field.
- Inline `@`/`/` autocomplete popover.
- Trailing model picker.
- Dictation toggle.
- Send button.
## Behavior
- `@` opens a source/context picker filtered as the user keeps typing; `/` opens a command picker the same way.
- Arrow keys move the highlighted suggestion; Enter or Tab accepts it; Escape dismisses the popover without clearing what was typed.
- Plain Enter (no popover open) submits the message; Shift+Enter inserts a newline.
- The send button is visually inactive until there is non-whitespace content.
- The model picker and dictation toggle are independent of the text content and can be changed at any time, including mid-draft.
- Dictation shows an unambiguous "listening" state (e.g. a pulsing indicator) so it's never unclear whether the mic is live.
## Content guidelines
- Mention and command labels are short, recognizable nouns/verbs.
- Command descriptions (shown secondary to the label) state what the command does in a few words, not a full sentence.
## Accessibility
- The autocomplete popover must be fully operable from the keyboard — it's the primary interaction path, not a mouse-only nicety — and should communicate the current highlighted item to assistive tech.
- The model picker and dictation toggle need explicit `aria-label`s since they're icon-only or short-label controls.
- Respect `prefers-reduced-motion` for the dictation pulse; fall back to a solid color change instead of an animated ring.
## Related patterns
- Typically pairs with Thinking Loader / Expandable Trace (the agent's working/done states) and Streaming Text (the reply) to form a full turn of conversation.
Diff Summary Card
A collapsed summary of a batch of file edits, with undo and an overflow list.
Edited 11 files
now
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { ChevronDown, ChevronRight, Code2, Copy, Pin, Volume2 } from "lucide-react";
import { cn } from "@/lib/utils";
export interface DiffFile {
id: string;
name: string;
additions: number;
deletions: number;
}
export interface DiffSummaryCardProps {
files: DiffFile[];
visibleCount?: number;
timestamp?: string;
onUndo?: () => void;
onViewChanges?: () => void;
className?: string;
}
export function DiffSummaryCard({
files,
visibleCount = 5,
timestamp = "now",
onUndo,
onViewChanges,
className,
}: DiffSummaryCardProps) {
const [expanded, setExpanded] = React.useState(false);
const primary = files.slice(0, visibleCount);
const rest = files.slice(visibleCount);
return (
<div className={cn("w-full overflow-hidden rounded-2xl border bg-card", className)}>
<div className="flex items-center justify-between gap-3 border-b px-4 py-3">
<p className="text-xs font-medium">Edited {files.length} files</p>
<div className="flex items-center gap-2">
<button
type="button"
onClick={onUndo}
className="text-xs text-muted-foreground transition-colors hover:text-foreground"
>
Undo
</button>
<button
type="button"
onClick={onViewChanges}
className="rounded-full border px-3 py-1 text-xs font-medium transition-colors hover:bg-accent"
>
View changes
</button>
</div>
</div>
<ul className="divide-y">
{primary.map((file) => (
<FileRow key={file.id} file={file} />
))}
</ul>
<AnimatePresence initial={false}>
{expanded && rest.length > 0 && (
<motion.ul
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2, ease: "easeInOut" }}
className="divide-y overflow-hidden border-t"
>
{rest.map((file) => (
<FileRow key={file.id} file={file} />
))}
</motion.ul>
)}
</AnimatePresence>
{rest.length > 0 && (
<button
type="button"
onClick={() => setExpanded((v) => !v)}
className="flex w-full items-center gap-1.5 border-t px-4 py-2.5 text-sm text-muted-foreground transition-colors hover:text-foreground"
>
{expanded ? "Show less" : `Show ${rest.length} more`}
<ChevronDown className={cn("size-4 transition-transform", expanded && "rotate-180")} />
</button>
)}
<div className="flex items-center justify-between border-t px-4 py-2.5">
<div className="flex items-center gap-1 text-muted-foreground">
<button
type="button"
aria-label="Copy"
className="rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground"
>
<Copy className="size-3.5" />
</button>
<button
type="button"
aria-label="Pin"
className="rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground"
>
<Pin className="size-3.5" />
</button>
<button
type="button"
aria-label="Read aloud"
className="rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground"
>
<Volume2 className="size-3.5" />
</button>
</div>
<span className="text-xs text-muted-foreground">{timestamp}</span>
</div>
</div>
);
}
function FileRow({ file }: { file: DiffFile }) {
return (
<li>
<button
type="button"
className="flex w-full items-center gap-2.5 px-4 py-2.5 text-left transition-colors hover:bg-accent/50"
>
<Code2 className="size-4 shrink-0 text-muted-foreground" />
<span className="flex-1 truncate text-xs">{file.name}</span>
<span className="shrink-0 font-mono text-xs">
<span className="text-emerald-600 dark:text-emerald-400">+{file.additions}</span>
<span className="ml-1.5 text-red-600 dark:text-red-400">-{file.deletions}</span>
</span>
<ChevronRight className="size-4 shrink-0 text-muted-foreground" />
</button>
</li>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Diff Summary Card
## Summary
A collapsed summary of a batch of file edits an agent just made: a count, an undo action, a "view changes" action, a per-file list of names with add/delete line counts, and an overflow expander for large batches. It lets the user trust that changes happened and skim their scope without reading every diff.
## When to use
- Immediately after an agent finishes a multi-file edit (a coding assistant, a batch content update, a config migration).
- When individual files have a clear, quantifiable diff (lines added/removed) worth surfacing at a glance.
## When not to use
- For a single-file edit — a one-line inline confirmation is enough; a whole card is overkill for one file.
- As the only way to inspect what changed. "View changes" must lead somewhere real (a diff viewer); this card is a summary, not a substitute for the actual diff.
- For edits that can't be undone. Only offer "Undo" when it actually reverts the change — a decorative Undo that doesn't work erodes trust fast.
## Anatomy
- Header: file count ("Edited N files"), an Undo action, a View changes action.
- File list: one row per file — an icon, the file name (truncated, not wrapped), additions/deletions counts, and an affordance that the row is clickable.
- Overflow control: "Show N more" beneath the first handful of rows, expanding in place.
- Footer: secondary actions (e.g. copy, pin, read aloud) and a timestamp.
## Behavior
- Show only the first handful of files (5–8) by default; collapse the rest behind "Show N more" so the card doesn't dominate the screen for large batches.
- Expanding the overflow list animates height smoothly rather than snapping; it does not replace or reflow the already-visible rows.
- Additions and deletions are always shown together (+N in one color, -N in another) so scanning the list gives an at-a-glance sense of which files grew, shrank, or were rewritten.
- Undo should act on the whole batch, not per file — this card represents one atomic change.
- Clicking a file row should open that file's specific diff, not the whole batch's.
## Content guidelines
- File names show their path when it disambiguates (e.g. two files with the same basename in different folders) — don't silently truncate to just the basename.
- The header count and the actual number of rows must always agree, including after expanding.
## Accessibility
- Each file row and the overflow toggle must be reachable and operable by keyboard, not just by mouse.
- Additions/deletions must not rely on color alone — the +/- sign already carries the meaning, so keep it even if you restyle the colors.
- The overflow toggle should update its accessible name/state (e.g. `aria-expanded`) when toggled.
## Related patterns
- Often appears as the terminal state of an agent turn, after a Thinking Loader/Expandable Trace sequence — the "here's what I actually changed" summary once work completes.
Diff Tabs
Per-file chips that switch an inline diff viewer between a batch of changed files.
thinking-loader/component.tsx+4-1
return (<div className="flex items-center gap-3 rounded-xl border"><divaria-live="polite"className="flex items-center gap-3 rounded-xl border">
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { FileCode2 } from "lucide-react";
import { cn } from "@/lib/utils";
export interface DiffLine {
type: "context" | "add" | "remove";
content: string;
}
export interface DiffTabFile {
id: string;
name: string;
additions: number;
deletions: number;
lines: DiffLine[];
}
export interface DiffTabsProps {
files: DiffTabFile[];
defaultFileId?: string;
className?: string;
}
export function DiffTabs({ files, defaultFileId, className }: DiffTabsProps) {
const [activeId, setActiveId] = React.useState(defaultFileId ?? files[0]?.id);
const active = files.find((file) => file.id === activeId) ?? files[0];
return (
<div className={cn("w-full", className)}>
<div className="flex flex-wrap items-center gap-2" role="tablist">
{files.map((file) => (
<button
key={file.id}
type="button"
role="tab"
aria-selected={file.id === active.id}
onClick={() => setActiveId(file.id)}
className={cn(
"flex items-center gap-1.5 rounded-md border px-2 py-1 text-xs font-medium transition-colors",
file.id === active.id
? "border-foreground/20 bg-accent text-foreground"
: "text-muted-foreground hover:bg-accent/50 hover:text-foreground"
)}
>
<span className="max-w-40 truncate">{file.name}</span>
<DiffCounts additions={file.additions} deletions={file.deletions} />
</button>
))}
</div>
<div className="mt-2 overflow-hidden rounded-2xl border bg-card">
<div className="flex items-center gap-2 border-b px-4 py-2.5">
<FileCode2 className="size-4 shrink-0 text-muted-foreground" aria-hidden />
<span className="flex-1 truncate text-xs font-medium">{active.name}</span>
<DiffCounts additions={active.additions} deletions={active.deletions} />
</div>
<AnimatePresence mode="wait" initial={false}>
<motion.div
key={active.id}
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -4 }}
transition={{ duration: 0.15, ease: "easeInOut" }}
className="overflow-x-auto"
>
<pre className="min-w-full font-mono text-xs leading-relaxed">
{active.lines.map((line, index) => (
<div
key={index}
className={cn(
"px-4 py-0.5",
line.type === "add" && "bg-emerald-500/10 text-emerald-700 dark:text-emerald-400",
line.type === "remove" && "bg-red-500/10 text-red-700 dark:text-red-400"
)}
>
<span aria-hidden className="mr-2 inline-block w-3 select-none text-muted-foreground">
{line.type === "add" ? "+" : line.type === "remove" ? "-" : ""}
</span>
{line.content}
</div>
))}
</pre>
</motion.div>
</AnimatePresence>
</div>
</div>
);
}
function DiffCounts({ additions, deletions }: { additions: number; deletions: number }) {
return (
<span className="shrink-0 font-mono text-[11px]">
<span className="text-emerald-600 dark:text-emerald-400">+{additions}</span>
{deletions > 0 && <span className="ml-1 text-red-600 dark:text-red-400">-{deletions}</span>}
</span>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Diff Tabs
## Summary
A row of per-file chips — each showing a file name and its add/delete line counts — that switch an inline diff viewer below between files. It lets the user flip through every file an agent touched without leaving the message, reading the actual changed lines rather than just a name and a count.
## When to use
- Right after (or instead of) a Diff Summary Card, when the user is likely to want to actually read the changes inline rather than open a separate diff viewer.
- A small-to-medium batch of files (roughly 2–8) where showing every file as a chip stays scannable in one row.
- Edits precise enough to render as real add/remove/context lines, not just a file-level description.
## When not to use
- A single file — skip the tab row and show its diff directly.
- Large batches (dozens of files): a wall of chips wrapping across many rows stops being scannable; fall back to a Diff Summary Card's list-plus-overflow instead.
- Binary or non-text changes (images, assets) — there's no line-level diff to render.
## Anatomy
- Tab row: one chip per file — file name (truncated, not wrapped) plus colored +N/-N counts — with the active file visually distinct (filled background) from the rest.
- Diff panel: header repeating the active file's name and counts, then the diff body.
- Diff body: one line per row, each tagged context / addition / removal, with removed and added lines tinted (not just colored text) so the eye can scan long files quickly.
## Behavior
- Selecting a chip swaps the diff panel's content; the swap should transition (a brief fade/slide), not hard-cut, so it reads as "same panel, new content" rather than a page change.
- Exactly one file is active at a time — this is a tab pattern, not a multi-select filter.
- The active chip and the diff header always show the same file name and counts; they must never fall out of sync.
- Long lines scroll horizontally within the diff panel rather than wrapping, which would break the line-by-line reading of a diff.
## Content guidelines
- File names show enough path to disambiguate same-named files in different folders; don't silently collapse to the basename.
- Additions and deletions are always shown together as +N/-N, even when one side is zero (omit only the zero side, e.g. a pure addition shows "+13" with no "-0").
## Accessibility
- The tab row and panel should use `role="tablist"`/`role="tab"` semantics (or equivalent) with `aria-selected` on the active chip, so the relationship between chip and panel is programmatic, not just visual.
- Chips must be reachable and operable by keyboard (arrow keys or tab order plus Enter/Space).
- Addition/removal styling must not rely on background tint alone if it's the only signal — keep the +/- marker in front of each line so the diff still reads in a high-contrast or no-color mode.
## Related patterns
- Diff Summary Card — the collapsed, file-list-only alternative for larger batches or when inline reading isn't the goal; Diff Tabs is the "let me actually read it here" counterpart.
Flowchart
Workflow trigger and condition steps on a dotted canvas.
Trigger
New pull request opened
Trigger when a PR is opened against main
If / Else
is
is
"use client";
import * as React from "react";
import { AnimatePresence, motion, Reorder, useDragControls } from "motion/react";
import { ChevronDown, GripVertical } from "lucide-react";
import { cn } from "@/lib/utils";
export interface FlowchartToken {
id: string;
icon?: React.ComponentType<{ className?: string }>;
label: string;
/** Tailwind background color class for a leading dot, e.g. "bg-amber-500". */
dotColor?: string;
}
export interface FlowchartClause {
id: string;
connector: "if" | "and" | "or";
subject: FlowchartToken;
subjectOptions?: FlowchartToken[];
field: FlowchartToken;
fieldOptions?: FlowchartToken[];
value: FlowchartToken;
valueOptions?: FlowchartToken[];
}
export interface FlowchartTriggerNode {
id: string;
type: "trigger";
icon: React.ComponentType<{ className?: string }>;
title: string;
description: string;
}
export interface FlowchartConditionNode {
id: string;
type: "condition";
clauses: FlowchartClause[];
}
export type FlowchartNode = FlowchartTriggerNode | FlowchartConditionNode;
export interface FlowchartProps {
nodes: FlowchartNode[];
className?: string;
}
type ClauseTokenKey = "subject" | "field" | "value";
type Offset = { dx: number; dy: number };
const badgeStyles: Record<FlowchartNode["type"], string> = {
trigger: "bg-violet-100 text-violet-700 dark:bg-violet-500/15 dark:text-violet-300",
condition: "bg-amber-100 text-amber-800 dark:bg-amber-500/15 dark:text-amber-300",
};
const badgeLabels: Record<FlowchartNode["type"], string> = {
trigger: "Trigger",
condition: "If / Else",
};
/* ── canvas layout constants ── */
const CANVAS_PAD = 32;
const ROW_GAP = 40;
const CARD_MAX_WIDTH = 384;
function estimateHeight(node: FlowchartNode) {
return node.type === "trigger" ? 116 : 96 + node.clauses.length * 56;
}
export function Flowchart({ nodes, className }: FlowchartProps) {
const [nodeList, setNodeList] = React.useState(nodes);
const canvasRef = React.useRef<HTMLDivElement>(null);
const nodeRefs = React.useRef(new Map<string, HTMLDivElement>());
const [canvasWidth, setCanvasWidth] = React.useState(0);
const [heights, setHeights] = React.useState<Record<string, number>>(() =>
Object.fromEntries(nodes.map((node) => [node.id, estimateHeight(node)]))
);
const [offsets, setOffsets] = React.useState<Record<string, Offset>>({});
const [draggingId, setDraggingId] = React.useState<string | null>(null);
React.useLayoutEffect(() => {
const canvas = canvasRef.current;
if (!canvas) return;
const measure = () => {
setCanvasWidth(canvas.clientWidth);
setHeights((prev) => {
const next = { ...prev };
let changed = false;
nodeRefs.current.forEach((el, id) => {
const h = el.offsetHeight;
if (h && Math.abs(h - (next[id] ?? 0)) > 0.5) {
next[id] = h;
changed = true;
}
});
return changed ? next : prev;
});
};
measure();
const observer = new ResizeObserver(measure);
observer.observe(canvas);
nodeRefs.current.forEach((el) => observer.observe(el));
return () => observer.disconnect();
}, [nodeList]);
/* stacked base position for each node, ignoring drag offsets */
const baseTops = React.useMemo(() => {
const tops: Record<string, number> = {};
let y = CANVAS_PAD;
nodeList.forEach((node) => {
tops[node.id] = y;
y += (heights[node.id] ?? estimateHeight(node)) + ROW_GAP;
});
return tops;
}, [nodeList, heights]);
const lastNode = nodeList[nodeList.length - 1];
const canvasHeight = lastNode
? baseTops[lastNode.id] + (heights[lastNode.id] ?? estimateHeight(lastNode)) + CANVAS_PAD
: CANVAS_PAD * 2;
const effectiveWidth = canvasWidth || CARD_MAX_WIDTH + CANVAS_PAD * 2;
const cardWidth = Math.max(Math.min(CARD_MAX_WIDTH, effectiveWidth - CANVAS_PAD * 2), 200);
const baseCenterX = effectiveWidth / 2;
function place(nodeId: string) {
const off = offsets[nodeId];
return {
cx: baseCenterX + (off?.dx ?? 0),
top: (baseTops[nodeId] ?? 0) + (off?.dy ?? 0),
};
}
function anchors(node: FlowchartNode) {
const { cx, top } = place(node.id);
const height = heights[node.id] ?? estimateHeight(node);
return {
top: { x: cx, y: top },
bottom: { x: cx, y: top + height },
};
}
function connector(from: FlowchartNode, to: FlowchartNode) {
const start = anchors(from).bottom;
const end = anchors(to).top;
const k = Math.min(Math.max(Math.abs(end.y - start.y) * 0.55, 24), 84);
return `M ${start.x} ${start.y} C ${start.x} ${start.y + k}, ${end.x} ${end.y - k}, ${end.x} ${end.y}`;
}
function handleDragMove(nodeId: string, node: FlowchartNode, dx: number, dy: number) {
const height = heights[nodeId] ?? estimateHeight(node);
const baseTop = baseTops[nodeId] ?? 0;
const minCx = cardWidth / 2 + CANVAS_PAD / 2;
const maxCx = Math.max(effectiveWidth - cardWidth / 2 - CANVAS_PAD / 2, minCx);
const cx = Math.min(Math.max(baseCenterX + dx, minCx), maxCx);
const top = Math.min(Math.max(baseTop + dy, 8), Math.max(canvasHeight - height - 8, 8));
setOffsets((current) => ({ ...current, [nodeId]: { dx: cx - baseCenterX, dy: top - baseTop } }));
}
function handleClausesReorder(nodeId: string, clauses: FlowchartClause[]) {
setNodeList((prev) =>
prev.map((node) => (node.id === nodeId && node.type === "condition" ? { ...node, clauses } : node))
);
}
function handleClauseTokenChange(
nodeId: string,
clauseId: string,
key: ClauseTokenKey,
token: FlowchartToken
) {
setNodeList((prev) =>
prev.map((node) =>
node.id === nodeId && node.type === "condition"
? {
...node,
clauses: node.clauses.map((clause) =>
clause.id === clauseId ? { ...clause, [key]: token } : clause
),
}
: node
)
);
}
return (
<div
ref={canvasRef}
className={cn(
"relative w-full rounded-2xl border bg-muted/20",
"[background-image:radial-gradient(var(--color-border)_1px,transparent_1px)] [background-size:16px_16px]",
className
)}
style={{ height: canvasHeight }}
>
<svg width={effectiveWidth} height={canvasHeight} className="pointer-events-none absolute inset-0" aria-hidden>
{nodeList.slice(1).map((node, i) => (
<path
key={node.id}
d={connector(nodeList[i], node)}
fill="none"
stroke="var(--color-border)"
strokeWidth={1.5}
/>
))}
</svg>
{nodeList.map((node) => {
const { cx, top } = place(node.id);
return (
<FlowchartNodeItem
key={node.id}
node={node}
offset={offsets[node.id] ?? { dx: 0, dy: 0 }}
style={{
left: cx,
top,
width: cardWidth,
zIndex: draggingId === node.id ? 2 : 1,
}}
registerRef={(el) => {
if (el) nodeRefs.current.set(node.id, el);
else nodeRefs.current.delete(node.id);
}}
onDragStart={() => setDraggingId(node.id)}
onDragMove={(dx, dy) => handleDragMove(node.id, node, dx, dy)}
onDragEnd={() => setDraggingId(null)}
onClausesReorder={(clauses) => handleClausesReorder(node.id, clauses)}
onClauseTokenChange={(clauseId, key, token) =>
handleClauseTokenChange(node.id, clauseId, key, token)
}
/>
);
})}
</div>
);
}
function FlowchartNodeItem({
node,
offset,
style,
registerRef,
onDragStart,
onDragMove,
onDragEnd,
onClausesReorder,
onClauseTokenChange,
}: {
node: FlowchartNode;
offset: Offset;
style: React.CSSProperties;
registerRef: (el: HTMLDivElement | null) => void;
onDragStart: () => void;
onDragMove: (dx: number, dy: number) => void;
onDragEnd: () => void;
onClausesReorder: (clauses: FlowchartClause[]) => void;
onClauseTokenChange: (clauseId: string, key: ClauseTokenKey, token: FlowchartToken) => void;
}) {
const drag = React.useRef<{ pointerId: number; startX: number; startY: number; baseDx: number; baseDy: number } | null>(
null
);
function handlePointerDown(event: React.PointerEvent<HTMLButtonElement>) {
drag.current = {
pointerId: event.pointerId,
startX: event.clientX,
startY: event.clientY,
baseDx: offset.dx,
baseDy: offset.dy,
};
event.currentTarget.setPointerCapture(event.pointerId);
onDragStart();
}
function handlePointerMove(event: React.PointerEvent<HTMLButtonElement>) {
const d = drag.current;
if (!d || d.pointerId !== event.pointerId) return;
onDragMove(d.baseDx + event.clientX - d.startX, d.baseDy + event.clientY - d.startY);
}
function handlePointerUp(event: React.PointerEvent<HTMLButtonElement>) {
if (drag.current?.pointerId === event.pointerId) {
drag.current = null;
onDragEnd();
}
}
return (
<div
ref={registerRef}
className="absolute flex -translate-x-1/2 flex-col items-start gap-1.5"
style={style}
>
<div className="flex items-center gap-1.5">
<span className={cn("rounded-md px-2.5 py-1 text-xs font-semibold", badgeStyles[node.type])}>
{badgeLabels[node.type]}
</span>
<button
type="button"
onPointerDown={handlePointerDown}
onPointerMove={handlePointerMove}
onPointerUp={handlePointerUp}
onPointerCancel={handlePointerUp}
aria-label="Drag to move this step"
className="flex size-5 shrink-0 touch-none items-center justify-center rounded text-muted-foreground transition-colors hover:bg-accent hover:text-foreground active:cursor-grabbing cursor-grab"
>
<GripVertical className="size-3.5" />
</button>
</div>
{node.type === "trigger" ? (
<TriggerCard node={node} />
) : (
<ConditionCard
node={node}
onClausesReorder={onClausesReorder}
onClauseTokenChange={onClauseTokenChange}
/>
)}
</div>
);
}
function TriggerCard({ node }: { node: FlowchartTriggerNode }) {
const Icon = node.icon;
return (
<div className="flex w-full items-center gap-2.5 rounded-2xl border bg-card p-3">
<span className="flex size-9 shrink-0 items-center justify-center rounded-xl bg-violet-100 text-violet-600 dark:bg-violet-500/15 dark:text-violet-300">
<Icon className="size-4" />
</span>
<div className="min-w-0">
<p className="text-xs font-semibold">{node.title}</p>
<p className="text-xs text-muted-foreground">{node.description}</p>
</div>
</div>
);
}
function ConditionCard({
node,
onClausesReorder,
onClauseTokenChange,
}: {
node: FlowchartConditionNode;
onClausesReorder: (clauses: FlowchartClause[]) => void;
onClauseTokenChange: (clauseId: string, key: ClauseTokenKey, token: FlowchartToken) => void;
}) {
return (
<div className="w-full rounded-2xl border bg-card p-3">
<Reorder.Group
as="div"
axis="y"
values={node.clauses}
onReorder={onClausesReorder}
className="flex flex-col gap-3"
>
{node.clauses.map((clause, i) => (
<ClauseRow
key={clause.id}
clause={clause}
displayConnector={i === 0 ? "if" : clause.connector === "if" ? "and" : clause.connector}
onTokenChange={(key, token) => onClauseTokenChange(clause.id, key, token)}
/>
))}
</Reorder.Group>
</div>
);
}
function ClauseRow({
clause,
displayConnector,
onTokenChange,
}: {
clause: FlowchartClause;
displayConnector: FlowchartClause["connector"];
onTokenChange: (key: ClauseTokenKey, token: FlowchartToken) => void;
}) {
const dragControls = useDragControls();
return (
<Reorder.Item
as="div"
value={clause}
dragListener={false}
dragControls={dragControls}
className="flex items-start gap-2 bg-card"
>
<button
type="button"
onPointerDown={(e) => dragControls.start(e)}
aria-label="Drag to reorder this clause"
className="flex w-10 shrink-0 touch-none items-center gap-1 rounded pt-1 text-xs text-muted-foreground transition-colors hover:text-foreground active:cursor-grabbing cursor-grab"
>
<GripVertical className="size-3.5 shrink-0" />
{displayConnector}
</button>
<div className="flex flex-1 flex-wrap items-center gap-2">
<TokenChip
variant="field"
token={clause.subject}
options={clause.subjectOptions}
onSelect={(token) => onTokenChange("subject", token)}
/>
<TokenChip
variant="field"
token={clause.field}
options={clause.fieldOptions}
onSelect={(token) => onTokenChange("field", token)}
/>
<span className="text-xs text-muted-foreground">is</span>
<TokenChip
variant="value"
token={clause.value}
options={clause.valueOptions}
onSelect={(token) => onTokenChange("value", token)}
/>
</div>
</Reorder.Item>
);
}
function TokenChip({
token,
options,
variant,
onSelect,
}: {
token: FlowchartToken;
options?: FlowchartToken[];
variant: "field" | "value";
onSelect: (token: FlowchartToken) => void;
}) {
const [open, setOpen] = React.useState(false);
const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
const Icon = token.icon;
const hasOptions = !!options?.length;
return (
<div ref={ref} className="relative" data-ui>
<button
type="button"
onClick={() => hasOptions && setOpen((v) => !v)}
aria-haspopup={hasOptions ? "listbox" : undefined}
aria-expanded={hasOptions ? open : undefined}
className={cn(
"inline-flex items-center gap-1.5 rounded-lg text-xs font-medium transition-colors",
variant === "field" ? "bg-muted px-2.5 py-1.5 hover:bg-accent" : "border px-3 py-1.5 hover:bg-accent",
!hasOptions && "cursor-default"
)}
>
{variant === "value" && token.dotColor && (
<span className={cn("size-2 shrink-0 rounded-full", token.dotColor)} />
)}
{variant === "field" && Icon && <Icon className="size-3.5 text-muted-foreground" />}
{token.label}
<ChevronDown className={cn("size-3.5 text-muted-foreground transition-transform", open && "rotate-180")} />
</button>
<AnimatePresence>
{open && hasOptions && (
<motion.div
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: 4 }}
transition={{ duration: 0.12 }}
role="listbox"
className="absolute left-0 top-full z-10 mt-2 min-w-40 overflow-hidden rounded-xl border bg-popover"
>
{options!.map((option) => (
<button
key={option.id}
type="button"
role="option"
aria-selected={option.id === token.id}
onClick={() => {
onSelect(option);
setOpen(false);
}}
className={cn(
"flex w-full items-center gap-1.5 px-3 py-2 text-left text-xs hover:bg-accent",
option.id === token.id && "font-medium"
)}
>
{option.dotColor && <span className={cn("size-2 shrink-0 rounded-full", option.dotColor)} />}
{option.icon && <option.icon className="size-3.5 text-muted-foreground" />}
{option.label}
</button>
))}
</motion.div>
)}
</AnimatePresence>
</div>
);
}
function useClickOutside<T extends HTMLElement>(onOutside: () => void) {
const ref = React.useRef<T>(null);
React.useEffect(() => {
function handle(e: MouseEvent) {
if (ref.current && !ref.current.contains(e.target as Node)) onOutside();
}
document.addEventListener("mousedown", handle);
return () => document.removeEventListener("mousedown", handle);
}, [onOutside]);
return ref;
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Flowchart
## Summary
A read-at-a-glance diagram of a workflow's trigger and condition steps, laid out on a dotted canvas with a connecting line between nodes. Each step is a colored badge ("Trigger", "If / Else") above a white card, so the flow reads top-to-bottom by default like a sentence: "when this happens, and this is true, then...". Every card can be dragged freely to any position on the canvas — not just reordered vertically — and the connector redraws live to keep the two ends linked.
## When to use
- Automation / workflow builders where a user assembles trigger + condition + action steps (e.g. "when a pull request is opened, if files changed is greater than 50 and path matches src/registry/**").
- Summarizing a rule or pipeline for review, where the exact sequence and branching matters more than density.
- When users benefit from spatially rearranging steps (e.g. to make room for annotations, or to group related steps) without that rearrangement changing execution order.
## When not to use
- For a linear list of steps with no branching or field-level detail — use Expandable Trace instead, it's lighter weight.
- As a fully interactive node-based editor (drag-to-connect new edges, zoom/pan, arbitrary graph topology, multiple outgoing branches). This pattern keeps a fixed sequence of nodes that can be repositioned; build a dedicated canvas editor for free-form graphs.
- When there are more than a handful of steps and horizontal branches — a single chain of nodes stops communicating structure once branches fork.
## Anatomy
- Canvas: a bordered, rounded container with a dotted background that visually separates the flow from surrounding UI. Its height is sized to the flow's default stacked layout.
- Node badge: a small colored pill labeling the node's kind ("Trigger" in violet, "If / Else" in amber), paired with a drag handle used to reposition the whole card. Color coding lets users scan a long flow for node types without reading every card.
- Node card: a white, rounded, shadowed card containing the node's content, absolutely positioned on the canvas so it can be dragged anywhere within it.
- Trigger card: icon in a tinted rounded box, a bold title, and a one-line description.
- Condition card: one row per clause. Each row has a drag handle, a connector word ("if" / "and" / "or"), a subject field chip (with icon), a comparison field chip, the word "is", and a value chip (a leading color dot + label) representing the selected option.
- Connector line: a curved line between consecutive nodes (bottom of one to top of the next), showing they execute in sequence regardless of where each card currently sits on the canvas.
## Behavior
- Each card's badge-row drag handle moves that card freely in both x and y; the sequence of steps (and therefore execution order) is unaffected by where a card is dropped — only its position on the canvas changes.
- The connector between two nodes recalculates on every drag frame, so it always runs from the bottom of the upstream card to the top of the downstream card no matter how far either has been moved.
- Dragging is clamped to stay inside the canvas bounds so a card can never be dropped off-canvas or outside the connector's reach.
- Field and value chips are dropdown triggers (chevron affixed) even in a read-only summary — they signal "this is configurable," not just descriptive text. They keep working normally after a card has been repositioned.
- Long values (e.g. a long file path) wrap onto their own line, indented to align under the row's first field chip rather than the card edge, so the row still reads as one clause.
- The drag handle on each clause row implies clauses are reorderable within their card; only show it when reordering is actually supported.
## Content guidelines
- Trigger titles are short event names ("New order created"); descriptions restate them as a plain sentence for users who need the extra context.
- Connector words are lowercase ("if", "and", "or") to read as a natural sentence, not shouty labels.
- Value chips show the selected option's label verbatim (e.g. a specific file path or category name), not a truncated or reformatted version.
## Accessibility
- The dotted background is decorative only — mark it `aria-hidden` or apply it via CSS so it isn't announced.
- Connector lines between nodes are decorative; mark them `aria-hidden` too.
- Each chip that opens a picker needs a real `button` element (or equivalent) so it's reachable and operable by keyboard, not a styled `span`.
## Related patterns
- Expandable Trace is the lighter-weight, non-branching alternative for a simple ordered list of steps.
- Prompt Bar uses the same "chip with chevron opens a picker" idea for inline @ and / suggestions.
Chat Bubble with Actions
A message bubble with feedback thumbs, edit-and-resubmit, retry/regenerate, and a version stepper.
Which loader should I use while my agent is thinking?
For a single reasoning step, the Thinking Loader keeps it simple — a shimmering label with a live elapsed-time counter.
"use client";
import * as React from "react";
import { Check, ChevronLeft, ChevronRight, Copy, Pencil, RotateCcw, ThumbsDown, ThumbsUp } from "lucide-react";
import { cn } from "@/lib/utils";
export type ChatRole = "user" | "assistant";
export type ChatFeedback = "up" | "down" | null;
export interface ChatBubbleProps {
role: ChatRole;
content: string;
onEditSubmit?: (content: string) => void;
onRegenerate?: () => void;
onFeedback?: (feedback: ChatFeedback) => void;
/** 0-based index of the version currently shown. Omit (with versionCount) to hide the stepper. */
versionIndex?: number;
/** Total number of versions (edits/regenerations) available for this message. */
versionCount?: number;
onVersionChange?: (index: number) => void;
className?: string;
}
export function ChatBubble({
role,
content,
onEditSubmit,
onRegenerate,
onFeedback,
versionIndex,
versionCount,
onVersionChange,
className,
}: ChatBubbleProps) {
const [editing, setEditing] = React.useState(false);
const [draft, setDraft] = React.useState(content);
const [feedback, setFeedback] = React.useState<ChatFeedback>(null);
const [copied, setCopied] = React.useState(false);
const isUser = role === "user";
const hasVersions = versionCount != null && versionCount > 1 && versionIndex != null && onVersionChange;
function startEdit() {
setDraft(content);
setEditing(true);
}
function handleFeedback(next: ChatFeedback) {
const value = feedback === next ? null : next;
setFeedback(value);
onFeedback?.(value);
}
async function handleCopy() {
await navigator.clipboard.writeText(content);
setCopied(true);
window.setTimeout(() => setCopied(false), 1500);
}
function commitEdit() {
const trimmed = draft.trim();
setEditing(false);
if (!trimmed || trimmed === content) {
setDraft(content);
return;
}
onEditSubmit?.(trimmed);
}
function cancelEdit() {
setDraft(content);
setEditing(false);
}
return (
<div className={cn("group flex flex-col gap-1.5", isUser ? "items-end" : "items-start", className)}>
{editing ? (
<div className="w-full max-w-md space-y-2">
<textarea
autoFocus
value={draft}
onChange={(e) => setDraft(e.target.value)}
onKeyDown={(e) => {
if (e.key === "Enter" && !e.shiftKey) {
e.preventDefault();
commitEdit();
}
if (e.key === "Escape") cancelEdit();
}}
rows={Math.min(6, Math.max(2, draft.split("\n").length))}
className="w-full resize-none rounded-2xl border bg-background px-4 py-2.5 text-sm leading-relaxed outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50"
/>
<div className="flex justify-end gap-2">
<button
type="button"
onClick={cancelEdit}
className="rounded-full px-3 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
Cancel
</button>
<button
type="button"
onClick={commitEdit}
className="rounded-full bg-primary px-3 py-1 text-xs font-medium text-primary-foreground transition-colors hover:bg-primary/90"
>
Save & submit
</button>
</div>
</div>
) : (
<div
className={cn(
"max-w-md rounded-2xl px-4 py-2.5 text-sm leading-relaxed",
isUser ? "bg-primary text-primary-foreground" : "bg-muted text-foreground"
)}
>
{content}
</div>
)}
{!editing && (
<div
className={cn(
"flex items-center gap-0.5 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100 group-focus-within:opacity-100",
(copied || feedback) && "opacity-100"
)}
>
{isUser ? (
<>
{onRegenerate && (
<IconButton label="Retry" onClick={onRegenerate}>
<RotateCcw className="size-3.5" />
</IconButton>
)}
<IconButton label="Edit message" onClick={startEdit}>
<Pencil className="size-3.5" />
</IconButton>
<IconButton label="Copy" onClick={handleCopy}>
{copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
</IconButton>
</>
) : (
<>
<IconButton label="Copy" onClick={handleCopy}>
{copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
</IconButton>
<IconButton label="Good response" active={feedback === "up"} onClick={() => handleFeedback("up")}>
<ThumbsUp className="size-3.5" />
</IconButton>
<IconButton label="Bad response" active={feedback === "down"} onClick={() => handleFeedback("down")}>
<ThumbsDown className="size-3.5" />
</IconButton>
<IconButton label="Regenerate" onClick={onRegenerate}>
<RotateCcw className="size-3.5" />
</IconButton>
</>
)}
{hasVersions && (
<VersionNav index={versionIndex} count={versionCount} onChange={onVersionChange} />
)}
</div>
)}
</div>
);
}
function VersionNav({
index,
count,
onChange,
}: {
index: number;
count: number;
onChange: (index: number) => void;
}) {
return (
<div className="ml-0.5 flex items-center gap-0.5 border-l pl-1">
<IconButton label="Previous version" onClick={() => onChange(index - 1)} disabled={index <= 0}>
<ChevronLeft className="size-3.5" />
</IconButton>
<span className="min-w-[2.5ch] text-center text-xs tabular-nums text-muted-foreground">
{index + 1}/{count}
</span>
<IconButton label="Next version" onClick={() => onChange(index + 1)} disabled={index >= count - 1}>
<ChevronRight className="size-3.5" />
</IconButton>
</div>
);
}
function IconButton({
label,
active,
disabled,
onClick,
children,
}: {
label: string;
active?: boolean;
disabled?: boolean;
onClick?: () => void;
children: React.ReactNode;
}) {
return (
<button
type="button"
onClick={onClick}
disabled={disabled}
aria-label={label}
aria-pressed={active}
className={cn(
"rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground",
active && "bg-accent text-foreground",
disabled && "pointer-events-none opacity-40"
)}
>
{children}
</button>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Chat Bubble with Actions
## Summary
A conversational message bubble — user or assistant — with an inline action row that reveals on hover/focus: Copy, thumbs up/down feedback, and Regenerate on assistant replies; Retry, Edit (and resubmit), and Copy on the user's own messages. When a message has more than one version — from an edit or a retry/regenerate — a version stepper ("2/2" with prev/next arrows) appears at the end of the row so people can page through history without losing it.
## When to use
- Any chat-style conversation UI where actions belong to a single message, not a global toolbar.
- Assistant replies that benefit from an explicit quality signal (thumbs) or a one-click retry when the first answer misses.
- User messages the person may want to correct or refine after seeing the reply (a typo, an added detail, a different phrasing) without retyping the whole conversation.
- Conversations where regenerating or editing produces multiple candidate replies/prompts worth keeping around instead of discarding — the version stepper lets people compare them without duplicating bubbles on screen.
## When not to use
- Read-only transcripts (chat history exports, shared/public views) where no one should be able to edit or regenerate.
- Broadcast or group messages, where "edit and resubmit" would silently change what other participants already saw — reserve it for single-user assistant conversations, where resubmitting is understood to fork the conversation rather than rewrite history for everyone.
- Very short-lived, ephemeral UI (toasts, system notices) — the action row adds visual weight that isn't earned there.
## Anatomy
- Message bubble: role-differentiated style (e.g. user bubble filled/right-aligned, assistant bubble muted/left-aligned).
- Action row, below the bubble, revealed on hover/focus:
- User: Retry, Edit, Copy.
- Assistant: Copy, thumbs up, thumbs down, Regenerate.
- Version stepper (optional, trailing): a vertical divider, a previous-version chevron, an "n/total" counter, a next-version chevron — shown only when the message has more than one version.
- Edit mode: the bubble becomes an editable textarea in place, with Cancel and "Save & submit" controls.
## Behavior
- The action row stays hidden until the bubble (or an action inside it) has hover or keyboard focus — it shouldn't compete with the message content at rest.
- Once feedback is given, the corresponding thumb stays visibly active (a toggle, not a one-shot click) so the state reads even after the row is no longer hovered; clicking the same thumb again clears it.
- Retry (user) and Regenerate (assistant) both resend the current user message and produce a new reply. Wire them to the same re-send handler — retrying from the user bubble is equivalent to regenerating from the assistant bubble that follows it.
- Regenerating/retrying never overwrites history in place — it adds a new version and moves the stepper to it, so earlier attempts stay reachable via the prev arrow.
- Editing a user message swaps the bubble for a textarea pre-filled with the current text. Enter (without Shift) or "Save & submit" commits it; Escape or Cancel discards the edit and restores the original text.
- Submitting an edited user message is expected to invalidate and regenerate the assistant reply that followed it — this pattern doesn't perform that regeneration itself, but callers should wire the edit-submit handler to a re-send that also creates a new version.
- Only one bubble is in edit mode at a time.
- The version stepper is only rendered when there's more than one version (`versionCount > 1`) — a message with a single version shows no stepper at all, not a disabled "1/1".
- Navigating the stepper on either the user or assistant bubble in a pair should move both in lockstep, since a version represents one full turn (the prompt and the reply it produced), not two independently versioned halves.
- The prev/next arrows disable at the ends of the version range instead of wrapping.
## Content guidelines
- Label the commit action "Save & submit" (or equivalent), not just "Save" — it should read as re-sending the message, a bigger consequence than saving a draft.
- Keep the action icons unlabeled visually but always give each a real accessible name — icon-only rows save space but must not go nameless.
- Keep the version counter numeric and terse ("2/2"); it's a position indicator, not a label — don't spell out "Version 2 of 2" inline.
## Accessibility
- Every action button needs a descriptive `aria-label` ("Good response", "Bad response", "Regenerate", "Retry", "Edit message", "Copy", "Previous version", "Next version") since the icon alone carries no accessible name.
- Thumbs up/down are toggle buttons — expose state with `aria-pressed`, not color alone.
- The action row must be reachable by keyboard, not only `:hover` — use `:focus-within` on the bubble so Tab reveals it.
- Disabled stepper arrows (at the first/last version) must be real `disabled` buttons, not just dimmed, so assistive tech and keyboard users don't land on a dead control.
- The edit textarea should receive focus automatically when edit mode opens, and focus should land somewhere sensible (the bubble, or the next actionable element) when it closes.
## Related patterns
- Pairs with Streaming Text for the assistant reply while it's still generating; this pattern's action row is the equivalent post-stream toolbar for a persisted chat message rather than a one-off streamed answer.
- For a voice-composed message, show a Live Transcript while the person is still speaking, then hand the finalized text off into a user bubble once the turn ends — don't run the transcript's interim/final styling inside the bubble itself.
Tool Approval
A pending tool-call prompt with allow, always-allow, and deny actions.
Bash
Run a shell command
npm install lodash"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { Check, ChevronDown, ShieldCheck, X } from "lucide-react";
import { cn } from "@/lib/utils";
export type ToolApprovalDecision = "allow" | "always-allow" | "deny";
export interface ToolApprovalScope {
id: string;
label: string;
}
export interface ToolApprovalProps {
icon: React.ComponentType<{ className?: string }>;
toolName: string;
summary: string;
detail?: string;
scopes?: ToolApprovalScope[];
onDecision?: (decision: ToolApprovalDecision, scope?: ToolApprovalScope) => void;
className?: string;
}
const defaultScopes: ToolApprovalScope[] = [
{ id: "command", label: "this command" },
{ id: "project", label: "this project" },
{ id: "always", label: "always" },
];
interface Resolution {
decision: ToolApprovalDecision;
scope?: ToolApprovalScope;
}
export function ToolApproval({
icon: Icon,
toolName,
summary,
detail,
scopes = defaultScopes,
onDecision,
className,
}: ToolApprovalProps) {
const [resolution, setResolution] = React.useState<Resolution | null>(null);
const [scopeOpen, setScopeOpen] = React.useState(false);
const scopeRef = useClickOutside<HTMLDivElement>(() => setScopeOpen(false));
function resolve(decision: ToolApprovalDecision, scope?: ToolApprovalScope) {
setScopeOpen(false);
setResolution({ decision, scope });
onDecision?.(decision, scope);
}
if (resolution) {
return <ResolvedRow toolName={toolName} resolution={resolution} className={className} />;
}
return (
<div className={cn("w-full overflow-hidden rounded-2xl border bg-card", className)}>
<div className="flex items-start gap-3 px-4 py-3.5">
<span className="flex size-9 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground">
<Icon className="size-4.5" />
</span>
<div className="min-w-0 flex-1 pt-0.5">
<p className="text-sm font-semibold">{toolName}</p>
<p className="text-xs text-muted-foreground">{summary}</p>
</div>
</div>
{detail && (
<div className="px-4 pb-3.5">
<code className="block overflow-x-auto rounded-lg bg-muted px-3 py-2 font-mono text-xs">{detail}</code>
</div>
)}
<div className="flex items-center gap-2 border-t px-4 py-3">
<button
type="button"
onClick={() => resolve("deny")}
className="rounded-full px-3.5 py-1.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
Deny
</button>
<div className="ml-auto flex items-center gap-2">
<div ref={scopeRef} className="relative shrink-0">
<div className="flex items-center overflow-hidden rounded-full border">
<button
type="button"
onClick={() => resolve("always-allow", scopes[0])}
className="px-3.5 py-1.5 text-xs font-medium transition-colors hover:bg-accent"
>
Always allow
</button>
<button
type="button"
aria-haspopup="menu"
aria-expanded={scopeOpen}
aria-label="Choose scope for always allow"
onClick={() => setScopeOpen((v) => !v)}
className="flex h-full items-center border-l px-2 py-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<ChevronDown className={cn("size-3.5 transition-transform", scopeOpen && "rotate-180")} />
</button>
</div>
<AnimatePresence>
{scopeOpen && (
<motion.div
role="menu"
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: 4 }}
transition={{ duration: 0.12 }}
className="absolute bottom-full right-0 z-10 mb-2 w-44 overflow-hidden rounded-xl border bg-popover"
>
{scopes.map((scope) => (
<button
key={scope.id}
type="button"
role="menuitem"
onClick={() => resolve("always-allow", scope)}
className="block w-full px-3 py-2 text-left text-xs hover:bg-accent"
>
Always allow for {scope.label}
</button>
))}
</motion.div>
)}
</AnimatePresence>
</div>
<button
type="button"
onClick={() => resolve("allow")}
className="rounded-full bg-foreground px-4 py-1.5 text-xs font-medium text-background transition-colors hover:bg-foreground/90"
>
Allow
</button>
</div>
</div>
</div>
);
}
function ResolvedRow({
toolName,
resolution,
className,
}: {
toolName: string;
resolution: Resolution;
className?: string;
}) {
const label =
resolution.decision === "deny"
? "Denied"
: resolution.decision === "always-allow"
? `Always allowed for ${resolution.scope?.label ?? "this project"}`
: "Allowed";
return (
<div className={cn("flex items-center gap-3 rounded-2xl border bg-card px-4 py-3", className)}>
<span
className={cn(
"flex size-8 shrink-0 items-center justify-center rounded-full",
resolution.decision === "deny"
? "bg-red-100 text-red-600 dark:bg-red-500/15 dark:text-red-400"
: "bg-emerald-100 text-emerald-600 dark:bg-emerald-500/15 dark:text-emerald-400"
)}
>
{resolution.decision === "deny" ? (
<X className="size-4" />
) : resolution.decision === "always-allow" ? (
<ShieldCheck className="size-4" />
) : (
<Check className="size-4" />
)}
</span>
<div className="min-w-0 flex-1">
<p className="text-xs font-medium">{toolName}</p>
<p className="text-[11px] text-muted-foreground">{label}</p>
</div>
</div>
);
}
function useClickOutside<T extends HTMLElement>(onOutside: () => void) {
const ref = React.useRef<T>(null);
React.useEffect(() => {
function handle(e: MouseEvent) {
if (ref.current && !ref.current.contains(e.target as Node)) onOutside();
}
document.addEventListener("mousedown", handle);
return () => document.removeEventListener("mousedown", handle);
}, [onOutside]);
return ref;
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Tool Approval
## Summary
A pending permission prompt shown before an agent executes a tool call it doesn't already have standing approval for: the tool's name, a plain-language summary of what it's about to do, the literal call (command, path, args) it will run, and three ways to respond — deny it, allow it once, or always allow it going forward. Once answered, it collapses into a compact resolved row so the transcript keeps moving.
## When to use
- Before any tool call whose effect is irreversible, external, or otherwise outside the trust the agent already has (running a shell command, calling a paid API, writing outside the project, sending a message on the user's behalf).
- Inline in an agent transcript or chat UI, at the point the call would happen — not as an app-blocking modal, since the user usually wants the surrounding conversation still visible while deciding.
## When not to use
- For actions the user already granted standing permission for — show them running, not asking again. Re-prompting after "always allow" erodes trust in the setting.
- For read-only, side-effect-free calls (e.g. re-reading a file already in context) where the friction outweighs the risk — gate only what actually needs gating.
- As a generic confirm dialog for non-tool actions (e.g. "delete this message?"). Use a plain confirmation pattern instead; this one is specifically a pending tool call with a scope decision attached.
## Anatomy
- Icon: a small tinted box identifying the tool (terminal, globe, file, etc.).
- Title + summary: the tool's name and a one-line plain-language description of the action.
- Detail block: the literal call being made (a shell command, a URL, a file path) in monospace, so the user can verify exactly what will run rather than trusting the summary alone.
- Action row: Deny, Always allow (with a scope picker), and Allow — deny nearest the reading start, the two affirmative actions grouped on the trailing side.
- Resolved state: once answered, the whole card collapses to a single row — a status icon and a short label ("Allowed", "Always allowed for this project", "Denied") — replacing the action row entirely.
## Behavior
- "Always allow" is a split control: clicking the label applies a default scope immediately; the attached chevron opens a short menu of narrower/wider scopes (e.g. "this command", "this project", "always") so precision doesn't cost extra clicks in the common case.
- A decision is terminal for this prompt — there's no separate confirm step after clicking one of the three actions, and none of the actions stay interactive once a decision is recorded.
- Deny doesn't carry a scope; it always applies to just this one call. Permanently blocking a tool belongs in settings, not this prompt.
- The detail block shows the actual call verbatim (real command, real path), never a paraphrase — this is the one place the user gets to verify before it runs.
## Content guidelines
- Tool names are short and literal ("Bash", "Web Search"), not a marketing name for the underlying feature.
- The summary states the action, not the agent's justification for it ("Run a shell command", not "I need to check if the tests pass").
- Scope labels in the always-allow menu name what they cover concretely ("this project", "this command"), never vague terms like "sometimes".
## Accessibility
- The three (or more, with scope options) actions must be real, focusable buttons — a keyboard-only user needs to reach Deny as easily as Allow.
- The always-allow menu follows the standard disclosure pattern: `aria-haspopup`/`aria-expanded` on the trigger, and closes on Escape or an outside click.
- Don't rely on color alone to distinguish Allow from Deny — the label text already carries the meaning, so keep it even under custom theming.
## Related patterns
- Diff Summary Card is the after-the-fact counterpart — this pattern gates a call before it runs, that one summarizes calls that already ran.
- Prompt Bar's chip-with-chevron dropdown is the same disclosure idiom used here for the scope picker.
Connector Panel
A settings panel for connecting an app or MCP server — shows capabilities overview, groups tools by type, and lets users set per-tool permission levels.
Vercel
Manage teams, projects, and deployments; search documentation and control infrastructure.
Tools
Check domain availability and priceMCP
Check whether one or more domain names are available for purchase and retrieve their pricing information.
Get temporary access to a Vercel URLMCP
Generate a temporary shareable link (valid ~23 hours) that bypasses authentication for a protected Vercel deployment URL, avoiding 403 errors.
Get agent run detailsMCP
Get detailed metadata for a single agent run, including events, workflow metadata, usage, and subagent breakout data. Requires a run ID.
Get agent run traceMCP
Get the full trace for a single agent run, including turns, messages, reasoning, tool calls, token usage, and tool input/output.
Get a deploymentMCP
Retrieve details for a specific Vercel deployment using its ID or URL, including status, metadata, and configuration.
Create a deploymentMCP
Deploy a project by pushing a new build. Accepts environment variables, build settings, and a target environment.
Update environment variableMCP
Create or update an environment variable for a project across one or more target environments (production, preview, development).
Add domain to projectMCP
Assign a custom domain to a Vercel project and configure its DNS records automatically.
List team membersMCP
Return all members of a Vercel team, including their roles, join dates, and access scopes.
Invite team memberMCP
Send an invitation email to add a new member to the team with a specified role.
Update member roleMCP
Change the role of an existing team member between Owner, Member, and Developer.
Delete a deploymentMCP
Permanently remove a deployment by ID. This action cannot be undone.
Remove domain from projectMCP
Detach a custom domain from a project and delete its associated DNS configuration.
Remove team memberMCP
Revoke a member's access to the team. They will lose access to all team projects immediately.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import {
BadgeCheck,
ChevronDown,
ExternalLink,
Plus,
Search,
X,
} from "lucide-react";
import { cn } from "@/lib/utils";
export type ToolPermission = "allow" | "always-ask" | "disable";
export interface ConnectorTool {
id: string;
name: string;
description: string;
badge?: string;
permission: ToolPermission;
}
export interface ConnectorToolGroup {
id: string;
label: string;
tools: ConnectorTool[];
}
export interface ConnectorLink {
label: string;
href: string;
icon?: React.ComponentType<{ className?: string }>;
}
export interface ConnectorPanelProps {
appName: string;
appDescription: string;
appIcon?: React.ReactNode;
verified?: boolean;
overview?: string[];
links?: ConnectorLink[];
toolGroups: ConnectorToolGroup[];
onAddConnector?: () => void;
onClose?: () => void;
onPermissionChange?: (toolId: string, permission: ToolPermission) => void;
onGroupAllow?: (groupId: string) => void;
className?: string;
}
// ─── Permission toggle ────────────────────────────────────────────────────────
function PermissionToggle({
value,
onChange,
toolName,
}: {
value: ToolPermission;
onChange: (p: ToolPermission) => void;
toolName: string;
}) {
const options: { value: ToolPermission; label: string }[] = [
{ value: "disable", label: "Disable" },
{ value: "always-ask", label: "Always ask" },
{ value: "allow", label: "Allow" },
];
return (
<div
role="group"
aria-label={`Permission for ${toolName}`}
className="flex shrink-0 items-center gap-1"
>
{options.map((opt) => (
<button
key={opt.value}
type="button"
onClick={() => onChange(opt.value)}
aria-pressed={value === opt.value}
className={cn(
"rounded-md px-2.5 py-1 text-xs font-medium transition-colors",
value === opt.value
? "bg-foreground text-background"
: "text-muted-foreground hover:bg-accent hover:text-foreground",
)}
>
{opt.label}
</button>
))}
</div>
);
}
// ─── Tool row ─────────────────────────────────────────────────────────────────
function ToolRow({
tool,
onPermissionChange,
}: {
tool: ConnectorTool;
onPermissionChange: (p: ToolPermission) => void;
}) {
return (
<div className="flex items-start gap-3 border-t px-4 py-3">
<div className="min-w-0 flex-1">
<div className="flex flex-wrap items-center gap-1.5">
<span className="text-xs font-semibold">{tool.name}</span>
{tool.badge && (
<span className="rounded-full border px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
{tool.badge}
</span>
)}
</div>
<p className="mt-0.5 text-xs leading-relaxed text-muted-foreground">
{tool.description}
</p>
</div>
<PermissionToggle
value={tool.permission}
onChange={onPermissionChange}
toolName={tool.name}
/>
</div>
);
}
// ─── Tool group section ───────────────────────────────────────────────────────
function ToolGroupSection({
group,
onPermissionChange,
onGroupAllow,
}: {
group: ConnectorToolGroup & { tools: ConnectorTool[] };
onPermissionChange: (toolId: string, p: ToolPermission) => void;
onGroupAllow: (groupId: string) => void;
}) {
const [collapsed, setCollapsed] = React.useState(false);
const allAllowed = group.tools.every((t) => t.permission === "allow");
return (
<div>
<div className="flex items-center gap-2 px-4 py-2">
<button
type="button"
onClick={() => setCollapsed((c) => !c)}
aria-expanded={!collapsed}
className="flex flex-1 items-center gap-1 text-xs font-medium text-muted-foreground hover:text-foreground"
>
<ChevronDown
className={cn(
"size-3.5 shrink-0 transition-transform",
collapsed && "-rotate-90",
)}
aria-hidden
/>
{group.label}
</button>
{!allAllowed && (
<button
type="button"
onClick={() => onGroupAllow(group.id)}
className="rounded-md bg-foreground px-2.5 py-1 text-xs font-medium text-background transition-opacity hover:opacity-80"
>
Allow
</button>
)}
</div>
<AnimatePresence initial={false}>
{!collapsed && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.18 }}
className="overflow-hidden"
>
{group.tools.map((tool) => (
<ToolRow
key={tool.id}
tool={tool}
onPermissionChange={(p) => onPermissionChange(tool.id, p)}
/>
))}
</motion.div>
)}
</AnimatePresence>
</div>
);
}
// ─── Filter bar ───────────────────────────────────────────────────────────────
function FilterBar({
groups,
activeGroup,
onGroupChange,
query,
onQueryChange,
}: {
groups: ConnectorToolGroup[];
activeGroup: string | null;
onGroupChange: (id: string | null) => void;
query: string;
onQueryChange: (q: string) => void;
}) {
const [dropOpen, setDropOpen] = React.useState(false);
const dropRef = React.useRef<HTMLDivElement>(null);
React.useEffect(() => {
if (!dropOpen) return;
function handle(e: MouseEvent) {
if (!dropRef.current?.contains(e.target as Node)) setDropOpen(false);
}
document.addEventListener("mousedown", handle);
return () => document.removeEventListener("mousedown", handle);
}, [dropOpen]);
const currentLabel =
groups.find((g) => g.id === activeGroup)?.label ?? "All";
return (
<div className="flex items-center gap-2 border-b px-4 py-2.5">
<div ref={dropRef} className="relative shrink-0">
<button
type="button"
onClick={() => setDropOpen((o) => !o)}
aria-haspopup="listbox"
aria-expanded={dropOpen}
className="inline-flex items-center gap-1 rounded-md border px-2.5 py-1.5 text-xs font-medium transition-colors hover:bg-accent"
>
{currentLabel}
<ChevronDown
className={cn(
"size-3 opacity-60 transition-transform",
dropOpen && "rotate-180",
)}
aria-hidden
/>
</button>
<AnimatePresence>
{dropOpen && (
<motion.ul
role="listbox"
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: 4 }}
transition={{ duration: 0.1 }}
className="absolute left-0 top-full z-10 mt-1 min-w-[140px] overflow-hidden rounded-xl border bg-popover shadow-lg"
>
<li>
<button
type="button"
role="option"
aria-selected={activeGroup === null}
onClick={() => {
onGroupChange(null);
setDropOpen(false);
}}
className={cn(
"w-full px-3 py-2 text-left text-xs transition-colors hover:bg-accent",
activeGroup === null && "font-semibold",
)}
>
All
</button>
</li>
{groups.map((g) => (
<li key={g.id}>
<button
type="button"
role="option"
aria-selected={activeGroup === g.id}
onClick={() => {
onGroupChange(g.id);
setDropOpen(false);
}}
className={cn(
"w-full px-3 py-2 text-left text-xs transition-colors hover:bg-accent",
activeGroup === g.id && "font-semibold",
)}
>
{g.label}
</button>
</li>
))}
</motion.ul>
)}
</AnimatePresence>
</div>
<div className="relative flex-1">
<Search
className="absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground"
aria-hidden
/>
<input
type="search"
value={query}
onChange={(e) => onQueryChange(e.target.value)}
placeholder="Search tools"
aria-label="Search tools"
className="w-full rounded-md border bg-background py-1.5 pl-8 pr-3 text-xs placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring"
/>
</div>
</div>
);
}
// ─── Main export ──────────────────────────────────────────────────────────────
export function ConnectorPanel({
appName,
appDescription,
appIcon,
verified = false,
overview = [],
links = [],
toolGroups: initialGroups,
onAddConnector,
onClose,
onPermissionChange,
onGroupAllow,
className,
}: ConnectorPanelProps) {
const [toolGroups, setToolGroups] = React.useState(initialGroups);
const [query, setQuery] = React.useState("");
const [activeGroup, setActiveGroup] = React.useState<string | null>(null);
function handlePermissionChange(toolId: string, permission: ToolPermission) {
setToolGroups((prev) =>
prev.map((group) => ({
...group,
tools: group.tools.map((t) =>
t.id === toolId ? { ...t, permission } : t,
),
})),
);
onPermissionChange?.(toolId, permission);
}
function handleGroupAllow(groupId: string) {
setToolGroups((prev) =>
prev.map((group) =>
group.id === groupId
? {
...group,
tools: group.tools.map((t) => ({
...t,
permission: "allow" as ToolPermission,
})),
}
: group,
),
);
onGroupAllow?.(groupId);
}
const filteredGroups = toolGroups
.filter((g) => !activeGroup || g.id === activeGroup)
.map((g) => ({
...g,
tools: g.tools.filter(
(t) =>
!query ||
t.name.toLowerCase().includes(query.toLowerCase()) ||
t.description.toLowerCase().includes(query.toLowerCase()),
),
}))
.filter((g) => g.tools.length > 0);
return (
<div
className={cn(
"flex w-full flex-col overflow-hidden rounded-2xl border bg-background shadow-xl",
className,
)}
>
{/* Header */}
<div className="flex items-start gap-3 border-b px-5 py-4">
{appIcon && (
<div className="flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-xl border bg-muted">
{appIcon}
</div>
)}
<div className="min-w-0 flex-1">
<div className="flex items-center gap-1.5">
<span className="text-sm font-semibold">{appName}</span>
{verified && (
<BadgeCheck
className="size-4 shrink-0 text-blue-500"
aria-label="Verified"
/>
)}
</div>
<p className="mt-0.5 text-xs leading-relaxed text-muted-foreground">
{appDescription}
</p>
</div>
<div className="flex shrink-0 items-center gap-1.5">
<button
type="button"
onClick={onAddConnector}
className="inline-flex items-center gap-1.5 rounded-lg bg-foreground px-3 py-1.5 text-xs font-medium text-background transition-opacity hover:opacity-80"
>
<Plus className="size-3.5" aria-hidden />
Add connector
</button>
{onClose && (
<button
type="button"
onClick={onClose}
aria-label="Close"
className="rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-4" aria-hidden />
</button>
)}
</div>
</div>
{/* Body */}
<div className="flex min-h-0 flex-1">
{/* Sidebar */}
<aside
aria-label="Connector overview"
className="w-44 shrink-0 border-r px-4 py-4"
>
{overview.length > 0 && (
<div className="mb-5">
<p className="mb-2 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground/60">
Overview
</p>
<ul className="space-y-2">
{overview.map((item, i) => (
<li key={i} className="flex items-start gap-1.5">
<span
className="mt-1.5 size-1.5 shrink-0 rounded-full bg-muted-foreground/40"
aria-hidden
/>
<span className="text-xs leading-relaxed text-muted-foreground">
{item}
</span>
</li>
))}
</ul>
</div>
)}
{links.length > 0 && (
<div>
<p className="mb-2 text-[10px] font-semibold uppercase tracking-wider text-muted-foreground/60">
Links
</p>
<ul className="space-y-1.5">
{links.map((link, i) => {
const Icon = link.icon ?? ExternalLink;
return (
<li key={i}>
<a
href={link.href}
target="_blank"
rel="noopener noreferrer"
className="flex items-center gap-1.5 text-xs text-muted-foreground transition-colors hover:text-foreground"
>
<Icon className="size-3.5 shrink-0" aria-hidden />
{link.label}
</a>
</li>
);
})}
</ul>
</div>
)}
</aside>
{/* Tools column */}
<div className="flex min-w-0 flex-1 flex-col">
<div className="px-4 py-2.5">
<h2 className="text-xs font-semibold">Tools</h2>
</div>
<FilterBar
groups={toolGroups}
activeGroup={activeGroup}
onGroupChange={setActiveGroup}
query={query}
onQueryChange={setQuery}
/>
<div className="flex-1 overflow-y-auto">
{filteredGroups.length === 0 ? (
<p className="px-4 py-10 text-center text-xs text-muted-foreground">
No tools match your search.
</p>
) : (
filteredGroups.map((group) => (
<ToolGroupSection
key={group.id}
group={group}
onPermissionChange={handlePermissionChange}
onGroupAllow={handleGroupAllow}
/>
))
)}
</div>
</div>
</div>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Connector Panel
## Summary
A structured settings panel for connecting and configuring an external app or MCP server with an AI agent. It shows what the integration can do (overview bullets and links in a sidebar), lists every tool the integration exposes grouped by capability, and lets users set per-tool or per-group permission levels — Disable, Always ask, or Allow — without leaving the panel. The header carries the app identity (name, verified badge) and an Add connector CTA; a sidebar holds discovery content; the main column offers search and group filtering over the tool list.
## When to use
- When onboarding a new MCP server or reviewing an existing integration's permissions before activating it.
- When users need to browse what an integration can do and control exactly which tools it may run autonomously, run after confirmation, or never run.
- In an agent settings area, marketplace, or connector catalog — not inline in an agent chat transcript.
## When not to use
- For in-transcript per-call approval (one tool, one moment) — use Tool Approval instead. This panel manages standing permissions, not live prompts.
- As a generic settings form or feature-flag manager unrelated to agent tool permissions.
- When the integration exposes only one or two tools — a simple toggle row suffices; the full panel layout is only worth its overhead at five or more tools.
## Anatomy
- **Header**: app icon, name, verified badge (if publisher-verified), one-line description, "Add connector" CTA, close button.
- **Sidebar**: "Overview" section — a short bullet list of capabilities phrased from the user's perspective; "Links" section — anchor links to the app's website and documentation.
- **Filter bar**: Group filter dropdown (All + each group name) and a text search that matches on tool name or description.
- **Tool group section**: a collapsible label row showing the group name and a group-level "Allow" button that disappears once every tool in the group is allowed; below it, one tool row per tool.
- **Tool row**: tool name, protocol badge (e.g. "MCP"), description, and a three-way permission toggle (Disable / Always ask / Allow).
## Behavior
- Search immediately filters tool rows by name or description substring across all groups.
- The group dropdown constrains the visible groups; combining it with search narrows within that group.
- The group-level "Allow" button sets every tool in the group to Allow in one action.
- Per-tool permission is a mutually exclusive three-way toggle: only one of Disable, Always ask, Allow is active at a time.
- Groups are individually collapsible; collapsing hides tool rows without changing their permissions.
- The panel is layout-agnostic — it can be rendered as a modal (with a backdrop owned by the caller) or embedded directly in a settings page.
## Content guidelines
- Overview bullets phrase capabilities from the user's perspective: "Access deployment logs for debugging", not "Provides log access".
- Tool names match the tool's identifier exactly — no paraphrasing.
- Tool descriptions state what the tool does, not why the agent would use it ("Generate a temporary shareable link…", not "Useful for sharing protected pages").
- The verified badge appears only when the publisher's identity has been confirmed — don't use it as a general quality signal.
- Protocol badges ("MCP") are short, literal, and uppercased.
## Accessibility
- The permission toggle group for each tool uses `role="group"` with `aria-label` naming the tool ("Permission for Check domain availability").
- Each permission button exposes its active state via `aria-pressed`.
- The verified badge icon carries `aria-label="Verified"` so it's not invisible to screen readers.
- Group collapse buttons set `aria-expanded` to reflect the open/closed state.
- The group filter dropdown follows the listbox disclosure pattern: `aria-haspopup="listbox"`, `aria-expanded`, closes on Escape or outside click.
- The search input has `aria-label="Search tools"`.
## Related patterns
- Tool Approval — per-call in-context permission prompt; this panel manages standing permissions set before calls happen.
- Agent Triggers — similar two-column layout (sidebar overview + main content) for agent configuration.
Tool Call Chip
An inline pill naming an in-flight tool call that resolves into a result summary.
Searching "tailwind v4 changelog"
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { AlertCircle, Check, Code2, FileText, Globe, Loader2, Search } from "lucide-react";
import { cn } from "@/lib/utils";
const ICONS = {
search: Search,
file: FileText,
code: Code2,
network: Globe,
} as const;
export type ToolCallKind = keyof typeof ICONS;
export type ToolCallStatus = "running" | "success" | "error";
export interface ToolCallChipProps {
kind?: ToolCallKind;
verb: string;
target: string;
status: ToolCallStatus;
/** Replaces the verb + target label once status is "success" or "error". */
result?: string;
className?: string;
}
export function ToolCallChip({
kind = "search",
verb,
target,
status,
result,
className,
}: ToolCallChipProps) {
const Icon = ICONS[kind];
return (
<div
className={cn(
"inline-flex max-w-full items-center gap-2 rounded-full border bg-card px-3 py-1.5 text-xs",
className
)}
>
<Icon className="size-3.5 shrink-0 text-muted-foreground" aria-hidden />
<span aria-live="polite" className="min-w-0 flex-1 truncate">
{status === "running" ? (
<>
{verb} <span className="text-muted-foreground">"{target}"</span>
</>
) : (
(result ?? `${verb} "${target}"`)
)}
</span>
<AnimatePresence mode="wait" initial={false}>
<motion.span
key={status}
initial={{ opacity: 0, scale: 0.7 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.7 }}
transition={{ duration: 0.15 }}
className="shrink-0"
>
{status === "running" && (
<Loader2 className="size-3.5 animate-spin text-muted-foreground" aria-hidden />
)}
{status === "success" && (
<Check className="size-3.5 text-emerald-600 dark:text-emerald-400" aria-hidden />
)}
{status === "error" && <AlertCircle className="size-3.5 text-destructive" aria-hidden />}
</motion.span>
</AnimatePresence>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Tool Call Chip
## Summary
A compact inline pill shown while a specific, named tool call is in flight — a verb, its target, and a spinner — that resolves in place into a short result summary the instant the call finishes. Unlike the Thinking Loader's generic "the system is working" signal, this names the concrete action actually happening right now.
## When to use
- The agent is mid-call on a specific tool or function (a web search, a file read, a code execution, an API request) and the target is worth naming (the query, the filename, the endpoint).
- Inside an Expandable Trace or a message stream, as the live version of what becomes a completed step once resolved.
## When not to use
- For the overall "agent is working" state when no single tool call is active — use a Thinking Loader for that; don't invent a fake tool name to fill the gap.
- Stacked several deep for sub-steps of one logical call. One chip per call actually in flight — batch or fold finished ones into a trace instead of leaving a pile of chips on screen.
- When the target is sensitive and shouldn't be echoed verbatim (e.g. a raw credential) — summarize instead of printing it raw.
## Anatomy
- Icon: represents the tool's kind (search, file, code, network, ...).
- Label: a present-tense verb plus its target, e.g. `Searching "tailwind v4 changelog"`.
- State indicator: a small spinner while running; swaps to a check icon on success or an alert icon on failure.
- Resolved label: replaces the in-progress label with a brief result summary, e.g. `Searched — 4 results`.
## Behavior
- Appears the instant the call is dispatched — don't wait for a response to show that work has started.
- The target truncates with an ellipsis if it's long; never wraps to a second line.
- On completion, the spinner swaps to a check (or alert, on error) and the label updates to the result summary in the same chip — it does not get replaced by a new element.
- Once resolved, the chip stays visible as part of the record rather than vanishing; it commonly becomes one row of a subsequent Expandable Trace.
- Multiple sequential calls in one turn render as multiple chips in order, each independently transitioning from running to resolved.
## Content guidelines
- Verb + straight-quoted target, one line: `Reading "component.tsx"`, `Calling "get_weather"`.
- Keep the resolved summary equally short — a count or outcome, not a restatement of the whole result.
- Stay truthful: never show a tool name or target that doesn't match what's actually running.
## Accessibility
- Wrap the label and state indicator in an `aria-live="polite"` region so the running → resolved transition is announced.
- Don't rely on the spinner-to-check swap alone to signal completion — the label text change must carry the same meaning for non-visual users.
- Give the icon `aria-hidden` and let the text label carry the accessible name.
## Related patterns
- Thinking Loader is the generic counterpart for when no specific tool call is active.
- Expandable Trace is where a sequence of resolved chips typically ends up once a turn completes.
- Tool Approval is the gate that, when required, appears before a chip like this starts running.
Attachment Chip
A composer's file/image attachment tray with drag-drop, upload progress, and inline preview.
sunset-photo.png
2.3 MB
quarterl…inal-v2.pdf
793 KB
notes.txt
4 KB
archive.zip
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { AlertCircle, File, RotateCcw, Upload, X } from "lucide-react";
import { cn } from "@/lib/utils";
export interface Attachment {
id: string;
name: string;
size: number;
/** 0-100. Ignored once status is "done" or "error". */
progress: number;
status: "uploading" | "done" | "error";
previewUrl?: string;
}
export interface AttachmentTrayProps {
attachments: Attachment[];
onRemove?: (id: string) => void;
onRetry?: (id: string) => void;
onDropFiles?: (files: FileList) => void;
className?: string;
}
export function AttachmentTray({
attachments,
onRemove,
onRetry,
onDropFiles,
className,
}: AttachmentTrayProps) {
const [dragging, setDragging] = React.useState(false);
return (
<div
onDragOver={(e) => {
e.preventDefault();
setDragging(true);
}}
onDragLeave={() => setDragging(false)}
onDrop={(e) => {
e.preventDefault();
setDragging(false);
if (e.dataTransfer.files.length) onDropFiles?.(e.dataTransfer.files);
}}
className={cn("relative rounded-2xl border p-3", className)}
>
{dragging && (
<div className="pointer-events-none absolute inset-1 z-10 flex flex-col items-center justify-center gap-1.5 rounded-xl border-2 border-dashed border-foreground/30 bg-background/90 text-sm text-muted-foreground">
<Upload className="size-4" aria-hidden />
Drop to attach
</div>
)}
{attachments.length > 0 ? (
<ul className="flex gap-2 overflow-x-auto pb-1">
{attachments.map((attachment) => (
<AttachmentChip
key={attachment.id}
attachment={attachment}
onRemove={onRemove}
onRetry={onRetry}
/>
))}
</ul>
) : (
!dragging && (
<p className="text-sm text-muted-foreground">Drag files here, or use the attach button.</p>
)
)}
</div>
);
}
export function AttachmentChip({
attachment,
onRemove,
onRetry,
}: {
attachment: Attachment;
onRemove?: (id: string) => void;
onRetry?: (id: string) => void;
}) {
const { id, name, size, progress, status, previewUrl } = attachment;
const radius = 16;
const circumference = 2 * Math.PI * radius;
return (
<li
className={cn(
"relative flex w-40 shrink-0 items-center gap-2 rounded-xl border bg-card p-2",
status === "error" && "border-destructive/40 bg-destructive/5"
)}
>
<div
className="relative flex size-9 shrink-0 items-center justify-center"
{...(status === "uploading"
? { role: "progressbar", "aria-valuenow": progress, "aria-valuemin": 0, "aria-valuemax": 100, "aria-label": `Uploading ${name}` }
: {})}
>
{previewUrl ? (
// eslint-disable-next-line @next/next/no-img-element
<img src={previewUrl} alt="" className="size-9 rounded-lg object-cover" />
) : (
<span className="flex size-9 items-center justify-center rounded-lg bg-muted text-muted-foreground">
<File className="size-4" aria-hidden />
</span>
)}
{status === "uploading" && (
<svg width={36} height={36} className="absolute inset-0 -rotate-90" aria-hidden>
<circle cx={18} cy={18} r={radius} strokeWidth={2} className="stroke-background/70" fill="none" />
<motion.circle
cx={18}
cy={18}
r={radius}
strokeWidth={2}
strokeLinecap="round"
className="stroke-foreground"
fill="none"
strokeDasharray={circumference}
animate={{ strokeDashoffset: circumference * (1 - progress / 100) }}
transition={{ duration: 0.2 }}
/>
</svg>
)}
{status === "error" && (
<span className="absolute inset-0 flex items-center justify-center rounded-lg bg-destructive/10">
<AlertCircle className="size-4 text-destructive" aria-hidden />
</span>
)}
</div>
<div className="min-w-0 flex-1">
<p className="truncate text-xs font-medium">{truncateMiddle(name)}</p>
<p aria-live="polite" className="text-xs text-muted-foreground">
{status === "error" ? (
<button
type="button"
onClick={() => onRetry?.(id)}
className="inline-flex items-center gap-1 text-destructive hover:underline"
>
<RotateCcw className="size-3" aria-hidden /> Retry
</button>
) : (
formatBytes(size)
)}
</p>
</div>
<button
type="button"
onClick={() => onRemove?.(id)}
aria-label={`Remove ${name}`}
className="absolute -right-1.5 -top-1.5 flex size-4 items-center justify-center rounded-full border bg-background text-muted-foreground shadow-sm transition-colors hover:text-foreground"
>
<X className="size-2.5" aria-hidden />
</button>
</li>
);
}
function truncateMiddle(name: string, max = 20) {
if (name.length <= max) return name;
const dot = name.lastIndexOf(".");
const ext = dot > 0 ? name.slice(dot) : "";
const base = dot > 0 ? name.slice(0, dot) : name;
const keep = max - ext.length - 1;
if (keep <= 1) return `${name.slice(0, max - 1)}…`;
return `${base.slice(0, Math.ceil(keep / 2))}…${base.slice(-Math.floor(keep / 2))}${ext}`;
}
function formatBytes(bytes: number) {
if (bytes < 1024) return `${bytes} B`;
if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(0)} KB`;
return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Attachment Chip
## Summary
A compact chip representing one file or image attached to a composer — thumbnail or file-type icon, a circular progress ring while it uploads, and a remove control — laid out in a tray that also shows a drop-zone overlay while a file is dragged over it. It lets the user see exactly what's about to be sent, and back out of it, before the message goes.
## When to use
- Any composer that accepts file or image attachments and needs to show what's queued before the user sends.
- When uploads can take real time (large files, slow networks) and the user benefits from per-file progress instead of a single blocking spinner.
- Any time an attachment might fail and the user needs a way to retry or remove it without retyping their message.
## When not to use
- For attachments on a message that has already been sent — show those inline in the message itself, not as an in-progress chip.
- As a general file-manager UI. This is for the handful of items about to go out with one message, not for browsing or organizing a file library.
- When the host truly cannot support removing an in-flight upload — don't show a remove control that doesn't actually cancel anything.
## Anatomy
- Drop-zone overlay: a dashed-border highlight with a "Drop to attach" label that appears over the whole tray while a file is dragged over it.
- Chip: a thumbnail (for images) or a file-type icon, the filename, the file size, and a remove (×) button.
- Progress ring: a circular indicator over the thumbnail/icon while uploading; replaced by the plain thumbnail/icon once the upload completes.
- Error state: an alert tint and icon with an inline "Retry" affordance if the upload fails.
## Behavior
- Dragging a file over the composer shows the drop-zone overlay immediately; dropping it (or picking via an attach button) adds a chip right away in an uploading state, before the network call resolves.
- The progress ring fills as the upload progresses; if no real progress fraction is available, it spins indeterminately instead of freezing at 0.
- The remove button works at any stage — including mid-upload, where it also cancels the in-flight request.
- Multiple attachments lay out in a horizontal, scrollable row above the text input rather than stacking vertically and pushing the input down.
- On failure, the chip switches to its error state with a visible "Retry" rather than silently disappearing or failing the whole send.
## Content guidelines
- Truncate long filenames in the middle, keeping the extension visible, so `quarterly-report-final-v2.pdf` reads as `quarterly-…-v2.pdf`, not an unreadable prefix.
- Show file size once the upload starts, not before there's anything to report.
## Accessibility
- Always provide a file-picker button as an equivalent to drag-and-drop — drag-and-drop must never be the only way to attach a file.
- Expose upload progress as `role="progressbar"` with `aria-valuenow`, not through animation alone.
- Give each remove button a descriptive accessible name (`Remove quarterly-report.pdf`), not a bare "×".
## Related patterns
- Prompt Bar and Prompt Bar Pro are the composers this tray typically lives inside.
- Diff Summary is a similar "batch of items with per-item status" pattern for a different context (file edits instead of uploads).
Stop Generation Button
A send button that morphs into a stop control mid-stream and back on completion.
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { ArrowUp, Square } from "lucide-react";
import { cn } from "@/lib/utils";
export type GenerationState = "idle" | "generating";
export interface StopGenerationButtonProps {
state: GenerationState;
/** Disables the idle/send state (e.g. empty input). Ignored while generating — stopping is never blocked. */
disabled?: boolean;
onSubmit?: () => void;
onStop?: () => void;
className?: string;
}
export function StopGenerationButton({
state,
disabled = false,
onSubmit,
onStop,
className,
}: StopGenerationButtonProps) {
const generating = state === "generating";
return (
<motion.button
type="button"
layout
disabled={!generating && disabled}
onClick={generating ? onStop : onSubmit}
aria-label={generating ? "Stop generating" : "Send message"}
whileTap={{ scale: 0.92 }}
transition={{ layout: { duration: 0.18, ease: "easeOut" } }}
className={cn(
"flex size-8 shrink-0 items-center justify-center rounded-full bg-foreground text-background transition-colors disabled:bg-muted disabled:text-muted-foreground",
className
)}
>
<motion.span
key={generating ? "stop" : "send"}
initial={{ opacity: 0, scale: 0.6 }}
animate={{ opacity: 1, scale: 1 }}
transition={{ duration: 0.15 }}
className="flex items-center justify-center"
>
{generating ? <Square className="size-3 fill-current" /> : <ArrowUp className="size-4" />}
</motion.span>
</motion.button>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Stop Generation Button
## Summary
A composer's send control that morphs into a Stop button the instant generation begins, then morphs back the instant it ends — the same control across all three states (idle, generating, done) so the user's hand never has to find a different button to interrupt a response.
## When to use
- Any composer whose output streams over a real window of time (an LLM response, a long-running job) where the user may want to interrupt it mid-flight.
- As the one control that owns both "start" and "stop" for a single turn — never a second, separately-positioned cancel button.
## When not to use
- For actions that can't actually be interrupted — never show a Stop control that doesn't stop anything real; that's worse than no control at all.
- For near-instant responses with no meaningful in-flight window — the morph would flash and add noise instead of giving the user a real chance to act.
## Anatomy
- A single circular (or pill) icon button.
- Idle state: a send/arrow icon, disabled when the input is empty.
- Generating state: a solid stop-square icon, always enabled.
- The shape morphs between states with motion — not an abrupt icon swap — so it reads as the same control changing purpose, not a different button appearing.
## Behavior
- Clicking while idle (with input present) submits immediately and the button morphs to Stop before the first token of the response arrives — the transition is optimistic, not waiting on a server round-trip.
- Clicking while generating cancels the stream and the button morphs back to idle immediately, without an intermediate loading state on the click itself.
- Disabled only in the idle state with empty input; always interactive while generating, since stopping should never be blocked.
- The morph plays every transition, including generating → idle on natural completion, so a finished response and a user-cancelled one both land back on the same recognizable send affordance.
## Content guidelines
- Icon-only is standard; if a label is shown alongside, it swaps in lockstep with the icon ("Send" / "Stop") rather than staying static.
## Accessibility
- `aria-label` updates with state ("Send message" / "Stop generating") so assistive tech announces the button's current purpose, not just its icon.
- Remains a real, focusable, keyboard-operable button (Enter/Space) in every state.
- Disabled state uses the `disabled` attribute, not opacity alone, so it's programmatically detectable.
## Related patterns
- Thinking Loader is the passive "still working" indicator that typically appears alongside this button — this control is what lets the user act on that same in-progress window.
Terminal Stream
An auto-scrolling, collapsible panel streaming raw command output line by line.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { ArrowDown, Check, ChevronDown, CircleDot, Terminal, X } from "lucide-react";
import { cn } from "@/lib/utils";
export interface LogLine {
id: string;
text: string;
level?: "default" | "info" | "warn" | "error" | "success";
}
export type TerminalStatus = "running" | "done" | "error";
export interface TerminalStreamProps {
command: string;
lines: LogLine[];
status: TerminalStatus;
defaultOpen?: boolean;
className?: string;
}
const LEVEL_CLASS: Record<NonNullable<LogLine["level"]>, string> = {
default: "text-neutral-300",
info: "text-sky-400",
warn: "text-amber-400",
error: "text-red-400",
success: "text-emerald-400",
};
export function TerminalStream({
command,
lines,
status,
defaultOpen = true,
className,
}: TerminalStreamProps) {
const [open, setOpen] = React.useState(defaultOpen);
const [pinnedToBottom, setPinnedToBottom] = React.useState(true);
const bodyRef = React.useRef<HTMLDivElement>(null);
React.useEffect(() => {
if (!open || !pinnedToBottom) return;
const el = bodyRef.current;
if (el) el.scrollTop = el.scrollHeight;
}, [lines, open, pinnedToBottom]);
function handleScroll() {
const el = bodyRef.current;
if (!el) return;
const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
setPinnedToBottom(atBottom);
}
function jumpToLatest() {
const el = bodyRef.current;
if (el) el.scrollTop = el.scrollHeight;
setPinnedToBottom(true);
}
return (
<div
className={cn(
"w-full overflow-hidden rounded-xl border border-neutral-800 bg-neutral-950 text-neutral-50",
className
)}
>
<button
type="button"
onClick={() => setOpen((v) => !v)}
aria-expanded={open}
className="flex w-full items-center gap-2 px-3.5 py-2.5 text-left text-sm"
>
<Terminal className="size-3.5 shrink-0 text-neutral-400" aria-hidden />
<span className="min-w-0 flex-1 truncate font-mono text-xs text-neutral-200">{command}</span>
<StatusBadge status={status} />
<span className="text-xs text-neutral-500">{lines.length}</span>
<ChevronDown
className={cn("size-4 shrink-0 text-neutral-500 transition-transform", open && "rotate-180")}
/>
</button>
<AnimatePresence initial={false}>
{open && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2, ease: "easeInOut" }}
className="relative overflow-hidden"
>
<div
ref={bodyRef}
onScroll={handleScroll}
role="log"
aria-live={status === "running" ? "polite" : "off"}
className="max-h-64 overflow-y-auto px-3.5 py-2.5 font-mono text-xs leading-relaxed"
>
{lines.map((line) => (
<p key={line.id} className={LEVEL_CLASS[line.level ?? "default"]}>
{line.text}
</p>
))}
{status === "running" && <BlinkingCursor />}
</div>
{!pinnedToBottom && (
<button
type="button"
onClick={jumpToLatest}
className="absolute bottom-2.5 left-1/2 flex -translate-x-1/2 items-center gap-1 rounded-full bg-neutral-800 px-2.5 py-1 text-xs text-neutral-200 shadow-sm transition-colors hover:bg-neutral-700"
>
<ArrowDown className="size-3" aria-hidden /> Jump to latest
</button>
)}
</motion.div>
)}
</AnimatePresence>
</div>
);
}
function StatusBadge({ status }: { status: TerminalStatus }) {
if (status === "running") {
return <CircleDot className="size-3.5 shrink-0 animate-pulse text-amber-400" aria-label="Running" />;
}
if (status === "error") {
return <X className="size-3.5 shrink-0 text-red-400" aria-label="Failed" />;
}
return <Check className="size-3.5 shrink-0 text-emerald-400" aria-label="Done" />;
}
function BlinkingCursor() {
return (
<motion.span
aria-hidden
className="inline-block h-3 w-[6px] translate-y-px bg-neutral-400"
animate={{ opacity: [1, 1, 0, 0] }}
transition={{ duration: 1, repeat: Infinity, times: [0, 0.5, 0.5, 1], ease: "linear" }}
/>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Terminal Stream
## Summary
An auto-scrolling, collapsible panel that streams a command's raw output line by line, tinted by level (info, warning, error, success) — the closest thing in the catalogue to a real terminal, for when the full, unstructured output of a running process is worth showing.
## When to use
- An agent or tool is executing a shell command, build, test run, or deploy, and its raw output has real value beyond "it succeeded" (debugging a failure, watching a long build).
- The user should be able to collapse it out of the way once they trust it's just noise, without losing the output entirely.
## When not to use
- For a single tool call's status with no meaningful line-by-line output — use a Tool Call Chip instead.
- For output that's actually structured data (a diff, a table, a list of files) — render it as that shape (e.g. Diff Summary) rather than flattening it into log lines.
- As a permanent, always-expanded fixture once the command is long done — let it collapse to a compact header so it doesn't dominate the surrounding content.
## Anatomy
- Header bar: a terminal icon, the command itself (monospace), a status indicator (running / done / error), a line count, and a collapse toggle.
- Log body: monospace lines, each tinted by level — default, info, warning, error, success.
- A blinking cursor at the tail while still streaming.
- A "Jump to latest" pill that appears only when the user has scrolled away from the bottom during an active stream.
## Behavior
- New lines append at the bottom and the panel auto-scrolls to keep the latest line in view, as long as the user hasn't manually scrolled up.
- Scrolling up during an active stream pauses auto-scroll and reveals "Jump to latest"; clicking it snaps back to the bottom and resumes auto-scroll.
- Collapsing hides the log body but keeps the header — including a live line count and status — visible; output keeps accumulating in the background while collapsed.
- On completion, the header's status swaps to done or error; the log itself is never cleared or replaced, so scrollback stays available.
## Content guidelines
- Tint lines by their actual level — don't invent color meaning for lines that are all the same kind of output.
- The header shows the literal command, not a paraphrase or summary of what it does.
## Accessibility
- The log region is a live region only while actively streaming and expanded (`aria-live="polite"`) — throttle or batch announcements for high-volume output rather than announcing every line.
- The collapse toggle exposes `aria-expanded`.
- The log body is a real scrollable, focusable region reachable and operable by keyboard, not just by mouse drag.
- Status is conveyed by icon and text together, never color alone.
## Related patterns
- Tool Call Chip is the compact, single-call counterpart — reach for this pattern once that call's full output actually matters.
- Diff Summary is the finished-state counterpart specifically for file-edit output, once raw log lines aren't the right shape anymore.
Inline Citation
A hoverable, clickable footnote-style source marker inline within text.
Tailwind v4 moved its configuration into CSS itself, dropping the old tailwind.config.js file entirely. Motion, formerly Framer Motion, now ships a smaller core bundle aimed specifically at this kind of micro-interaction.
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { AnimatePresence, motion } from "motion/react";
import { cn } from "@/lib/utils";
export interface CitationSource {
title: string;
domain: string;
snippet?: string;
url: string;
}
export interface InlineCitationProps {
index: number;
source: CitationSource;
className?: string;
}
const POPOVER_WIDTH = 256;
const MARGIN = 8;
interface Position {
top: number;
left: number;
placement: "top" | "bottom";
}
export function InlineCitation({ index, source, className }: InlineCitationProps) {
const [open, setOpen] = React.useState(false);
const [position, setPosition] = React.useState<Position | null>(null);
const mounted = useMounted();
const triggerRef = React.useRef<HTMLButtonElement>(null);
const popoverRef = React.useRef<HTMLDivElement>(null);
const popoverId = React.useId();
const reposition = React.useCallback(() => {
const rect = triggerRef.current?.getBoundingClientRect();
if (!rect) return;
const placement: Position["placement"] = rect.top > 180 ? "top" : "bottom";
const left = Math.min(
Math.max(rect.left + rect.width / 2, POPOVER_WIDTH / 2 + MARGIN),
window.innerWidth - POPOVER_WIDTH / 2 - MARGIN
);
setPosition({ top: placement === "top" ? rect.top : rect.bottom, left, placement });
}, []);
function show() {
reposition();
setOpen(true);
}
React.useEffect(() => {
if (!open) return;
function handlePointerDown(e: MouseEvent) {
const target = e.target as Node;
if (triggerRef.current?.contains(target) || popoverRef.current?.contains(target)) return;
setOpen(false);
}
function handleKey(e: KeyboardEvent) {
if (e.key === "Escape") setOpen(false);
}
document.addEventListener("mousedown", handlePointerDown);
document.addEventListener("keydown", handleKey);
window.addEventListener("scroll", reposition, true);
window.addEventListener("resize", reposition);
return () => {
document.removeEventListener("mousedown", handlePointerDown);
document.removeEventListener("keydown", handleKey);
window.removeEventListener("scroll", reposition, true);
window.removeEventListener("resize", reposition);
};
}, [open, reposition]);
return (
<>
<button
ref={triggerRef}
type="button"
aria-describedby={open ? popoverId : undefined}
aria-expanded={open}
onMouseEnter={show}
onMouseLeave={() => setOpen(false)}
onFocus={show}
onBlur={() => setOpen(false)}
onClick={() => (open ? setOpen(false) : show())}
className={cn(
"mx-0.5 inline-flex size-4 -translate-y-1.5 items-center justify-center rounded-full bg-muted align-super text-[10px] font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground",
className
)}
>
{index}
</button>
{mounted &&
createPortal(
<AnimatePresence>
{open && position && (
// Positioning lives on this plain element, not the motion.div below — Motion owns the
// `transform` style for its own x/y animation, so a hand-written translate() here would
// get silently overwritten by it.
<div
ref={popoverRef}
style={{
position: "fixed",
top: position.top,
left: position.left,
width: POPOVER_WIDTH,
transform:
position.placement === "top"
? `translate(-50%, calc(-100% - ${MARGIN}px))`
: `translate(-50%, ${MARGIN}px)`,
}}
className="z-50"
>
<motion.div
id={popoverId}
role="tooltip"
initial={{ opacity: 0, y: position.placement === "top" ? 4 : -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: position.placement === "top" ? 4 : -4 }}
transition={{ duration: 0.12 }}
className="rounded-xl border bg-popover p-3 text-left shadow-md"
>
<a
href={source.url}
target="_blank"
rel="noreferrer"
className="block text-sm font-medium text-foreground hover:underline"
>
{source.title}
</a>
<p className="mt-0.5 text-xs text-muted-foreground">{source.domain}</p>
{source.snippet && <p className="mt-1.5 text-xs text-foreground/80">{source.snippet}</p>}
</motion.div>
</div>
)}
</AnimatePresence>,
document.body
)}
</>
);
}
/** True only once the client has rendered — lets a portal target `document.body` without an SSR mismatch. */
function useMounted() {
return React.useSyncExternalStore(
() => () => {},
() => true,
() => false
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Inline Citation
## Summary
A small, numbered footnote-style marker set right after a specific claim in the text, that reveals its source — title, domain, a short snippet, and a link out — on hover or click, without breaking the reader's flow. It's the claim-level counterpart to a general "here's what I searched" indicator.
## When to use
- A specific sentence or clause in the answer is backed by a specific source, and the user may want to verify it without leaving the page or scrolling to a source list.
- Any streamed or static answer that cites multiple distinct sources for different claims, where a single end-of-answer source list would lose the claim-to-source mapping.
## When not to use
- For a blanket "this response used web search" signal with no specific claim attached — that belongs in the answer's own inline source chip (see Related), not a numbered footnote.
- On nearly every sentence. Citing everything turns the text into a wall of superscripts and trains the user to stop noticing them — reserve this for claims that actually need backing.
- As the only way to see all sources at once — pair it with a full source list when the user wants the complete picture, this marker is for in-context verification of one claim.
## Anatomy
- Marker: a small raised numeral (or a compact icon + numeral), inline immediately after the clause it supports.
- Popover: source title, domain/favicon, a one-line snippet, and a link to open the source.
- Multiple citations on one clause render as adjacent numerals, each independently triggerable — never merged into a single marker.
## Behavior
- Hovering or focusing the marker opens the popover; it closes on mouse-leave/blur, on Escape, or on an outside click.
- On touch devices, where hover doesn't apply, tapping the marker opens the popover; tapping again or tapping outside closes it.
- The popover repositions to stay on-screen near a viewport edge (flips above/below or left/right as needed) rather than clipping.
- Numerals count up in the order sources first appear in the text, not alphabetically or by source importance.
## Content guidelines
- The snippet is a short excerpt that supports the specific claim, not the whole source page.
- Marker numerals are literal reference numbers, not a rating or confidence score — don't overload their meaning.
## Accessibility
- The marker is a real focusable element (`<button>` or `<a>`), never a styled, non-interactive `<span>`.
- The popover content is associated via `aria-describedby` (or an equivalent live association), so assistive tech can reach it from the marker.
- Never rely on hover alone — keyboard focus and touch tap must open the same popover.
## Related patterns
- Streaming Text's inline source chip is the word-level "this came from a search" signal; Inline Citation is the claim-level footnote built on top of a specific source.
Sources Stack
An overlapping stack of source favicons with a count, expanding into a linked source list.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { ChevronDown, ExternalLink, Globe } from "lucide-react";
import { cn } from "@/lib/utils";
export interface Source {
title: string;
domain: string;
url: string;
/** Falls back to a globe icon when omitted or when the image fails to load. */
faviconUrl?: string;
}
export interface SourcesStackProps {
sources: Source[];
/** How many favicons render in the collapsed stack before folding into the count. */
visibleCount?: number;
defaultOpen?: boolean;
className?: string;
}
export function SourcesStack({
sources,
visibleCount = 3,
defaultOpen = false,
className,
}: SourcesStackProps) {
const [open, setOpen] = React.useState(defaultOpen);
const listId = React.useId();
const stacked = sources.slice(0, visibleCount);
return (
<div className={cn("w-full max-w-xs", className)}>
<button
type="button"
onClick={() => setOpen((v) => !v)}
aria-expanded={open}
aria-controls={listId}
className="flex w-full items-center gap-2 rounded-full py-1.5 pl-1.5 pr-3 transition-colors hover:bg-accent/50"
>
<span aria-hidden className="flex -space-x-2">
{stacked.map((source, i) => (
<Favicon key={source.url} source={source} style={{ zIndex: stacked.length - i }} />
))}
</span>
<span className="text-xs text-muted-foreground">
{sources.length} source{sources.length === 1 ? "" : "s"}
</span>
<ChevronDown
className={cn(
"size-3.5 shrink-0 text-muted-foreground transition-transform duration-200",
open && "rotate-180"
)}
/>
</button>
<AnimatePresence initial={false}>
{open && (
<motion.ul
id={listId}
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2, ease: "easeInOut" }}
className="mt-1.5 overflow-hidden rounded-xl border bg-popover"
>
{sources.map((source) => (
<li key={source.url} className="border-b last:border-b-0">
<a
href={source.url}
target="_blank"
rel="noreferrer"
className="flex items-center gap-2.5 px-3 py-2 transition-colors hover:bg-accent/50"
>
<Favicon source={source} />
<span className="min-w-0 flex-1">
<span className="block truncate text-sm text-foreground/90">{source.title}</span>
<span className="block truncate text-xs text-muted-foreground">{source.domain}</span>
</span>
<ExternalLink className="size-3.5 shrink-0 text-muted-foreground" aria-hidden />
</a>
</li>
))}
</motion.ul>
)}
</AnimatePresence>
</div>
);
}
function Favicon({ source, style }: { source: Source; style?: React.CSSProperties }) {
const [errored, setErrored] = React.useState(false);
const showImage = source.faviconUrl && !errored;
return (
<span
style={style}
className="relative flex size-5 shrink-0 items-center justify-center overflow-hidden rounded-full border-2 border-background bg-muted"
>
{showImage ? (
// eslint-disable-next-line @next/next/no-img-element
<img src={source.faviconUrl} alt="" className="size-full object-cover" onError={() => setErrored(true)} />
) : (
<Globe className="size-2.5 text-muted-foreground" aria-hidden />
)}
</span>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Sources Stack
## Summary
A compact "N sources" pill showing overlapping favicons for the sources behind an answer, which expands in place into a linked list of every source. It's the answer-level counterpart to Inline Citation's claim-level footnote — one glance at the total, one tap for the full list.
## When to use
- Summarizing all the sources an answer drew on, in a single, low-footprint control rather than a dedicated section that always takes up space.
- The exact source count and provenance (which domains) matter to the user's trust in the answer, but the individual claim-to-source mapping doesn't need to be shown inline.
- After a research or search-heavy answer where listing every source inline (via Inline Citation) would be excessive, but omitting sources entirely would undersell the work done.
## When not to use
- When a specific sentence needs to point at a specific source — use Inline Citation for that claim-level link; this pattern only summarizes the whole set.
- For a single source. A stack implies plural; one source reads better as a plain link or a single favicon + domain label.
- As a replacement for inline citations in a long, multi-claim answer — pair the two rather than picking one over the other.
## Anatomy
- Collapsed trigger: a pill with a stack of overlapping favicons (2-3 visible, each ringed to separate it from the one behind) followed by the total count ("7 sources") and a chevron.
- Expanded list: one row per source, each with its favicon, title, domain, and an external-link affordance, opening in a new tab.
## Behavior
- Clicking the pill toggles the list open/closed in place, pushing surrounding content rather than overlaying it.
- The favicon stack always shows the same leading few sources regardless of how many are open in the list — it's a preview, not a paginated view.
- A source with no reachable favicon falls back to a generic globe icon rather than a broken image.
- The chevron rotates to reflect open/closed state; the transition animates height, not just opacity, so surrounding layout doesn't jump.
## Content guidelines
- Titles are the source's own page title, not a paraphrase; domains are the bare hostname, no protocol or path.
- Order sources by relevance or citation order, not alphabetically — the first favicon in the stack should be the most load-bearing source.
## Accessibility
- The trigger is a real `<button>` with `aria-expanded` and `aria-controls` pointing at the list.
- The favicon stack in the collapsed trigger is decorative (`aria-hidden`) since the count text already states how many sources there are.
- Each expanded row is a real `<a>` to the source, reachable and activatable by keyboard alone.
## Related patterns
- Inline Citation is the claim-level counterpart — a numbered marker tied to one sentence, versus this pattern's answer-level summary of every source used.
Source Trust Card
A paginated single-source card with a trust badge and domain pills for jumping between sources.
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { AnimatePresence, motion } from "motion/react";
import { ChevronLeft, ChevronRight, Globe, ShieldCheck } from "lucide-react";
import { cn } from "@/lib/utils";
export interface TrustedSource {
title: string;
domain: string;
description: string;
url: string;
/** Falls back to a globe icon when omitted or when the image fails to load. */
faviconUrl?: string;
/** Shows a "Trusted" badge; hovering or focusing it reveals why the source is trusted. */
trustReason?: string;
}
export interface SourceTrustCardProps {
sources: TrustedSource[];
defaultIndex?: number;
className?: string;
}
export function SourceTrustCard({ sources, defaultIndex = 0, className }: SourceTrustCardProps) {
const [index, setIndex] = React.useState(defaultIndex);
const [direction, setDirection] = React.useState(0);
const source = sources[index];
function go(delta: number) {
setDirection(delta);
setIndex((i) => (i + delta + sources.length) % sources.length);
}
function goTo(i: number) {
setDirection(i > index ? 1 : -1);
setIndex(i);
}
return (
<div className={cn("w-full max-w-sm overflow-hidden rounded-2xl border bg-card shadow-sm", className)}>
<div className="flex items-center justify-between border-b px-3 py-2">
<div className="flex items-center gap-1">
<button
type="button"
onClick={() => go(-1)}
disabled={sources.length < 2}
aria-label="Previous source"
className="rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
>
<ChevronLeft className="size-4" />
</button>
<span className="min-w-[3ch] text-center text-xs tabular-nums text-muted-foreground">
{index + 1}/{sources.length}
</span>
<button
type="button"
onClick={() => go(1)}
disabled={sources.length < 2}
aria-label="Next source"
className="rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
>
<ChevronRight className="size-4" />
</button>
</div>
<span className="text-xs text-muted-foreground">
{sources.length} source{sources.length === 1 ? "" : "s"}
</span>
</div>
<div className="relative overflow-hidden">
<AnimatePresence mode="popLayout" initial={false}>
<motion.div
key={index}
initial={{ x: direction >= 0 ? 24 : -24, opacity: 0 }}
animate={{ x: 0, opacity: 1 }}
exit={{ x: direction >= 0 ? -24 : 24, opacity: 0 }}
transition={{ duration: 0.2, ease: "easeInOut" }}
className="p-3"
>
<div className="relative">
<a
href={source.url}
target="_blank"
rel="noreferrer"
className="-m-1 flex items-start gap-2.5 rounded-lg p-1 transition-colors hover:bg-accent/50"
>
<Favicon source={source} />
<span className="min-w-0 flex-1">
<span className={cn("block truncate text-xs text-muted-foreground", source.trustReason && "pr-16")}>
{source.domain}
</span>
<span className="mt-0.5 block line-clamp-2 text-sm font-medium leading-snug text-foreground">
{source.title}
</span>
<span className="mt-1 block line-clamp-2 text-xs leading-relaxed text-muted-foreground">
{source.description}
</span>
</span>
</a>
{source.trustReason && (
<TrustBadge domain={source.domain} reason={source.trustReason} url={source.url} />
)}
</div>
</motion.div>
</AnimatePresence>
</div>
{sources.length > 1 && (
<div className="flex flex-wrap gap-1.5 border-t px-3 py-2">
{sources.map((s, i) => (
<button
key={s.url}
type="button"
onClick={() => goTo(i)}
aria-current={i === index}
className={cn(
"rounded-full border px-2 py-0.5 text-xs transition-colors",
i === index
? "border-primary/30 bg-primary/10 text-foreground"
: "border-transparent bg-muted text-muted-foreground hover:bg-accent"
)}
>
{s.domain}
</button>
))}
</div>
)}
</div>
);
}
function Favicon({ source }: { source: TrustedSource }) {
const [errored, setErrored] = React.useState(false);
const showImage = source.faviconUrl && !errored;
return (
<span className="relative flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-full border bg-muted">
{showImage ? (
// eslint-disable-next-line @next/next/no-img-element
<img src={source.faviconUrl} alt="" className="size-full object-cover" onError={() => setErrored(true)} />
) : (
<Globe className="size-4 text-muted-foreground" aria-hidden />
)}
</span>
);
}
const TOOLTIP_WIDTH = 224;
const MARGIN = 8;
interface Position {
top: number;
left: number;
placement: "top" | "bottom";
}
function TrustBadge({ domain, reason, url }: { domain: string; reason: string; url: string }) {
const [open, setOpen] = React.useState(false);
const [position, setPosition] = React.useState<Position | null>(null);
const mounted = useMounted();
const triggerRef = React.useRef<HTMLButtonElement>(null);
const tooltipRef = React.useRef<HTMLDivElement>(null);
const tooltipId = React.useId();
const reposition = React.useCallback(() => {
const rect = triggerRef.current?.getBoundingClientRect();
if (!rect) return;
const placement: Position["placement"] = rect.top > 140 ? "top" : "bottom";
const left = Math.min(
Math.max(rect.right, TOOLTIP_WIDTH + MARGIN),
window.innerWidth - MARGIN
);
setPosition({ top: placement === "top" ? rect.top - MARGIN : rect.bottom + MARGIN, left, placement });
}, []);
function show() {
reposition();
setOpen(true);
}
function hide() {
setOpen(false);
}
React.useEffect(() => {
if (!open) return;
function handleKey(e: KeyboardEvent) {
if (e.key === "Escape") setOpen(false);
}
document.addEventListener("keydown", handleKey);
window.addEventListener("scroll", reposition, true);
window.addEventListener("resize", reposition);
return () => {
document.removeEventListener("keydown", handleKey);
window.removeEventListener("scroll", reposition, true);
window.removeEventListener("resize", reposition);
};
}, [open, reposition]);
return (
<>
<button
ref={triggerRef}
type="button"
aria-describedby={open ? tooltipId : undefined}
aria-expanded={open}
onMouseEnter={show}
onMouseLeave={hide}
onFocus={show}
onBlur={hide}
className="absolute right-0 top-0 inline-flex items-center gap-1 rounded-full border border-emerald-600/30 bg-emerald-50 px-1.5 py-0.5 text-[10px] font-medium text-emerald-700 transition-colors hover:bg-emerald-100 dark:bg-emerald-950/40 dark:text-emerald-400 dark:hover:bg-emerald-950/70"
>
<ShieldCheck className="size-3" aria-hidden />
Trusted
</button>
{mounted &&
createPortal(
<AnimatePresence>
{open && position && (
<div
ref={tooltipRef}
style={{
position: "fixed",
top: position.top,
left: position.left,
width: TOOLTIP_WIDTH,
transform:
position.placement === "top"
? `translate(-100%, -100%)`
: `translate(-100%, 0)`,
}}
className="z-50"
>
<motion.div
id={tooltipId}
role="tooltip"
initial={{ opacity: 0, y: position.placement === "top" ? 4 : -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: position.placement === "top" ? 4 : -4 }}
transition={{ duration: 0.12 }}
className="rounded-xl border bg-popover p-3 text-left shadow-md"
>
<div className="flex items-center gap-1.5 text-xs font-medium text-foreground">
<ShieldCheck className="size-3.5 text-emerald-600 dark:text-emerald-400" aria-hidden />
Trusted
</div>
<p className="mt-1 text-xs leading-relaxed text-muted-foreground">
<span className="font-medium text-foreground/80">{domain}</span> {reason}
</p>
<a
href={url}
target="_blank"
rel="noreferrer"
className="mt-1.5 inline-block text-xs font-medium text-primary hover:underline"
>
Learn more
</a>
</motion.div>
</div>
)}
</AnimatePresence>,
document.body
)}
</>
);
}
/** True only once the client has rendered — lets a portal target `document.body` without an SSR mismatch. */
function useMounted() {
return React.useSyncExternalStore(
() => () => {},
() => true,
() => false
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Source Trust Card
## Summary
A paginated card for a single cited source, showing its favicon, title, and
snippet, plus an optional "Trusted" badge that reveals why the source is
credible on hover. A row of domain pills below lets the reader jump
straight to any source in the set.
## When to use
- An AI answer cites a small set of web sources (roughly 2–6) and the
reader may want to inspect each one before trusting the answer.
- At least one source benefits from an explicit credibility signal — an
official vendor site, a government domain, a well-known registrar or
standards body — where "why should I trust this" isn't obvious from the
domain alone.
- The reader is likely to check sources one at a time rather than scan
them all at once (contrast with a list or stack view).
## When not to use
- A single source — show it inline or as a plain link; pagination chrome
for one item is dead weight.
- More than ~6–8 sources — pagination through a long set is tedious; use
`Sources Stack` (an expandable list) instead.
- Every source is equally low-stakes and none needs a trust explanation —
a plain source list is lighter and just as useful.
- Inline, mid-sentence citation markers — use `Inline Citation` for that;
this pattern is a standalone card, not a footnote.
## Anatomy
- Header: previous/next controls, a "current/total" counter, and a
"N sources" label.
- Source body (clickable, opens the source): favicon, domain, title,
short description/snippet.
- Trust badge (optional, only when a source is verified): a small shield
icon + "Trusted" pill pinned above the domain; hovering or focusing it
reveals a tooltip with one sentence explaining why, and a "Learn more"
link.
- Domain pill row (only when there's more than one source): one pill per
source for direct navigation; the active pill is visually distinct.
## Behavior
- Previous/next buttons cycle through sources with a short slide + fade
transition in the direction of travel; wrap around at the ends.
- Clicking a domain pill jumps directly to that source, sliding in the
correct direction (forward if later in the set, backward if earlier).
- The whole source body (favicon, title, description) is a single link
that opens the source in a new tab; the trust badge sits outside that
link so it can be hovered or focused independently.
- The trust badge only renders when the current source has a trust
reason — most sources in a set will not have one, and that's expected.
It stays collapsed to the "Trusted" pill until hovered or focused, so it
never pushes the card's height around.
- The tooltip opens on hover or keyboard focus, closes on mouse leave,
blur, or Escape, and flips above or below the badge depending on
available viewport space.
- Favicon falls back to a generic globe icon if the image is missing or
fails to load.
## Content guidelines
- Title: the source's actual page title, truncated rather than rewritten.
- Description: a one- to two-line snippet in the source's own voice, not
editorial commentary.
- Trust reason: one short sentence stating the concrete basis for trust
(e.g. "is trusted for official domain registration... from a U.S.
provider"), not a vague "this is a good source."
- Domain pills show the bare domain (`cloudflare.com`), not the full title.
## Accessibility
- Previous/next buttons need accessible names ("Previous source" / "Next
source"), not just chevron icons.
- The counter and "N sources" text give screen reader users the set size
and position without relying on the visual pagination alone.
- Domain pills use `aria-current` on the active source so assistive tech
can tell which one is showing.
- The trust badge is a real `button`, reachable by keyboard: focusing it
opens the tooltip the same way hovering does, and the tooltip is linked
back to the badge with `aria-describedby` so screen readers announce it.
- Respect `prefers-reduced-motion`: reduce or remove the slide transition
between sources and the tooltip's fade-in.
## Related patterns
- `Sources Stack` — better for larger sets browsed as a single list
rather than one at a time.
- `Inline Citation` — for footnote-style markers inside response text,
rather than a standalone card.
Follow-Up List
A vertical list of suggested next questions shown after a response, each sendable with a tap.
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { CornerDownRight } from "lucide-react";
import { cn } from "@/lib/utils";
export interface FollowUpListProps {
suggestions: string[];
onSelect?: (suggestion: string) => void;
className?: string;
}
export function FollowUpList({ suggestions, onSelect, className }: FollowUpListProps) {
if (suggestions.length === 0) return null;
return (
<ul className={cn("flex w-full max-w-md flex-col", className)}>
{suggestions.map((suggestion, i) => (
<motion.li
key={suggestion}
initial={{ opacity: 0, y: 4 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.2, delay: i * 0.05 }}
>
<button
type="button"
onClick={() => onSelect?.(suggestion)}
className="group flex w-full items-center gap-2.5 border-b py-3 text-left last:border-b-0"
>
<CornerDownRight className="size-3.5 shrink-0 text-muted-foreground" aria-hidden />
<span className="flex-1 text-sm text-foreground/90 transition-colors group-hover:text-foreground">
{suggestion}
</span>
</button>
</motion.li>
))}
</ul>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Follow-Up List
## Summary
A vertical list of suggested next questions shown after an assistant response, each one a full-width row a user can tap to send as their next message. It turns "what else could I ask?" into a menu instead of a blank composer.
## When to use
- After a response where the model can anticipate a handful of natural next questions (a docs answer, a research summary, a completed task) and surfacing them saves the user from typing.
- When the suggestions themselves carry information worth reading in full — multi-clause or slightly long questions that would wrap awkwardly as chips.
- As the primary next action after a response, when there isn't already a busy row of inline actions (copy, thumbs, share) competing for the same space.
## When not to use
- When suggestions are short, single-topic phrases meant to sit alongside other inline actions (copy, regenerate) — use compact wrapping chips instead, so the row stays low-footprint.
- Immediately after every single message in a fast back-and-forth chat — it adds visual weight the user will mostly skip past; reserve it for points where the conversation could naturally branch.
- When there's only one sensible follow-up — a single suggestion reads better as an inline link or a one-line prompt, not a list.
## Anatomy
- A vertical stack of rows, each with a leading "corner-down-right" arrow icon (echoing "this leads to a reply") and the suggestion text.
- A hairline divider between rows; no divider after the last row.
- No container border or background — the list sits directly under the response it follows, reading as part of that turn rather than a separate card.
## Behavior
- Rows animate in with a slight upward fade, staggered a beat apart, so the list doesn't slam onto the screen the instant the response finishes.
- Clicking a row sends that suggestion as the user's next message immediately — it is not a two-step "fill the composer, then let the user edit" interaction.
- Rows appear only once the response they follow has finished streaming, never while it's still generating.
## Content guidelines
- Write suggestions as full first-person questions the user could ask verbatim ("How do I migrate historical data if I switch from Google Analytics"), not fragments or topic labels.
- Keep the list short — three to five suggestions. More than that stops being a quick scan and starts being a list to read.
- Order by how likely the user is to want it next, not alphabetically or by topic grouping.
## Accessibility
- Each row is a real `<button>` inside a `<ul>`/`<li>`, reachable and activatable by keyboard alone.
- The leading icon is decorative (`aria-hidden`) — the row's accessible name comes from the suggestion text alone.
- Rows are large tap targets (full-width, generous vertical padding) so the pattern works as well on touch as with a pointer.
## Related patterns
- Streaming Text's `followUps` chips are the compact counterpart — short, wrapping suggestions that sit inline with other post-response actions rather than as their own list.
Selection Actions
A floating toolbar on text selection for describing edits, explaining, or improving a passage.
Turn on the thinking loader the moment the agent starts a step, and keep it up until the trace is fully ready to show so users never sit through a blank pause.
Highlight a passage above to try Explain, Improve, or a custom edit.
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { AnimatePresence, motion } from "motion/react";
import { Check, ChevronRight, CircleHelp, Loader2, RotateCcw, Sparkles, X } from "lucide-react";
import { cn } from "@/lib/utils";
export interface SelectionActionsProps {
text: string;
onExplain?: (selection: string) => string | Promise<string>;
onRewrite: (selection: string, instruction: string) => string | Promise<string>;
className?: string;
}
const QUICK_EDITS = ["Fix grammar", "Shorten", "Make more formal"];
const TOOLBAR_WIDTH = 320;
const REVIEW_WIDTH = 200;
const MARGIN = 8;
const DEFAULT_INSTRUCTION = "Improve the clarity and flow of this passage.";
interface Anchor {
top: number;
bottom: number;
left: number;
}
interface Selection {
start: number;
end: number;
text: string;
}
interface Review {
start: number;
end: number;
original: string;
instruction: string;
candidate: string | null;
}
export function SelectionActions({ text, onExplain, onRewrite, className }: SelectionActionsProps) {
const [value, setValue] = React.useState(text);
const [selection, setSelection] = React.useState<Selection | null>(null);
const [anchor, setAnchor] = React.useState<Anchor | null>(null);
const [instruction, setInstruction] = React.useState("");
const [expanded, setExpanded] = React.useState(false);
const [explanation, setExplanation] = React.useState<string | null>(null);
const [review, setReview] = React.useState<Review | null>(null);
const [reviewAnchor, setReviewAnchor] = React.useState<Anchor | null>(null);
const containerRef = React.useRef<HTMLParagraphElement>(null);
const toolbarRef = React.useRef<HTMLDivElement>(null);
const candidateRef = React.useRef<HTMLElement>(null);
const mounted = useMounted();
const clearSelectionState = React.useCallback(() => {
setSelection(null);
setAnchor(null);
setInstruction("");
setExpanded(false);
setExplanation(null);
}, []);
const updateFromDom = React.useCallback(
(target: Node) => {
const container = containerRef.current;
const insideToolbar = toolbarRef.current?.contains(target);
const insideContainer = container?.contains(target);
if (!insideToolbar && !insideContainer) {
clearSelectionState();
return;
}
if (insideToolbar) return;
const sel = window.getSelection();
if (!sel || sel.rangeCount === 0 || sel.isCollapsed || !container) {
clearSelectionState();
return;
}
const range = sel.getRangeAt(0);
if (!container.contains(range.commonAncestorContainer)) {
clearSelectionState();
return;
}
const { start, end } = offsetsWithin(container, range);
if (start === end) {
clearSelectionState();
return;
}
const rect = range.getBoundingClientRect();
setSelection({ start, end, text: value.slice(start, end) });
setAnchor({ top: rect.top, bottom: rect.bottom, left: rect.left + rect.width / 2 });
setExpanded(false);
setExplanation(null);
},
[value, clearSelectionState]
);
React.useEffect(() => {
if (review) return;
function handlePointerUp(e: PointerEvent) {
updateFromDom(e.target as Node);
}
function handleKeyUp(e: KeyboardEvent) {
if (e.key === "Escape") {
window.getSelection()?.removeAllRanges();
clearSelectionState();
return;
}
if (e.key.startsWith("Arrow") || e.key === "Shift") updateFromDom(e.target as Node);
}
document.addEventListener("pointerup", handlePointerUp);
document.addEventListener("keyup", handleKeyUp);
return () => {
document.removeEventListener("pointerup", handlePointerUp);
document.removeEventListener("keyup", handleKeyUp);
};
}, [review, updateFromDom, clearSelectionState]);
React.useLayoutEffect(() => {
if (!review || !candidateRef.current) return;
const rect = candidateRef.current.getBoundingClientRect();
setReviewAnchor({ top: rect.top, bottom: rect.bottom, left: rect.left + rect.width / 2 });
}, [review, review?.candidate]);
async function runRewrite(rawInstruction: string) {
if (!selection) return;
const instructionToUse = rawInstruction.trim() || DEFAULT_INSTRUCTION;
const { start, end, text: original } = selection;
window.getSelection()?.removeAllRanges();
clearSelectionState();
setReview({ start, end, original, instruction: instructionToUse, candidate: null });
const result = await onRewrite(original, instructionToUse);
setReview((prev) => (prev && prev.start === start && prev.end === end ? { ...prev, candidate: result } : prev));
}
function retry() {
if (!review) return;
const { start, end, original, instruction: usedInstruction } = review;
setReview((prev) => (prev ? { ...prev, candidate: null } : prev));
Promise.resolve(onRewrite(original, usedInstruction)).then((result) => {
setReview((prev) => (prev && prev.start === start && prev.end === end ? { ...prev, candidate: result } : prev));
});
}
function keep() {
if (!review || review.candidate == null) return;
const { start, end, candidate } = review;
setValue((prev) => prev.slice(0, start) + candidate + prev.slice(end));
setReview(null);
setReviewAnchor(null);
}
function discard() {
setReview(null);
setReviewAnchor(null);
}
async function explain() {
if (!selection || !onExplain) return;
const result = await onExplain(selection.text);
setExplanation(result);
}
return (
<div className={cn("relative w-full", className)}>
<p ref={containerRef} className="select-text text-sm leading-relaxed text-foreground/90">
{renderContent(value, review, candidateRef)}
</p>
{mounted &&
createPortal(
<>
<AnimatePresence>
{selection && anchor && !review && (
<FloatingToolbar
ref={toolbarRef}
anchor={anchor}
instruction={instruction}
onInstructionChange={setInstruction}
onSubmitInstruction={() => runRewrite(instruction)}
hasExplain={!!onExplain}
onExplain={explain}
onImprove={() => runRewrite(DEFAULT_INSTRUCTION)}
onQuickEdit={runRewrite}
expanded={expanded}
onToggleExpanded={() => setExpanded((v) => !v)}
explanation={explanation}
/>
)}
</AnimatePresence>
<AnimatePresence>
{review && reviewAnchor && (
<ReviewToolbar
anchor={reviewAnchor}
loading={review.candidate == null}
onKeep={keep}
onDiscard={discard}
onRetry={retry}
/>
)}
</AnimatePresence>
</>,
document.body
)}
</div>
);
}
function renderContent(
value: string,
review: Review | null,
candidateRef: React.RefObject<HTMLElement | null>
) {
if (!review) return value;
const before = value.slice(0, review.start);
const after = value.slice(review.end);
const loading = review.candidate == null;
return (
<>
{before}
<mark
ref={candidateRef}
aria-busy={loading}
className={cn(
"rounded px-0.5",
loading
? "animate-pulse bg-muted text-muted-foreground"
: "bg-blue-100 text-foreground dark:bg-blue-500/20"
)}
>
{loading ? review.original : review.candidate}
</mark>
{after}
</>
);
}
const FloatingToolbar = React.forwardRef<
HTMLDivElement,
{
anchor: Anchor;
instruction: string;
onInstructionChange: (v: string) => void;
onSubmitInstruction: () => void;
hasExplain: boolean;
onExplain: () => void;
onImprove: () => void;
onQuickEdit: (instruction: string) => void;
expanded: boolean;
onToggleExpanded: () => void;
explanation: string | null;
}
>(function FloatingToolbar(
{
anchor,
instruction,
onInstructionChange,
onSubmitInstruction,
hasExplain,
onExplain,
onImprove,
onQuickEdit,
expanded,
onToggleExpanded,
explanation,
},
ref
) {
const left = clampCenterX(anchor.left, TOOLBAR_WIDTH);
return (
<motion.div
ref={ref}
role="toolbar"
aria-label="Selection actions"
initial={{ opacity: 0, y: -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -4 }}
transition={{ duration: 0.14 }}
style={{ position: "fixed", top: anchor.bottom + MARGIN, left, width: TOOLBAR_WIDTH, transform: "translateX(-50%)" }}
className="z-50"
>
<div className="flex items-center gap-1 rounded-full border bg-popover px-1.5 py-1 shadow-md">
<input
value={instruction}
onChange={(e) => onInstructionChange(e.target.value)}
onKeyDown={(e) => {
if (e.key === "Enter" && instruction.trim()) onSubmitInstruction();
}}
placeholder="Describe edits"
aria-label="Describe edits"
className="min-w-0 flex-1 bg-transparent px-2 py-1 text-xs text-foreground outline-none placeholder:text-muted-foreground"
/>
{hasExplain && (
<>
<Divider />
<ToolbarButton icon={CircleHelp} label="Explain" onClick={onExplain} />
</>
)}
<Divider />
<ToolbarButton icon={Sparkles} label="Improve" onClick={onImprove} />
<Divider />
<button
type="button"
aria-label={expanded ? "Fewer quick edits" : "More quick edits"}
aria-expanded={expanded}
onClick={onToggleExpanded}
className="flex size-7 shrink-0 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<ChevronRight className={cn("size-4 transition-transform", expanded && "rotate-90")} aria-hidden />
</button>
</div>
<AnimatePresence>
{expanded && (
<motion.div
initial={{ opacity: 0, y: -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -4 }}
transition={{ duration: 0.12 }}
className="mt-1.5 overflow-hidden rounded-xl border bg-popover shadow-md"
>
{QUICK_EDITS.map((q) => (
<button
key={q}
type="button"
onClick={() => onQuickEdit(q)}
className="block w-full px-3 py-2 text-left text-xs text-foreground/90 hover:bg-accent"
>
{q}
</button>
))}
</motion.div>
)}
</AnimatePresence>
<AnimatePresence>
{explanation && (
<motion.div
role="status"
initial={{ opacity: 0, y: -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -4 }}
transition={{ duration: 0.12 }}
className="mt-1.5 rounded-xl border bg-popover p-3 text-xs text-foreground/90 shadow-md"
>
{explanation}
</motion.div>
)}
</AnimatePresence>
</motion.div>
);
});
function ToolbarButton({
icon: Icon,
label,
onClick,
}: {
icon: React.ComponentType<{ className?: string }>;
label: string;
onClick: () => void;
}) {
return (
<button
type="button"
onClick={onClick}
className="flex shrink-0 items-center gap-1.5 rounded-full px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<Icon className="size-4" aria-hidden />
{label}
</button>
);
}
function Divider() {
return <span className="h-4 w-px shrink-0 bg-border" aria-hidden />;
}
function ReviewToolbar({
anchor,
loading,
onKeep,
onDiscard,
onRetry,
}: {
anchor: Anchor;
loading: boolean;
onKeep: () => void;
onDiscard: () => void;
onRetry: () => void;
}) {
const left = clampCenterX(anchor.left, REVIEW_WIDTH);
return (
<motion.div
role="toolbar"
aria-label="Review suggested edit"
initial={{ opacity: 0, y: -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -4 }}
transition={{ duration: 0.14 }}
style={{ position: "fixed", top: anchor.bottom + MARGIN, left, transform: "translateX(-50%)" }}
className="z-50 flex items-center gap-1 rounded-full border bg-popover p-1 shadow-md"
>
<button
type="button"
disabled={loading}
onClick={onKeep}
className="flex items-center gap-1.5 rounded-full bg-foreground px-3.5 py-1.5 text-xs font-medium text-background transition-colors hover:bg-foreground/90 disabled:pointer-events-none disabled:opacity-50"
>
<Check className="size-3.5" aria-hidden />
Keep
</button>
<button
type="button"
onClick={onDiscard}
className="flex items-center gap-1.5 rounded-full px-3.5 py-1.5 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-3.5" aria-hidden />
Discard
</button>
<span className="h-4 w-px bg-border" aria-hidden />
<button
type="button"
aria-label="Retry"
disabled={loading}
onClick={onRetry}
className="flex size-7 shrink-0 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-50"
>
{loading ? <Loader2 className="size-3.5 animate-spin" aria-hidden /> : <RotateCcw className="size-3.5" aria-hidden />}
</button>
</motion.div>
);
}
function offsetsWithin(container: HTMLElement, range: Range) {
const pre = document.createRange();
pre.selectNodeContents(container);
pre.setEnd(range.startContainer, range.startOffset);
const start = pre.toString().length;
return { start, end: start + range.toString().length };
}
function clampCenterX(centerX: number, width: number) {
if (typeof window === "undefined") return centerX;
return Math.min(Math.max(centerX, width / 2 + MARGIN), window.innerWidth - width / 2 - MARGIN);
}
/** True only once the client has rendered — lets a portal target `document.body` without an SSR mismatch. */
function useMounted() {
return React.useSyncExternalStore(
() => () => {},
() => true,
() => false
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Selection Actions
## Summary
A floating toolbar that appears when the user highlights a passage of agent-written text, letting them describe an edit, ask for an explanation, or request an improvement without leaving the reading flow. Submitting an action replaces the highlight with a live, editable suggestion — shown inline with a subtle highlight — that the user keeps, discards, or retries before it lands in the text.
## When to use
- Over any block of agent-generated text the user is expected to revise in place — a drafted email, a generated paragraph, a summary — rather than regenerating the whole response.
- When edits are naturally scoped to a phrase or sentence rather than the whole document, so anchoring the toolbar to the selection reads more directly than a document-level "regenerate" action.
- When the user benefits from a quick, low-commitment way to ask "why did you write this" (Explain) alongside ways to change it (Improve, a custom instruction, or a quick-edit shortcut).
## When not to use
- On text the user can't or shouldn't edit (system messages, another person's message, read-only citations) — offering a rewrite toolbar implies the content is theirs to change.
- For whole-document actions like "regenerate this response" or "translate the whole thing" — those belong on a persistent action bar for the message, not a selection-anchored popup.
- On very short text (a label, a single word) where a highlight-triggered toolbar has more visual weight than the content it's acting on.
## Anatomy
- A pill-shaped toolbar anchored below the current selection: a borderless "Describe edits" text field on the left, a vertical divider, an "Explain" button (circle-help icon), another divider, an "Improve" button (sparkle icon), a final divider, and a chevron that expands a short list of quick edits (e.g. "Fix grammar," "Shorten," "Make more formal").
- Once an edit is requested, the toolbar is replaced by the candidate text rendered inline with a highlight (a muted pulsing highlight while generating, a colored highlight once ready) directly in place of the original passage.
- Below the candidate, a second pill toolbar appears: a filled "Keep" button, a plain "Discard" button, and a small icon-only "Retry" button, separated the same way as the first toolbar.
## Behavior
- The toolbar appears only once a selection is finalized (on pointer-up or after a keyboard selection), not while the user is still dragging — so it doesn't jitter mid-drag.
- Clicking Explain, Improve, a quick edit, or submitting the instruction field immediately swaps the selection for the review state: the original selection is replaced by an inline highlighted placeholder while the request is in flight, then by the candidate text once it resolves.
- Explain does not enter the review flow — it opens an inline answer panel below the toolbar and leaves the original text untouched.
- While reviewing a candidate, new selections are disabled; the user must Keep or Discard first.
- Keep commits the candidate into the underlying text and closes the toolbar. Discard reverts to the original passage with no trace of the attempt. Retry re-runs the same instruction and shows the loading highlight again without discarding the review state.
- Clicking outside the toolbar and the selected passage, or pressing Escape, dismisses the toolbar and clears the selection without making any change.
## Content guidelines
- Keep quick-edit labels as short verb phrases ("Fix grammar," "Shorten") the user can scan in under a second — they're shortcuts, not full instructions.
- The Explain response should describe intent or reasoning ("this sets the deadline because—"), not just restate the sentence in other words.
- Default the Improve action to a clear, generic instruction ("improve clarity and flow") so it's useful without the user typing anything.
## Accessibility
- Both toolbars have `role="toolbar"` with a descriptive `aria-label`, and the instruction field carries its own `aria-label` since its only visible label is placeholder text.
- The candidate highlight sets `aria-busy` while generating so assistive tech doesn't announce placeholder content as final.
- The explanation panel uses `role="status"` so screen reader users hear the answer as it appears without needing to navigate to it.
- Escape and outside-click both dismiss the toolbar, matching how any other transient popover on the page behaves.
## Related patterns
- Chat Bubble with Actions covers whole-message actions (regenerate, edit-and-resubmit) — reach for Selection Actions when the edit is scoped to part of a message instead of the whole thing.
- Inline Citation uses the same anchored-popover positioning technique for a hover-triggered footnote instead of a click-triggered action toolbar.
Rate Limit
A quota-exceeded state with a live countdown to when the user can send again.
Approaching weekly usage limitResets at 18:00
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { X } from "lucide-react";
import { cn } from "@/lib/utils";
export interface RateLimitProps {
label: string;
resetTime?: string;
resetAt?: Date;
upgradeLabel?: string;
onUpgrade?: () => void;
onDismiss?: () => void;
className?: string;
}
function useCountdown(resetAt?: Date) {
const getRemaining = () =>
resetAt ? Math.max(0, Math.floor((resetAt.getTime() - Date.now()) / 1000)) : null;
const [remaining, setRemaining] = React.useState(getRemaining);
React.useEffect(() => {
if (!resetAt) return;
const id = window.setInterval(() => setRemaining(getRemaining()), 1000);
return () => window.clearInterval(id);
}, [resetAt]);
if (remaining === null) return null;
const m = Math.floor(remaining / 60);
const s = remaining % 60;
return `${m}:${String(s).padStart(2, "0")}`;
}
export function RateLimit({
label,
resetTime,
resetAt,
upgradeLabel = "Get more usage",
onUpgrade,
onDismiss,
className,
}: RateLimitProps) {
const [visible, setVisible] = React.useState(true);
const countdown = useCountdown(resetAt);
const resetLabel = countdown ? `Resets in ${countdown}` : resetTime ? `Resets at ${resetTime}` : null;
function dismiss() {
setVisible(false);
onDismiss?.();
}
return (
<AnimatePresence>
{visible && (
<motion.div
initial={{ opacity: 0, y: -6 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -6 }}
transition={{ duration: 0.2, ease: "easeOut" }}
role="status"
aria-live="polite"
className={cn(
"flex w-full items-center gap-3 rounded-2xl border border-border bg-muted/50 px-4 py-2.5",
className
)}
>
<PulsingIcon />
<div className="flex min-w-0 flex-1 items-center gap-2">
<span className="truncate text-xs font-medium text-foreground">{label}</span>
{resetLabel && (
<span className="shrink-0 text-xs text-muted-foreground" aria-label={resetLabel}>
{resetLabel}
</span>
)}
</div>
{onUpgrade && (
<button
type="button"
onClick={onUpgrade}
className="shrink-0 rounded-lg border border-border bg-background px-3 py-1 text-xs font-medium text-foreground transition-colors hover:bg-accent"
>
{upgradeLabel}
</button>
)}
{onDismiss && (
<button
type="button"
onClick={dismiss}
aria-label="Dismiss"
className="shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-4" aria-hidden />
</button>
)}
</motion.div>
)}
</AnimatePresence>
);
}
function PulsingIcon() {
return (
<span className="relative flex size-4 shrink-0 items-center justify-center" aria-hidden>
<span className="absolute size-3.5 animate-ping rounded-full bg-foreground/10" />
<span className="relative flex size-4 items-center justify-center rounded-full">
<svg width="16" height="16" viewBox="0 0 16 16" fill="none" className="text-foreground/60">
<circle cx="8" cy="8" r="1.5" fill="currentColor" />
<path
d="M5.2 10.8a4 4 0 0 1 0-5.6"
stroke="currentColor"
strokeWidth="1.2"
strokeLinecap="round"
/>
<path
d="M10.8 10.8a4 4 0 0 0 0-5.6"
stroke="currentColor"
strokeWidth="1.2"
strokeLinecap="round"
/>
<path
d="M3.4 12.6a6.5 6.5 0 0 1 0-9.2"
stroke="currentColor"
strokeWidth="1.2"
strokeLinecap="round"
opacity="0.4"
/>
<path
d="M12.6 12.6a6.5 6.5 0 0 0 0-9.2"
stroke="currentColor"
strokeWidth="1.2"
strokeLinecap="round"
opacity="0.4"
/>
</svg>
</span>
</span>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Rate Limit
## Summary
A dismissible horizontal banner that warns the user their usage is approaching or has reached a quota limit. Shows a label, an optional reset time or live countdown, an upgrade CTA, and a dismiss control — all in a single compact row.
## When to use
- When the user is approaching or has hit a per-day, per-week, or per-month message quota.
- As a non-blocking notice inline in the UI — not a modal, not a toast, not a full page. The user should be able to read it and continue working (or dismiss it).
- When a reset time is known (either a specific clock time or a duration), always show it — it transforms a hard stop into a temporary state.
## When not to use
- Transient server errors or network failures — use the Generation Error pattern instead.
- Hard blocks where the user truly cannot proceed (account suspended, payment failed) — those warrant a modal or full-page state, not a dismissible banner.
- Per-request throttling (HTTP 429 with immediate retry-after < 60s) — show a brief inline message rather than a persistent banner.
## Anatomy
- **Pulsing signal icon**: concentric arcs around a center dot, with a subtle ping animation. Communicates "signal / broadcast / status" — not an error icon, not an alarm.
- **Label**: the usage limit message in medium-weight text. Should describe what limit was hit, not the raw technical limit.
- **Reset label**: muted text, inline with the label. Either a static clock time ("Resets at 18:00") or a live MM:SS countdown ("Resets in 4:23").
- **Upgrade CTA**: a bordered pill button with a short action label. Only shown when `onUpgrade` is provided.
- **Dismiss (×)**: icon-only button at the far right. Removes the banner with an exit animation.
## Behavior
- Enters with a short downward fade (opacity 0→1, y -6→0, 200ms ease-out).
- Exits with the reverse when dismissed.
- Countdown mode: a `setInterval` ticking every second drives the MM:SS display. The interval stops at 0 to avoid unnecessary renders. Callers are responsible for restoring access when the timer expires — this component does not re-enable the composer automatically.
- Static mode: `resetTime` is a pre-formatted string ("18:00"); the component renders it as-is.
- Dismissing via the × fires `onDismiss` and hides the component. Callers decide whether to re-show it (e.g. on next page load or after a threshold is crossed again).
## Reset label variants
- **`resetTime` (string)**: Pass a pre-formatted clock time. Use for quota resets tied to a known wall-clock time ("Resets at 18:00", "Resets at midnight").
- **`resetAt` (Date)**: Pass a future timestamp. The component derives a live countdown ("Resets in 4:23"). Use when the API returns an exact reset timestamp.
- If both are provided, `resetAt` takes precedence (live countdown is more informative).
- If neither is provided, no reset label is shown.
## Content guidelines
- Label: describe the limit in human terms, not API terms. "Approaching weekly usage limit" not "429 Too Many Requests" or "Rate limit: 10/10 used".
- Never show the raw numeric quota ("You've used 10 of 10 messages") — it frames the product negatively.
- Upgrade label: "Get more usage" or "Upgrade" — short, benefit-framed, not "Buy now" or "Go Pro".
- Reset label: "Resets at [time]" or "Resets in [MM:SS]" — consistent preposition, no parentheses.
## Accessibility
- The container has `role="status"` and `aria-live="polite"` so screen readers announce it when it appears without interrupting the user.
- The countdown span has an `aria-label` with the human-readable form ("Resets in 4 minutes 23 seconds") — screen readers don't read "4:23" legibly.
- The dismiss button has `aria-label="Dismiss"`.
- The pulsing icon is `aria-hidden` — it is decorative.
- Countdown ticks should NOT be in a live region themselves — announcing every second would be disruptive. The initial announcement of the full banner is sufficient.
## Related patterns
- Generation Error — for individual response failures, not quota states.
- Partial Response — for responses cut short by token limits rather than user quotas.
Partial Response
A cut-short assistant reply with Continue and Retry actions.
The ai-patterns skill gives any Claude Code session access to the full pattern library. Once installed, you can reference patterns by name in your prompts — for example, "use the Streaming Text pattern for the assistant reply" or "wire up the Tool Approval pattern before each shell command". The skill exposes each pattern's UX spec, component source, and demo so Claude can
Stopped · Response was stopped before it finished.
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { ChevronRight, RotateCcw } from "lucide-react";
import { cn } from "@/lib/utils";
export type PartialResponseReason = "interrupted" | "max-tokens" | "error";
export interface PartialResponseProps {
content: string;
reason?: PartialResponseReason;
onResume?: () => void;
onRetry?: () => void;
resuming?: boolean;
className?: string;
}
const reasonConfig: Record<PartialResponseReason, { label: string; hint: string; showResume: boolean }> = {
interrupted: {
label: "Stopped",
hint: "Response was stopped before it finished.",
showResume: true,
},
"max-tokens": {
label: "Cut off",
hint: "Response reached the output limit.",
showResume: true,
},
error: {
label: "Incomplete",
hint: "Response stopped due to an error.",
showResume: false,
},
};
export function PartialResponse({
content,
reason = "interrupted",
onResume,
onRetry,
resuming = false,
className,
}: PartialResponseProps) {
const config = reasonConfig[reason];
return (
<div className={cn("flex flex-col gap-0 rounded-2xl border border-border bg-muted/30 overflow-hidden", className)}>
<div className="px-4 py-3 text-sm leading-relaxed text-foreground">
{content}
<motion.span
className="ml-0.5 inline-block h-[1em] w-0.5 translate-y-[1px] rounded-sm bg-foreground/40"
animate={{ opacity: [1, 0] }}
transition={{ duration: 0.8, repeat: Infinity, ease: "linear" }}
aria-hidden
/>
</div>
<div className="flex items-center justify-between border-t border-border/60 bg-muted/40 px-4 py-2.5">
<p className="text-xs text-muted-foreground">
<span className="font-medium text-foreground">{config.label}</span>
{" · "}
{config.hint}
</p>
<div className="flex items-center gap-1.5">
{onRetry && (
<button
type="button"
onClick={onRetry}
aria-label="Retry from scratch"
className="flex items-center gap-1 rounded-full px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<RotateCcw className="size-3" aria-hidden />
Retry
</button>
)}
{config.showResume && onResume && (
<button
type="button"
onClick={onResume}
disabled={resuming}
aria-label={resuming ? "Resuming response" : "Continue response"}
className="flex items-center gap-1 rounded-full bg-foreground px-2.5 py-1 text-xs font-medium text-background transition-opacity hover:opacity-80 disabled:opacity-50"
>
{resuming ? (
"Continuing…"
) : (
<>
Continue
<ChevronRight className="size-3" aria-hidden />
</>
)}
</button>
)}
</div>
</div>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Partial Response
## Summary
A message component for responses that ended before completion. Displays whatever text was generated, clearly marks it as incomplete, and offers Continue (resume from the cut-off point) and Retry (regenerate from scratch) actions.
## When to use
- The stream ended before a natural conclusion — stopped by the user, cut off by an output token limit, or dropped by a transient error — and some content was produced.
- Any time preserving and resuming the partial output is preferable to discarding it. A partial response with continuation is nearly always more useful than a blank error card.
- In the message thread at the position of the incomplete assistant turn, not as a modal or a separate panel.
## When not to use
- Zero content produced — if the response never started, use the Generation Error pattern instead.
- The content is corrupted or nonsensical (e.g. a mid-token cut-off in a code block) — in this case retry is the better default action; hide Continue.
- Read-only transcript views where resuming is not an option.
## Reasons
Three distinct reasons change the copy and available actions:
- **interrupted**: User clicked Stop. Label "Stopped". Both Continue and Retry are available.
- **max-tokens**: Hit the model's output token ceiling. Label "Cut off". Both Continue (model continues from the cut-off) and Retry are available.
- **error**: Transient error mid-stream. Label "Incomplete". Only Retry is available — continuing from an error state may reproduce the error.
## Anatomy
- Content area: the partial text, rendered as-is, with a blinking cursor appended to signal incompleteness.
- Status bar: a hairline-bordered footer row.
- Left: reason label (bold) + separator + one-line hint in muted text.
- Right: Retry button (ghost, muted) and Continue button (filled, primary). Continue is the primary action.
- Blinking cursor: a narrow vertical bar animating opacity 1→0 on a 0.8s loop. Hidden with `aria-hidden`.
## Behavior
- The cursor blinks continuously at rest to keep the "mid-stream" sense alive even after the stream stopped.
- Tapping Continue puts the button into "Continuing…" disabled state immediately; the caller owns the actual resumption request and passes `resuming={true}` back.
- Resumption semantics (sending the prior context + the partial response as the new prompt) are the caller's responsibility. This component signals intent; it does not issue API calls.
- Tapping Retry discards the partial content and issues a fresh generation from the original prompt. The caller handles this by removing the partial message and resubmitting.
- Only one action may be in-flight at a time (Continue disables during `resuming`). Retry does not need a loading state if the caller immediately replaces this component with a new streaming response.
## Content guidelines
- Reason labels: "Stopped", "Cut off", "Incomplete" — short, factual, no punctuation.
- Hint text: one sentence, no more. "Response was stopped before it finished." / "Response reached the output limit." / "Response stopped due to an error."
- Continue label: "Continue" with a › chevron — implies the stream will pick up from here, not start over.
- Retry label: "Retry" — unambiguous, separate from Continue.
- Never expose the token count or technical limit to the user ("stopped at 4096 tokens").
## Accessibility
- The blinking cursor has `aria-hidden` — it is a decorative animation.
- Continue button `aria-label` changes to "Resuming response" when `resuming` is true, giving screen-reader users feedback without a visible spinner.
- The status bar text is available to assistive technology as static text; no additional live region is needed since the component appears fully rendered.
- Keyboard: both actions are reachable via Tab; Continue is the last focused element in the component (rightmost in the footer), matching its primary-action status.
## Related patterns
- Generation Error — for requests that produced no output at all.
- Rate Limit — for quota-exceeded states where the user must wait before retrying.
- Stop Generation Button — the control that triggers the "interrupted" reason for this pattern.
- Streaming Text — the in-progress version of this component, before the stream ends.
Generation Error
A console-style error card for a failed generation, with details and retry.
Something went wrong
The response couldn't be generated.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { ChevronDown, CircleAlert, RotateCcw } from "lucide-react";
import { cn } from "@/lib/utils";
export type GenerationErrorReason = "network" | "server" | "timeout" | "filtered";
export interface GenerationErrorProps {
reason?: GenerationErrorReason;
message?: string;
errorCode?: string;
onRetry?: () => void;
retrying?: boolean;
className?: string;
}
const reasonConfig: Record<GenerationErrorReason, { title: string; hint: string; retryable: boolean }> = {
network: {
title: "Connection lost",
hint: "Check your connection and try again.",
retryable: true,
},
server: {
title: "Something went wrong",
hint: "The response couldn't be generated.",
retryable: true,
},
timeout: {
title: "Request timed out",
hint: "The model took too long to respond.",
retryable: true,
},
filtered: {
title: "Response blocked",
hint: "This request was blocked by content safety filters.",
retryable: false,
},
};
export function GenerationError({
reason = "server",
message,
errorCode,
onRetry,
retrying = false,
className,
}: GenerationErrorProps) {
const [detailsOpen, setDetailsOpen] = React.useState(false);
const config = reasonConfig[reason];
return (
<div
role="alert"
className={cn("flex flex-col gap-0 rounded-2xl border border-border bg-muted/30 overflow-hidden", className)}
>
<div className="flex items-start gap-3 px-4 py-3">
<CircleAlert className="mt-0.5 size-4 shrink-0 text-muted-foreground" aria-hidden />
<div className="flex min-w-0 flex-1 flex-col gap-0.5">
<p className="text-xs font-medium text-foreground">{config.title}</p>
<p className="text-[11px] text-muted-foreground">{message ?? config.hint}</p>
</div>
</div>
<div className="flex items-center justify-between border-t border-border/60 bg-muted/40 px-4 py-2.5">
{errorCode ? (
<button
type="button"
onClick={() => setDetailsOpen((v) => !v)}
aria-expanded={detailsOpen}
className="flex items-center gap-1 text-[11px] text-muted-foreground transition-colors hover:text-foreground"
>
<ChevronDown
className={cn("size-3 transition-transform", detailsOpen && "rotate-180")}
aria-hidden
/>
Show details
</button>
) : (
<span />
)}
{config.retryable && onRetry && (
<button
type="button"
onClick={onRetry}
disabled={retrying}
aria-label={retrying ? "Retrying" : "Retry"}
className="flex items-center gap-1 rounded-full bg-foreground px-2.5 py-1 text-[11px] font-medium text-background transition-opacity hover:opacity-80 disabled:opacity-50"
>
<RotateCcw className={cn("size-3", retrying && "animate-spin")} aria-hidden />
{retrying ? "Retrying…" : "Retry"}
</button>
)}
</div>
<AnimatePresence initial={false}>
{detailsOpen && errorCode && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.18, ease: "easeOut" }}
className="overflow-hidden border-t border-border/60"
>
<pre className="whitespace-pre-wrap break-all px-4 py-2.5 font-mono text-[11px] text-muted-foreground">
{errorCode}
</pre>
</motion.div>
)}
</AnimatePresence>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Generation Error
## Summary
A message-thread card for a generation that produced no output at all — a network drop, a server failure, a timeout, or a content-safety block. Shows a short human-readable reason, an optional collapsible technical detail (a console-style error line), and a Retry action where retrying makes sense.
## When to use
- The request never produced any content — nothing to preserve, unlike a cut-short stream.
- In the message thread at the position of the failed assistant turn, replacing the loader that was there.
- Whenever a technical error code, request ID, or stack-like detail exists and might help a user reporting the issue — surface it behind "Show details" rather than inline.
## When not to use
- Some content was generated before the failure — use the Partial Response pattern instead so the user doesn't lose it.
- Quota/usage limits — use the Rate Limit pattern; those are expected, recurring states, not failures.
- Validation errors on the user's own input (empty prompt, unsupported file type) — handle inline in the composer, not as a thread message.
## Reasons
Four distinct reasons change the copy and whether Retry is offered:
- **network**: Connection dropped mid-request. Title "Connection lost". Retryable.
- **server**: Upstream failure. Title "Something went wrong". Retryable.
- **timeout**: The model didn't respond in time. Title "Request timed out". Retryable.
- **filtered**: Blocked by content-safety policy. Title "Response blocked". Not retryable — retrying the same prompt will fail the same way; the user needs to change the request instead.
## Anatomy
- Icon: a muted alert glyph, not an alarming red — consistent with this library's other error/limit states.
- Title (bold) + one-line hint, muted.
- Footer row: "Show details" toggle on the left (only rendered when `errorCode` is passed), Retry button on the right (only when the reason is retryable and `onRetry` is passed).
- Details panel: a monospace, console-style line with the technical error code / request ID, expandable under the footer.
## Behavior
- Details panel animates open/closed by height, collapsed by default.
- Retry enters a disabled "Retrying…" state immediately on tap; the spinner icon rotates. The caller owns the actual re-generation call and clears `retrying` when it resolves (success replaces this component; failure re-renders it).
- Non-retryable reasons (`filtered`) never show a Retry button even if `onRetry` is passed — the caller should instead let the user edit and resend their prompt.
- `message` overrides the default hint text per reason, for surfacing a more specific server-provided message without changing the title or retryability.
## Content guidelines
- Titles are short and human: "Connection lost", "Something went wrong", "Request timed out", "Response blocked" — never a raw HTTP status or exception class name in the title.
- The hint is one sentence, plain language, no blame ("Check your connection and try again," not "Your connection failed").
- Technical detail (`errorCode`) is the only place raw identifiers belong — request IDs, error codes, stack fragments — and it's opt-in behind "Show details", never shown by default.
- Retry label is always "Retry", not "Try again" or "Regenerate" — keep it distinct from the Partial Response pattern's "Continue"/"Retry" pair.
## Accessibility
- The card has `role="alert"` so screen readers announce the failure as it mounts.
- "Show details" uses `aria-expanded` reflecting panel state.
- The Retry button's `aria-label` switches to "Retrying" while in flight, since the visible label ("Retrying…") pairs with a spinning icon that conveys nothing to assistive tech on its own.
- The alert icon is `aria-hidden` — the card's text content, not the icon, carries the meaning.
## Related patterns
- Partial Response — for streams that produced some content before stopping.
- Rate Limit — for quota-exceeded states, which are expected and recurring rather than failures.
Console Error Card
A structured card surfacing a browser console error with a code frame, call stack, and navigation.
1/2Console Error
Encountered a script tag while rendering React component. Scripts inside React components are never executed when rendering on the client. Consider using template tag instead.
src/app/layout.tsx (43:9) @ RootLayout
41 >
42 <head>
>43 <script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
44 </head>
45 <body className="flex min-h-full flex-col font-sans">
46 <header className="border-b">
Was this helpful?
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { ChevronLeft, ChevronRight, ChevronDown, Copy, ThumbsUp, ThumbsDown, X, ExternalLink } from "lucide-react";
import { cn } from "@/lib/utils";
export interface CodeLine {
number: number;
content: string;
isError?: boolean;
}
export interface CodeFrame {
file: string;
lines: CodeLine[];
}
export interface StackFrame {
name: string;
context?: string;
file?: string;
}
export interface ConsoleErrorCardProps {
type?: "error" | "warning";
message: string;
frame?: CodeFrame;
stack?: StackFrame[];
current?: number;
total?: number;
onPrev?: () => void;
onNext?: () => void;
onClose?: () => void;
onCopy?: () => void;
onOpenFrame?: (file: string) => void;
onHelpful?: (value: boolean) => void;
className?: string;
}
export function ConsoleErrorCard({
type = "error",
message,
frame,
stack = [],
current = 1,
total = 1,
onPrev,
onNext,
onClose,
onCopy,
onOpenFrame,
onHelpful,
className,
}: ConsoleErrorCardProps) {
const [stackOpen, setStackOpen] = React.useState(false);
const [helpfulVote, setHelpfulVote] = React.useState<boolean | null>(null);
const [copied, setCopied] = React.useState(false);
function handleCopy() {
onCopy?.();
setCopied(true);
setTimeout(() => setCopied(false), 1500);
}
function handleHelpful(value: boolean) {
setHelpfulVote(value);
onHelpful?.(value);
}
const isError = type === "error";
return (
<div
className={cn(
"w-full overflow-hidden rounded-2xl border border-border bg-background text-foreground",
className
)}
>
{/* Top bar */}
<div className="flex items-center justify-between border-b border-border px-3.5 py-2.5">
<div className="flex items-center gap-2">
{total > 1 && (
<>
<button
type="button"
onClick={onPrev}
disabled={current <= 1}
aria-label="Previous error"
className="rounded-md p-0.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
>
<ChevronLeft className="size-4" aria-hidden />
</button>
<span className="font-mono text-[11px] text-muted-foreground tabular-nums">
{current}/{total}
</span>
<button
type="button"
onClick={onNext}
disabled={current >= total}
aria-label="Next error"
className="rounded-md p-0.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground disabled:pointer-events-none disabled:opacity-40"
>
<ChevronRight className="size-4" aria-hidden />
</button>
</>
)}
<span
className={cn(
"rounded-md px-2 py-0.5 text-[11px] font-semibold",
isError
? "bg-red-100 text-red-700 dark:bg-red-950/60 dark:text-red-400"
: "bg-amber-100 text-amber-700 dark:bg-amber-950/60 dark:text-amber-400"
)}
>
Console {isError ? "Error" : "Warning"}
</span>
</div>
<div className="flex items-center gap-1">
{onCopy && (
<button
type="button"
onClick={handleCopy}
aria-label="Copy error"
className="rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<AnimatePresence mode="wait" initial={false}>
{copied ? (
<motion.svg
key="check"
initial={{ scale: 0.7, opacity: 0 }}
animate={{ scale: 1, opacity: 1 }}
exit={{ scale: 0.7, opacity: 0 }}
transition={{ duration: 0.15 }}
className="size-4 text-emerald-500"
viewBox="0 0 16 16"
fill="none"
>
<path d="M3 8l3.5 3.5L13 5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
</motion.svg>
) : (
<motion.div key="copy" initial={{ scale: 0.7, opacity: 0 }} animate={{ scale: 1, opacity: 1 }} exit={{ scale: 0.7, opacity: 0 }} transition={{ duration: 0.15 }}>
<Copy className="size-4" aria-hidden />
</motion.div>
)}
</AnimatePresence>
</button>
)}
{onClose && (
<button
type="button"
onClick={onClose}
aria-label="Close"
className="rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-4" aria-hidden />
</button>
)}
</div>
</div>
{/* Error message */}
<div className="px-4 py-3">
<p
className={cn(
"text-xs leading-relaxed",
isError ? "text-red-600 dark:text-red-400" : "text-amber-600 dark:text-amber-400"
)}
>
{message}
</p>
</div>
{/* Code frame */}
{frame && (
<div className="mx-4 mb-3 overflow-hidden rounded-xl border border-border bg-muted/40">
<div className="flex items-center justify-between border-b border-border px-3 py-2">
<span className="font-mono text-[11px] text-muted-foreground">{frame.file}</span>
{onOpenFrame && (
<button
type="button"
onClick={() => onOpenFrame(frame.file)}
aria-label="Open in editor"
className="rounded p-0.5 text-muted-foreground transition-colors hover:text-foreground"
>
<ExternalLink className="size-3.5" aria-hidden />
</button>
)}
</div>
<div className="overflow-x-auto p-2 font-mono text-[11px] leading-5">
{frame.lines.map((line) => (
<div
key={line.number}
className={cn(
"flex gap-3 rounded px-1",
line.isError
? "bg-red-50 dark:bg-red-950/40"
: ""
)}
>
<span
className={cn(
"w-6 shrink-0 select-none text-right tabular-nums",
line.isError
? "text-red-400 dark:text-red-500"
: "text-muted-foreground/50"
)}
>
{line.isError ? ">" : ""}{line.number}
</span>
<span className="whitespace-pre text-muted-foreground">
<CodeContent content={line.content} isError={line.isError} />
</span>
</div>
))}
</div>
</div>
)}
{/* Call stack */}
{stack.length > 0 && (
<div className="mx-4 mb-3 overflow-hidden rounded-xl border border-border">
<button
type="button"
onClick={() => setStackOpen((v) => !v)}
aria-expanded={stackOpen}
className="flex w-full items-center justify-between px-3 py-2 text-left transition-colors hover:bg-muted/50"
>
<div className="flex items-center gap-2">
<span className="text-[11px] font-semibold text-foreground">Call Stack</span>
<span className="rounded-md bg-muted px-1.5 py-0.5 font-mono text-[11px] text-muted-foreground tabular-nums">
{stack.length}
</span>
</div>
<ChevronDown
className={cn(
"size-4 shrink-0 text-muted-foreground transition-transform",
stackOpen && "rotate-180"
)}
aria-hidden
/>
</button>
<AnimatePresence initial={false}>
{stackOpen && (
<motion.div
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.18, ease: "easeInOut" }}
className="overflow-hidden border-t border-border"
>
<div className="divide-y divide-border">
{stack.map((frame, i) => (
<div key={i} className="px-3 py-2">
<p className="text-[11px] font-medium text-foreground">{frame.name}</p>
{frame.context && (
<p className="text-[11px] text-muted-foreground">{frame.context}</p>
)}
{frame.file && (
<p className="mt-0.5 font-mono text-[11px] text-muted-foreground/70">{frame.file}</p>
)}
</div>
))}
</div>
</motion.div>
)}
</AnimatePresence>
</div>
)}
{/* Footer */}
{onHelpful && (
<div className="flex items-center justify-end gap-2 border-t border-border px-4 py-2.5">
<span className="text-[11px] text-muted-foreground">Was this helpful?</span>
<button
type="button"
onClick={() => handleHelpful(true)}
aria-label="Yes, helpful"
aria-pressed={helpfulVote === true}
className={cn(
"rounded-md p-1 transition-colors",
helpfulVote === true
? "text-emerald-500"
: "text-muted-foreground hover:text-foreground"
)}
>
<ThumbsUp className="size-3.5" aria-hidden />
</button>
<button
type="button"
onClick={() => handleHelpful(false)}
aria-label="Not helpful"
aria-pressed={helpfulVote === false}
className={cn(
"rounded-md p-1 transition-colors",
helpfulVote === false
? "text-red-500"
: "text-muted-foreground hover:text-foreground"
)}
>
<ThumbsDown className="size-3.5" aria-hidden />
</button>
</div>
)}
</div>
);
}
function CodeContent({ content, isError }: { content: string; isError?: boolean }) {
return (
<span className={isError ? "text-foreground" : undefined}>
{content}
</span>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Console Error Card
## Summary
A structured card that surfaces a browser console error or warning inside an AI product's interface. Shows a human-readable error message, an inline code frame pointing to the offending line, a collapsible call stack, and optional navigation across multiple errors — letting the user inspect, copy, and dismiss without leaving the conversation.
## When to use
- When an AI coding assistant detects a runtime error in the user's running application and needs to show it contextually alongside the conversation.
- When surfacing errors collected from a browser session, a test run, or a build log that the AI is helping the user debug.
- When there are multiple errors to navigate through (1/N pattern) and the user needs to triage them one at a time.
## When not to use
- Quota or rate-limit errors — use the Rate Limit pattern instead.
- Simple one-line error toasts that don't need code context — use a standard alert or toast.
- Full-screen error pages (unrecoverable crashes) — this card is for inline, dismissible inspection, not for blocking states.
- Compiler or build errors without a known line number — omit the code frame; don't show an empty frame.
## Anatomy
- **Top bar**: navigation arrows (previous / next) and a "1/N" counter for multi-error sessions; a severity badge ("Console Error" in red, "Console Warning" in amber); copy and close action buttons.
- **Error message**: the raw error text, rendered in the severity color. Should be scannable at a glance.
- **Code frame**: file path and line:col reference in the header; a small window of source lines with the error line highlighted and a ">" gutter indicator; an optional "Open in editor" affordance.
- **Call Stack**: a collapsible section with a frame count badge. Each frame shows the function name, an optional anonymous-context label, and the file path. Hidden by default to reduce visual weight.
- **Helpful footer**: thumbs-up / thumbs-down feedback, revealed only when `onHelpful` is wired up. Lets the product collect signal on error surface quality.
## Behavior
- Navigation arrows are disabled when at the first or last error; they are hidden entirely when `total` is 1.
- The call stack collapses with a height animation (Motion `AnimatePresence`). Opening it does not shift the surrounding layout unexpectedly — use overflow-hidden during transition.
- Copying triggers a brief checkmark-swap animation on the copy icon (≈1.5 s), then reverts. No toast is needed — the icon change is the confirmation.
- The helpful-vote buttons toggle `aria-pressed` and apply a color accent on selection; voting again on the same choice has no effect (idempotent).
- Closing fires `onClose` and is the caller's responsibility — the card itself does not unmount; wrap it in `AnimatePresence` if you need an exit animation.
## Code frame guidelines
- Show 3–6 lines of context around the error line; 2 lines before and 2 after is a good default.
- Always include the line number and column in the file header (`path/to/file.tsx (line:col) @ FunctionName`).
- Highlight only the single error line — highlighting a range suggests a range selection, which is misleading.
- If the source is not available, omit the `frame` prop entirely rather than showing a placeholder.
## Content guidelines
- Error message: verbatim from the console, no paraphrasing. The stack trace may rephrase, but the top-level message must be exact so the user can search for it.
- Badge label: "Console Error" or "Console Warning" — not "Runtime Error", "JS Error", or anything branded.
- Call stack frame names: use the function/component name as it appears in the source, not the mangled bundler name. If the frame is anonymous, show `<anonymous>` literally.
- "Was this helpful?" — only show this when the AI generated the error diagnosis. Don't ask for helpfulness on raw errors the AI simply forwarded.
## Accessibility
- The card root should have `role="alert"` when it appears dynamically so screen readers announce it immediately.
- Navigation buttons have `aria-label="Previous error"` / `aria-label="Next error"`.
- The call-stack toggle button has `aria-expanded` tracking the open state.
- Thumbs buttons have `aria-label` ("Yes, helpful" / "Not helpful") and `aria-pressed` for toggle semantics.
- The code frame is `aria-hidden` to screen readers if the full error message already conveys the problem — avoid reading out raw code lines.
## Related patterns
- Rate Limit — for quota-based errors, not runtime errors.
- Partial Response — for responses cut short by token or context limits.
- Terminal Stream — for streaming build/test output where errors surface in line.
Connectivity Error
A dismissible card surfacing a network connection failure with a description and retry/details actions.
Connection lostCheck your internet connection, VPN or proxy and try again.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { WifiOff, X } from "lucide-react";
import { cn } from "@/lib/utils";
export interface ConnectivityErrorProps {
title?: string;
description?: string;
detailsLabel?: string;
retryLabel?: string;
onViewDetails?: () => void;
onRetry?: () => void;
onClose?: () => void;
className?: string;
}
export function ConnectivityError({
title = "Connection lost",
description = "Check your internet connection, VPN or proxy and try again.",
detailsLabel = "View details",
retryLabel = "Try again",
onViewDetails,
onRetry,
onClose,
className,
}: ConnectivityErrorProps) {
const [visible, setVisible] = React.useState(true);
function handleClose() {
setVisible(false);
onClose?.();
}
return (
<AnimatePresence>
{visible && (
<motion.div
initial={{ opacity: 0, y: -6 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -6 }}
transition={{ duration: 0.2, ease: "easeOut" }}
role="alert"
aria-live="assertive"
className={cn(
"flex w-full flex-wrap items-center gap-x-4 gap-y-2 overflow-hidden rounded-lg border border-border bg-background px-4 py-2.5 text-foreground",
className
)}
>
{/* Message */}
<div className="flex min-w-0 flex-1 items-center gap-2">
<WifiOff className="size-3.5 shrink-0 text-foreground" aria-hidden />
<span className="truncate text-xs font-semibold text-foreground">{title}</span>
<span className="truncate text-xs text-muted-foreground">{description}</span>
</div>
{/* Actions */}
<div className="flex shrink-0 items-center gap-2">
{onViewDetails && (
<button
type="button"
onClick={onViewDetails}
className="rounded-md border border-border bg-background px-2.5 py-1 text-[11px] font-medium text-foreground transition-colors hover:bg-accent"
>
{detailsLabel}
</button>
)}
{onRetry && (
<button
type="button"
onClick={onRetry}
className="rounded-md border border-border bg-background px-2.5 py-1 text-[11px] font-medium text-foreground transition-colors hover:bg-accent"
>
{retryLabel}
</button>
)}
{onClose && (
<button
type="button"
onClick={handleClose}
aria-label="Close"
className="rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-3.5" aria-hidden />
</button>
)}
</div>
</motion.div>
)}
</AnimatePresence>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Connectivity Error
## Summary
A dismissible banner that surfaces a network connectivity failure with a short description and two recovery actions — "View details" and "Try again". Spans the full width of its container as a single row, appears inline in the layout (not as a toast or modal), and exits with a fade when dismissed or retried.
## When to use
- When the AI product loses its connection to the backend mid-session or on page load, and the user needs to know before submitting another prompt.
- When the error may be caused by VPN, proxy, or local network configuration — not just a transient blip — and the user might need to investigate before retrying.
- When both a passive "View details" path and an immediate "Try again" action are meaningful.
## When not to use
- Brief transient failures that auto-recover within seconds — surface a spinner instead and only show this if recovery fails after a threshold.
- Hard authentication or quota failures — use a more specific error pattern (Rate Limit, account error) rather than a generic connectivity card.
- When there is no meaningful "View details" target — omit that action rather than linking to a dead end.
## Anatomy
- **Container**: Single row, full width, small border radius, no shadow — reads as a slim banner rather than a card.
- **Icon**: `WifiOff` (or similar offline icon) at 14px, next to the title. Decorative — `aria-hidden`.
- **Title**: Short, factual label ("Connection lost"). Small, semibold, text-foreground.
- **Description**: One short sentence, inline after the title on the same row. Small, muted text, truncates if the row runs out of space.
- **View details button**: Small secondary bordered button in the trailing action group. Omitted if `onViewDetails` is not provided.
- **Try again button**: Small secondary bordered button in the trailing action group. Omitted if `onRetry` is not provided.
- **Close button**: Icon-only × button at the far right of the action group, hidden if `onClose` is not provided.
## Behavior
- Mounts with a short upward fade (opacity 0→1, y −6→0, 200 ms ease-out).
- Exits with the reverse animation when the close button is clicked.
- Pressing "Try again" should trigger the parent's retry logic; the demo resets the key so the card reappears after it has been dismissed.
- Internal `visible` state gates the `AnimatePresence` exit — callers control re-showing by re-mounting (key reset) or by not providing `onClose`.
- The card does not auto-dismiss or countdown — the user must act.
## Content guidelines
- Title: plain noun phrase describing the state, not an error code. "Connection lost" not "ERR_NETWORK_CHANGED" or "Request failed (503)".
- Description: one sentence, action-oriented. Lead with what to check, not what went wrong. "Check your internet connection, VPN or proxy and try again."
- "Try again" is always the primary recovery; "View details" is optional and should link to a diagnostic panel or log, not an alert.
- Keep both button labels under 20 characters — they share a single row.
## Accessibility
- The container has `role="alert"` and `aria-live="assertive"` so screen readers announce it immediately on mount.
- The close button has `aria-label="Close"`.
- The wifi-off icon is `aria-hidden` — the title carries the semantic meaning.
## Related patterns
- Rate Limit — for quota-exceeded states, not connectivity failures.
- Partial Response — for responses cut short by the server, not by a network drop.
- Console Error Card — for surfacing developer-facing browser errors, not end-user connectivity issues.
Response Compare
A side-by-side pair of response panels with independent regenerate and a single preferred pick.
How does photosynthesis work?
Response A
Photosynthesis is the process plants use to convert light energy into chemical energy. Chlorophyll in the leaves absorbs sunlight, which drives a reaction that turns water and carbon dioxide into glucose and oxygen. The glucose fuels the plant's growth, and the oxygen is released as a byproduct.
Response B
Plants make their own food through photosynthesis. Using sunlight captured by chlorophyll, they combine CO2 from the air with water drawn up through their roots. This produces glucose for energy and releases oxygen into the atmosphere as a waste product.
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { Check, Copy, RotateCcw, Sparkles } from "lucide-react";
import { cn } from "@/lib/utils";
export interface CompareResponse {
id: string;
label: string;
content: string;
}
export interface ResponseCompareProps {
prompt?: string;
responses: [CompareResponse, CompareResponse];
onPick?: (id: string) => void;
onRegenerate?: (id: string) => void;
className?: string;
}
export function ResponseCompare({ prompt, responses, onPick, onRegenerate, className }: ResponseCompareProps) {
const [pickedId, setPickedId] = React.useState<string | null>(null);
function handlePick(id: string) {
setPickedId(id);
onPick?.(id);
}
function handleRegenerate(id: string) {
setPickedId((current) => (current === id ? null : current));
onRegenerate?.(id);
}
return (
<div className={cn("w-full", className)}>
{prompt && <p className="mb-3 text-sm text-muted-foreground">{prompt}</p>}
<div role="radiogroup" aria-label="Preferred response" className="grid grid-cols-1 gap-3 md:grid-cols-2">
{responses.map((response) => (
<ResponsePanel
key={response.id}
response={response}
picked={pickedId === response.id}
dimmed={pickedId !== null && pickedId !== response.id}
onPick={() => handlePick(response.id)}
onRegenerate={() => handleRegenerate(response.id)}
/>
))}
</div>
</div>
);
}
function ResponsePanel({
response,
picked,
dimmed,
onPick,
onRegenerate,
}: {
response: CompareResponse;
picked: boolean;
dimmed: boolean;
onPick: () => void;
onRegenerate: () => void;
}) {
const [copied, setCopied] = React.useState(false);
async function handleCopy() {
await navigator.clipboard.writeText(response.content);
setCopied(true);
window.setTimeout(() => setCopied(false), 1500);
}
return (
<div
role="radio"
aria-checked={picked}
aria-label={response.label}
tabIndex={0}
onClick={onPick}
onKeyDown={(e) => {
if (e.key === "Enter" || e.key === " ") {
e.preventDefault();
onPick();
}
}}
className={cn(
"flex h-80 cursor-pointer flex-col overflow-hidden rounded-2xl border bg-card transition-opacity outline-none",
picked ? "border-primary ring-1 ring-primary" : "border-border hover:border-foreground/20",
dimmed && "opacity-60",
"focus-visible:ring-2 focus-visible:ring-ring"
)}
>
<div className="flex items-center justify-between gap-2 border-b px-4 py-2.5">
<span className="text-xs font-medium">{response.label}</span>
{picked && (
<motion.span
initial={{ opacity: 0, scale: 0.9 }}
animate={{ opacity: 1, scale: 1 }}
className="flex items-center gap-1 rounded-full bg-primary/10 px-2 py-0.5 text-xs font-medium text-primary"
>
<Sparkles className="size-3" />
Preferred
</motion.span>
)}
</div>
<div className="flex-1 overflow-y-auto px-4 py-3">
<p className="whitespace-pre-wrap text-sm leading-relaxed text-foreground/90">{response.content}</p>
</div>
<div className="flex items-center justify-between gap-2 border-t px-3 py-2">
<div className="flex items-center gap-0.5 text-muted-foreground">
<IconButton
label="Copy"
onClick={(e) => {
e.stopPropagation();
handleCopy();
}}
>
{copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
</IconButton>
<IconButton
label={`Regenerate ${response.label}`}
onClick={(e) => {
e.stopPropagation();
onRegenerate();
}}
>
<RotateCcw className="size-3.5" />
</IconButton>
</div>
<button
type="button"
onClick={(e) => {
e.stopPropagation();
onPick();
}}
className={cn(
"rounded-full border px-3 py-1 text-xs font-medium transition-colors",
picked ? "border-primary bg-primary text-primary-foreground" : "hover:bg-accent"
)}
>
{picked ? "Chosen" : "Choose this"}
</button>
</div>
</div>
);
}
function IconButton({
label,
onClick,
children,
}: {
label: string;
onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
children: React.ReactNode;
}) {
return (
<button
type="button"
onClick={onClick}
aria-label={label}
className="rounded-md p-1.5 transition-colors hover:bg-accent hover:text-foreground"
>
{children}
</button>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Response Compare
## Summary
A side-by-side pair of full response panels answering the same prompt, letting the person read both in full and pick the one they prefer. It turns "regenerate and hope" into a direct A/B choice, and is the natural expansion of thumbs up/down when there are two concrete candidates to weigh instead of one.
## When to use
- Comparing two model outputs (different models, prompts, temperatures, or system prompts) for the same input, where quality is genuinely close and worth a human call.
- Eval/preference-collection tooling that needs an explicit, recorded choice between two candidates rather than a vague quality signal.
- Regeneration flows where showing the new answer next to the old one (instead of replacing it) helps the person decide which to keep.
## When not to use
- When one answer is obviously wrong (factual error, refusal, empty output) — surface an error state or a single corrected answer instead of asking someone to compare against garbage.
- More than two candidates at once. Side-by-side reading breaks down past two full-length responses; use a ranked list or a carousel instead.
- Low-stakes, low-effort answers (a one-line lookup, a short factual reply) where the ceremony of comparing outweighs the value of choosing.
## Anatomy
- Optional shared prompt header showing the question both responses are answering.
- Two response panels in a row (stacking vertically on narrow viewports): a label (model/version name or "Response A"/"Response B"), the response body, and a footer action row (Copy, Regenerate, "Choose this").
- A selection state: the chosen panel gets a visibly distinct border/highlight and a "Preferred" badge; the other panel recedes (reduced emphasis) without disappearing.
## Behavior
- The whole panel is a single click/tap target for selecting it, not just the "Choose this" button — clicking anywhere on a panel's card (its header, body text, or empty space) picks it, the same as clicking the explicit button.
- Copy and Regenerate stay independent actions that don't select the panel — clicking either one acts on that panel's content without also making it the preferred choice, so a person can copy or regenerate one side while still undecided.
- Selecting a panel is a single choice between the two — choosing one always deselects the other; it is not two independent toggles.
- The choice is changeable: picking the other panel (by clicking it anywhere, or its "Choose this" button) after the fact swaps the preferred state, it doesn't require undoing the first choice explicitly.
- Regenerating one panel only replaces that panel's content and clears any existing selection — it never touches the other panel's content.
- Both panels render at equal height with independently scrolling content, so a long response on one side doesn't push the other side's footer out of alignment or off-screen.
- Copy acts on that panel's response text only.
## Content guidelines
- Label panels neutrally ("Response A" / "Response B", or the model name) — avoid labels that imply a quality judgment before the person has read either one.
- Keep the "Choose this" action's label consistent across both panels; don't rephrase it based on which one you'd expect to win.
## Accessibility
- Group the two panels with `role="radiogroup"` and expose each panel itself as `role="radio"` with `aria-checked` and a focusable `tabindex`, since the whole card — not just its "Choose this" button — is the selectable unit and exactly one of two options can be selected.
- Each panel needs a visible hover/focus affordance (e.g. a border change, a focus ring) so the card reads as clickable, not just as a static container with buttons inside it.
- The nested Copy and Regenerate buttons must stop click/keyboard events from also triggering the panel's own selection, so using them never has the side effect of picking that panel.
- Selecting via keyboard must work on the panel itself (Enter or Space while it's focused), not only by tabbing all the way to the "Choose this" button.
- Each panel's response text must be reachable by screen reader in a sensible order — visual left/right placement shouldn't be the only thing separating them; label each region (e.g. `aria-label="Response A"`) so assistive tech announces which one is being read.
- The preferred badge's meaning must not rely on color/border alone — include visible text ("Preferred") or an icon with an accessible name.
- All actions (Copy, Regenerate, Choose this, and selecting the panel itself) must be reachable and operable by keyboard.
## Related patterns
- Chat Bubble with Actions — the single-response equivalent (thumbs up/down, Regenerate) for when there's one reply to judge rather than two to choose between.
- Diff Summary Card — a different kind of side-by-side comparison (before/after a batch of file edits) rather than two independent generations.
Confidence Indicator
A badge or inline dot signaling how sure an AI answer or extraction is.
Badge, with calibrated score
Inline dot, per-claim
The invoice total is $4,210.00, due on the last business day of the month.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { ChevronDown } from "lucide-react";
import { cn } from "@/lib/utils";
export type ConfidenceLevel = "high" | "medium" | "low";
const LEVEL_CONFIG: Record<
ConfidenceLevel,
{ label: string; bars: number; barColor: string; dotColor: string }
> = {
high: {
label: "High confidence",
bars: 3,
barColor: "text-emerald-600 dark:text-emerald-400",
dotColor: "bg-emerald-500",
},
medium: {
label: "Medium confidence",
bars: 2,
barColor: "text-amber-600 dark:text-amber-400",
dotColor: "bg-amber-500",
},
low: {
label: "Low confidence",
bars: 1,
barColor: "text-red-600 dark:text-red-400",
dotColor: "bg-red-500",
},
};
export interface ConfidenceIndicatorProps {
level: ConfidenceLevel;
/** Overrides the default "High/Medium/Low confidence" label. */
label?: string;
/** One short, specific sentence explaining the level. Shown in an expandable disclosure (badge variant) or as the tooltip/accessible name (dot variant). */
reason?: string;
/** A calibrated 0-100 score to display alongside the band. Only pass this if the number is real — see pattern content guidelines. */
percentage?: number;
/** "badge" (default) for a standalone claim/response; "dot" for inline placement next to a word or value. */
variant?: "badge" | "dot";
className?: string;
}
export function ConfidenceIndicator({
level,
label,
reason,
percentage,
variant = "badge",
className,
}: ConfidenceIndicatorProps) {
const config = LEVEL_CONFIG[level];
const text = label ?? config.label;
if (variant === "dot") {
return <ConfidenceDot level={level} text={text} reason={reason} className={className} />;
}
return (
<ConfidenceBadge
level={level}
text={text}
reason={reason}
percentage={percentage}
className={className}
/>
);
}
function ConfidenceBadge({
level,
text,
reason,
percentage,
className,
}: {
level: ConfidenceLevel;
text: string;
reason?: string;
percentage?: number;
className?: string;
}) {
const [expanded, setExpanded] = React.useState(false);
const config = LEVEL_CONFIG[level];
const canExpand = Boolean(reason);
return (
<div className={cn("inline-flex max-w-full flex-col items-start", className)}>
<button
type="button"
onClick={() => canExpand && setExpanded((v) => !v)}
aria-expanded={canExpand ? expanded : undefined}
className={cn(
"inline-flex items-center gap-1.5 rounded-full border bg-card px-2.5 py-1 text-xs font-medium text-foreground transition-colors",
canExpand ? "cursor-pointer hover:bg-accent" : "cursor-default"
)}
>
<SignalBars level={level} className={config.barColor} />
<span>{text}</span>
{typeof percentage === "number" && (
<span className="text-muted-foreground">· {Math.round(percentage)}%</span>
)}
{canExpand && (
<ChevronDown
className={cn("size-3 text-muted-foreground transition-transform", expanded && "rotate-180")}
aria-hidden
/>
)}
</button>
<AnimatePresence initial={false}>
{canExpand && expanded && (
<motion.p
initial={{ opacity: 0, height: 0 }}
animate={{ opacity: 1, height: "auto" }}
exit={{ opacity: 0, height: 0 }}
transition={{ duration: 0.15, ease: "easeOut" }}
className="overflow-hidden pl-1 pt-1.5 text-xs text-muted-foreground"
>
{reason}
</motion.p>
)}
</AnimatePresence>
</div>
);
}
function ConfidenceDot({
level,
text,
reason,
className,
}: {
level: ConfidenceLevel;
text: string;
reason?: string;
className?: string;
}) {
const config = LEVEL_CONFIG[level];
const accessibleName = reason ? `${text}: ${reason}` : text;
return (
<span
role="img"
aria-label={accessibleName}
title={accessibleName}
className={cn("inline-flex size-2 shrink-0 translate-y-[-1px] rounded-full", config.dotColor, className)}
/>
);
}
function SignalBars({ level, className }: { level: ConfidenceLevel; className?: string }) {
const filled = LEVEL_CONFIG[level].bars;
const heights = [5, 8, 11];
return (
<span className="flex items-end gap-0.5" aria-hidden>
{heights.map((height, i) => (
<span
key={height}
style={{ height }}
className={cn("w-1 rounded-sm", i < filled ? cn("bg-current", className) : "bg-muted-foreground/25")}
/>
))}
</span>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Confidence Indicator
## Summary
A small visual signal attached to an AI-generated claim, answer, or extraction that communicates how sure the system is — as a qualitative band (High / Medium / Low), not a fabricated precise number. Comes in two shapes: a labeled badge for a whole response or block, and a compact dot for an inline, per-claim signal inside running text.
## When to use
- Next to an answer, classification, or extraction whose correctness genuinely varies (a document field extraction, an OCR read, a retrieval match, a generated label).
- Anywhere a low-confidence result would otherwise look identical to a high-confidence one and the user could act on it without checking.
- Per-claim, inline, when a single response mixes well-supported and shaky statements (use the dot variant next to the specific sentence or value, not the whole message).
## When not to use
- On every single response by default — if confidence is uniformly high or the system has no real signal for it, showing the indicator anyway trains users to ignore it.
- As a substitute for actually improving the answer. A low-confidence badge is not a fix for a bad retrieval or a weak extraction; use it as a signal, and pair it with a way to verify or correct (a source link, an edit affordance), not just a color.
- With a precise percentage the underlying model doesn't actually produce or that isn't calibrated (see Content guidelines).
## Anatomy
- Signal bars: three small bars of increasing height; the number filled (1/2/3) encodes the level. Decorative only — never the sole carrier of meaning.
- Label: the actual meaning in words — "High confidence", "Medium confidence", "Low confidence", or a domain-specific override ("Likely correct", "Needs review").
- Optional reason disclosure: a short, specific explanation ("Only one source mentions this date"), revealed on click/tap for the badge variant. Omit if there's nothing specific to say — don't invent a generic filler reason.
- Dot variant: the signal bars collapse to a single small colored dot for inline placement next to a word or value, with the level/reason available via title text or an adjacent tooltip rather than a visible label (there's no room for one inline).
## Behavior
- Static by default — it reflects a value computed once, it doesn't animate or update on its own.
- The badge variant's reason (when provided) is collapsed by default and expands in place on click; it never opens as a popover that covers surrounding content.
- Clicking the dot variant (when it carries a reason) opens the same kind of disclosure, anchored near the dot.
- Never interactive in a way that changes the underlying confidence — this component only displays a value it's given.
## Content guidelines
- Prefer three bands (High/Medium/Low) over a numeric percentage. Most systems don't have a genuinely calibrated confidence score, and a number like "87%" implies precision that misleads more than a band does.
- If you do show a number, it must come from an actually calibrated source (e.g., a model's real logprob-derived score, a retrieval similarity above a validated threshold) — never a number invented to look precise.
- Reason text is one short, concrete sentence about *why* the confidence is what it is, not a restatement of the label ("Low confidence" → reason should not be "This has low confidence").
- Low confidence should read as informative, not alarming — this is a "double-check this" signal, not an error.
## Accessibility
- Never convey the level by color alone — the text label (badge variant) or accessible name (dot variant, via `aria-label`/`title`) must state it in words for colorblind users and screen readers.
- The signal-bars glyph is `aria-hidden` — it's decorative reinforcement of the label, not an independent source of information.
- The reason disclosure toggle needs `aria-expanded` and, ideally, is a real `<button>` so it's reachable and operable by keyboard.
## Related patterns
- Inline Citation — when the reason for low confidence is "check the source," a citation marker is often a better fix than a bare confidence dot.
- Tool Approval — for actions (not claims) where uncertainty should gate execution rather than just being displayed.
Voice Waveform
A live amplitude waveform while the AI listens or speaks.
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { cn } from "@/lib/utils";
export type VoiceWaveformState = "idle" | "listening" | "speaking";
export interface VoiceWaveformProps {
state: VoiceWaveformState;
/**
* Live amplitude levels (0-1), one per bar, sampled from a real audio
* source (e.g. an AnalyserNode) by the caller on each animation frame.
* When omitted, the waveform drives itself with a synthetic idle rhythm —
* useful for prototypes before real audio is wired up.
*/
levels?: number[];
barCount?: number;
className?: string;
}
const STATE_COLOR: Record<VoiceWaveformState, string> = {
idle: "bg-muted-foreground/30",
listening: "bg-sky-500 dark:bg-sky-400",
speaking: "bg-foreground",
};
const STATE_LABEL: Record<VoiceWaveformState, string> = {
idle: "Voice input idle",
listening: "Listening",
speaking: "Speaking",
};
export function VoiceWaveform({ state, levels, barCount = 27, className }: VoiceWaveformProps) {
const synthetic = useSyntheticLevels(barCount, state);
const active = levels ?? synthetic;
return (
<div
role="img"
aria-label={STATE_LABEL[state]}
className={cn("flex h-10 items-center justify-center gap-[3px]", className)}
>
{Array.from({ length: barCount }).map((_, i) => {
const height = state === "idle" ? 3 : Math.max(3, Math.round((active[i] ?? 0) * 36));
return (
<motion.span
key={i}
className={cn("w-[3px] shrink-0 rounded-full", STATE_COLOR[state])}
animate={{ height }}
transition={{ duration: 0.15, ease: "easeOut" }}
/>
);
})}
</div>
);
}
/** Generates a plausible-looking amplitude trace when the caller has no real audio source to sample yet. */
function useSyntheticLevels(barCount: number, state: VoiceWaveformState) {
const reducedMotion = usePrefersReducedMotion();
// Idle and reduced-motion levels are pure functions of the inputs, so they're
// derived directly rather than pushed into state from an effect.
const staticLevels = React.useMemo(() => {
if (state === "idle") return Array(barCount).fill(0);
if (reducedMotion) return Array.from({ length: barCount }, (_, i) => 0.3 + 0.2 * Math.sin(i / 2));
return null;
}, [barCount, state, reducedMotion]);
const [animatedLevels, setAnimatedLevels] = React.useState<number[]>(() => Array(barCount).fill(0));
React.useEffect(() => {
if (staticLevels) return;
const ceiling = state === "speaking" ? 0.95 : 0.7;
const id = window.setInterval(() => {
setAnimatedLevels(Array.from({ length: barCount }, () => Math.random() * ceiling + 0.05));
}, 120);
return () => window.clearInterval(id);
}, [barCount, state, staticLevels]);
return staticLevels ?? animatedLevels;
}
function usePrefersReducedMotion() {
const [reduced, setReduced] = React.useState(() =>
typeof window !== "undefined" ? window.matchMedia("(prefers-reduced-motion: reduce)").matches : false
);
React.useEffect(() => {
const mql = window.matchMedia("(prefers-reduced-motion: reduce)");
const handler = () => setReduced(mql.matches);
mql.addEventListener("change", handler);
return () => mql.removeEventListener("change", handler);
}, []);
return reduced;
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Voice Waveform
## Summary
A row of amplitude bars that visualizes live audio while a voice conversation is active — either the user's mic input while the system listens, or the system's own audio while it speaks. The bar heights track real signal energy, so the shape is never decorative alone: it's the one piece of the UI that proves audio is actually flowing.
## When to use
- Anywhere audio is actively being captured or played back in a voice interface (a voice mode, a call-style assistant, a dictation composer) and the user benefits from seeing that the mic or speaker is live.
- Paired with Listening State as the "is it working" confirmation once capture has actually started — Listening State signals the mode, this component proves signal is coming through.
- As the visual body of a "speaking" indicator while an assistant's audio response plays, so users can see when it finishes talking without relying on audio alone.
## When not to use
- As a fake "always animating" decoration with no real amplitude behind it — an idle shimmer belongs to a loader pattern (see Thinking Loader), not this one. If there's no live level to show, use the `idle` state's flat bars, don't fabricate motion.
- For a static, already-recorded audio clip's waveform (e.g. a voice message you can scrub) — that's a seek/scrubber component with a fixed waveform image, a different pattern than this live, continuously-updating one.
- When there is no audio at all in the interaction — this is specifically for voice, not a generic "activity" indicator.
## Anatomy
- Bars: a fixed-count row of thin, rounded-cap bars, evenly spaced, vertically centered so taller bars grow symmetrically up and down from the middle.
- Color by state: idle bars sit low and muted; listening bars pick up an accent color (distinct from the assistant's own color) so users can tell "you're being heard" apart from "it's replying"; speaking bars use the foreground/brand color.
## Behavior
- Bar heights update on every amplitude sample from the real audio source (an `AnalyserNode`, a WebRTC audio track, or the transport's own level events) — each bar eases to its new height rather than snapping, so the row reads as a continuous waveform instead of a flicker.
- `idle`: bars sit at a minimum flat height with no motion — audio isn't flowing.
- `listening`: bars react to the user's mic input in real time.
- `speaking`: bars react to the assistant's outgoing audio in real time.
- The moment audio stops (silence, mic muted, playback ends), bars settle back toward the idle floor rather than freezing mid-peak.
- Never mix live sampled levels with synthetic randomness in the same instance — a prototype without real audio wired up yet should look plausibly alive, but once a real level source exists, use it exclusively.
## Content guidelines
- N/A — this pattern carries no text content itself; pair it with a label (see Listening State) when the mode itself needs to be named.
## Accessibility
- Give the container an accessible name via `role="img"` and `aria-label` stating the current state in words ("Listening", "Speaking", "Voice input idle") — the bars themselves are purely visual and carry no independent semantic content.
- Respect `prefers-reduced-motion`: replace the rapid per-sample bar animation with a gentle static or slow-moving pattern that still communicates "audio is active" without the flicker.
- Don't rely on the waveform alone to signal turn-taking (who's talking) — pair it with a persistent state label or speaker indicator for screen reader users and anyone not watching closely.
## Related patterns
- Listening State — the broader "the system is capturing your voice" indicator this waveform's `listening` state visualizes the input for.
- Live Transcript — shows what the captured audio actually contained, once transcribed; use alongside this component so users get both the raw signal and the recognized text.
Listening State
A pulsing mic indicator showing the AI is actively listening.
Listening…
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { Mic, Square } from "lucide-react";
import { cn } from "@/lib/utils";
export interface ListeningStateProps {
/** Whether the mic is actively capturing audio. Set false for a paused/muted variant with no ripple. */
active?: boolean;
label?: string;
onStop?: () => void;
className?: string;
}
export function ListeningState({
active = true,
label = "Listening…",
onStop,
className,
}: ListeningStateProps) {
return (
<div className={cn("flex flex-col items-center gap-3", className)}>
<div
className={cn(
"relative flex size-12 shrink-0 items-center justify-center rounded-full transition-colors",
active ? "text-sky-500" : "text-muted-foreground"
)}
>
{active && (
<motion.span
aria-hidden
className="absolute inset-0 rounded-full bg-sky-500/20"
animate={{ scale: [1, 1.4], opacity: [0, 0.6, 0] }}
transition={{ duration: 1.2, repeat: Infinity, ease: "easeOut" }}
/>
)}
<Mic className="size-6" aria-hidden />
</div>
<div className="flex items-center gap-2">
<span aria-live="polite" className="text-sm text-muted-foreground">
{active ? label : "Paused"}
</span>
{onStop && (
<button
type="button"
onClick={onStop}
aria-label="Stop listening"
className="rounded-full p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<Square className="size-3" aria-hidden fill="currentColor" />
</button>
)}
</div>
</div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Listening State
## Summary
A dedicated visual state — a pulsing mic glyph with an outward ripple, a status label, and a stop control — that tells the user the system is actively capturing their voice right now. It's the "your mic is live" moment in a voice interface, distinct from showing what was heard (Live Transcript) or how loud it is (Voice Waveform).
## When to use
- The instant a voice interface starts capturing audio, whether triggered by a push-to-talk press, a wake word, or an always-on mode — show this before or alongside any transcript text appears.
- As the anchor state users glance at to confirm "yes, it's hearing me" separate from reading a waveform or transcript, especially for brief utterances where a transcript hasn't rendered yet.
- Any time capture is paused (muted, held) but the session is still open — use the inactive variant rather than removing the component entirely, so the control to resume stays in place.
## When not to use
- While the assistant is talking, not the user — this state specifically means "capturing your voice." Use a distinct speaking indicator (e.g. Voice Waveform in its `speaking` state) for that half of the turn.
- As a permanent idle-mode decoration when no capture session is open — it implies the mic is live; don't show it before the user has actually started or been prompted to speak.
- Stacked with a second, separate ripple/pulse indicator for the same mic state — one active listening indicator per view.
## Anatomy
- Mic glyph: a plain (unfilled) microphone icon, tinted with an accent color while active and muted gray when paused — not a solid-filled badge. This mirrors Prompt Bar's dictation mic exactly, so the two read as the same control at any size.
- Ripple: a single translucent ring, sized and centered on the glyph itself (not a separate oversized container), that expands outward a short distance and fades to nothing, looping continuously. Because the glyph has no opaque fill behind it, the full ring is visible from the start of each cycle, not just the portion that clears a solid background.
- Status label: a short live-updating phrase ("Listening…", "Paused") directly below the glyph.
- Stop control: a small button beside the label that ends capture — always reachable without needing to find a separate toolbar.
## Behavior
- The ripple only animates while `active` is true; pausing or muting freezes the glyph in a flat, static state with the ripple removed rather than slowed down, so "paused" is unambiguous at a glance.
- Clicking stop ends the capture session immediately — no confirmation step, since capture is easy to restart and holding it hostage behind a dialog adds friction to a moment that's meant to feel instant.
- The label updates in place (no layout shift) when switching between active and paused text.
- On resume, restart the ripple animation from its initial state rather than resuming mid-cycle, so the "just started listening" cue is clear each time.
- Drive the ripple with a plain keyframe `animate` (scale `[1, 1.4]`, opacity `[0, 0.6, 0]`, 1.2s, `easeOut`, infinite repeat, no separate `initial` or per-instance `delay`) — this is copied verbatim from Prompt Bar's dictation mic, down to the ring's low-alpha color treatment (`/20`). Staggering multiple rings via `delay` on an infinitely-repeating animation is fragile and prone to drifting out of sync; one ring on a clean loop reads just as clearly as "listening."
- Fade the ripple's opacity in from 0 and back out to 0 within each cycle rather than starting it at full strength — a ring that starts fully visible and simply expands has to hard-reset to a small, bold ring the instant it disappears, which reads as the ring suddenly shrinking rather than continuing to expand. Fading through 0 at both ends of the loop makes the reset invisible.
## Content guidelines
- Keep the label to a short present-participle phrase ("Listening…"); avoid restating instructions the user already knows ("Speak now to ask a question").
- The paused label states the state plainly ("Paused"), not an instruction to act ("Tap mic to continue") — pair any needed instruction with a visible affordance instead of relying on the label alone.
## Accessibility
- Wrap the label in `aria-live="polite"` so a screen reader announces the active/paused transition without needing focus.
- The stop control must be a real, focusable `<button>` with an `aria-label` ("Stop listening") since it carries no visible text.
- Respect `prefers-reduced-motion`: keep the glyph's color state (it's the actual status signal) but suppress or shorten the expanding ripple.
- Never rely on the ripple animation alone to convey "active" — the accent color and label both carry that meaning independently.
## Related patterns
- Prompt Bar / Prompt Bar Pro — their composer's dictation mic button uses this same single-ring ripple technique at a smaller scale; keep both in sync if the ripple's timing or easing ever changes.
- Voice Waveform — shows the live amplitude of the audio this state confirms is being captured; often shown together, with the waveform inside or beside the mic glyph.
- Live Transcript — shows what capture actually produced once speech is recognized; this state covers the moment before or alongside that text appearing.
Live Transcript
A streaming, speaker-labeled transcription of a voice conversation.
Waiting for speech…
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { ArrowDown, Mic } from "lucide-react";
import { cn } from "@/lib/utils";
export interface TranscriptSegment {
id: string;
speaker: "user" | "assistant";
text: string;
/** Interim speech-recognition results render lighter and can still be replaced; omit or set true once the segment is committed. */
final?: boolean;
}
export interface LiveTranscriptProps {
segments: TranscriptSegment[];
/** Whether the mic is actively capturing right now — drives the live cursor and the region's aria-live behavior. */
active?: boolean;
className?: string;
}
const SPEAKER_LABEL: Record<TranscriptSegment["speaker"], string> = {
user: "You",
assistant: "Assistant",
};
export function LiveTranscript({ segments, active = true, className }: LiveTranscriptProps) {
const [pinnedToBottom, setPinnedToBottom] = React.useState(true);
const bodyRef = React.useRef<HTMLDivElement>(null);
React.useEffect(() => {
if (!pinnedToBottom) return;
const el = bodyRef.current;
if (el) el.scrollTop = el.scrollHeight;
}, [segments, pinnedToBottom]);
function handleScroll() {
const el = bodyRef.current;
if (!el) return;
setPinnedToBottom(el.scrollHeight - el.scrollTop - el.clientHeight < 24);
}
function jumpToLatest() {
const el = bodyRef.current;
if (el) el.scrollTop = el.scrollHeight;
setPinnedToBottom(true);
}
return (
<div className={cn("relative w-full overflow-hidden rounded-2xl border bg-card", className)}>
<div
ref={bodyRef}
onScroll={handleScroll}
role="log"
aria-live={active ? "polite" : "off"}
className="max-h-72 space-y-3 overflow-y-auto px-4 py-3.5"
>
{segments.length === 0 ? (
<p className="flex items-center gap-2 text-sm text-muted-foreground">
<Mic className="size-3.5" aria-hidden />
Waiting for speech…
</p>
) : (
segments.map((segment) => (
<p key={segment.id} className="text-sm leading-relaxed">
<span className="mr-1.5 text-xs font-medium text-muted-foreground">
{SPEAKER_LABEL[segment.speaker]}
</span>
<span className={cn(segment.final === false && "text-muted-foreground italic")}>
{segment.text}
{segment.final === false && active && <BlinkingCursor />}
</span>
</p>
))
)}
</div>
{!pinnedToBottom && (
<button
type="button"
onClick={jumpToLatest}
className="absolute bottom-2.5 left-1/2 flex -translate-x-1/2 items-center gap-1 rounded-full bg-foreground px-2.5 py-1 text-xs text-background shadow-sm"
>
<ArrowDown className="size-3" aria-hidden />
Jump to latest
</button>
)}
</div>
);
}
function BlinkingCursor() {
return (
<motion.span
aria-hidden
className="ml-0.5 inline-block h-3 w-[2px] translate-y-px bg-muted-foreground"
animate={{ opacity: [1, 1, 0, 0] }}
transition={{ duration: 1, repeat: Infinity, times: [0, 0.5, 0.5, 1], ease: "linear" }}
/>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Live Transcript
## Summary
A scrolling, speaker-labeled log of a voice conversation's recognized text, updated as speech-to-text results arrive: interim (not-yet-final) text renders lighter with a live cursor and can still be corrected in place, while finalized text settles into normal styling. It's the readable record of what Listening State and Voice Waveform are only signaling is happening.
## When to use
- Any voice conversation where users benefit from a text record of what was said — accessibility for users who can't rely on audio alone, a way to verify the system heard correctly, or a scrollback for a conversation that moved fast.
- Alongside Listening State and/or Voice Waveform, as the content layer under those activity signals — this shows what was captured, they show that capture is happening.
- When speech recognition produces genuinely interim results (a streaming ASR API) that later get corrected — the interim/final distinction is the whole point of this pattern; don't reach for it if your transcription only ever arrives as complete, final utterances.
## When not to use
- For a static, already-complete transcript of a past conversation (e.g. a call summary page) — render that as plain finalized text; the interim styling, live cursor, and auto-scroll are all specifically for a conversation still in progress.
- As the only signal that the mic is live — pair it with Listening State, since a transcript with no new lines yet looks identical to a stalled or disconnected session.
- For multi-party transcription needing more than two speaker roles or precise timestamps — this pattern's two-role (user/assistant) labeling is for a conversational voice agent, not a full meeting-transcription tool.
## Anatomy
- Log region: a scrollable container holding one paragraph per segment, auto-scrolling as new segments arrive.
- Speaker label: a short bold tag ("You", "Assistant") prefixing each segment so turns stay distinguishable without color-only cues.
- Interim segment: lighter, italicized text ending in a blinking cursor — visually marked as provisional and still subject to change.
- Final segment: normal-weight, normal-color text — settled, won't change again.
- Jump-to-latest control: appears only once the user has scrolled up away from the bottom, letting them return to the live edge without fighting the auto-scroll.
- Empty state: a muted "Waiting for speech…" line with a mic glyph, shown before any segment has arrived.
## Behavior
- New words append to the current speaker's interim segment in place — the same segment id gets replaced with updated text, it doesn't append as a new line for every partial result.
- The moment a segment finalizes, its styling settles (cursor removed, italics and muted color drop) and any further speech starts a new segment.
- The transcript auto-scrolls to the newest line only while the user hasn't manually scrolled away; scrolling up disables auto-scroll and reveals the jump-to-latest control, exactly like a running log or terminal stream.
- Never rewrites already-final text based on later context — once a segment is marked final, treat it as committed; corrections apply prospectively to the next segment, not retroactively.
## Content guidelines
- Speaker labels are short and consistent ("You" / "Assistant"), not the person's name or a role description that could vary turn to turn.
- Show interim text exactly as the recognizer produced it, including mid-word states — don't paper over recognition artifacts by delaying display until a cleaner result arrives, that just makes the system look unresponsive.
## Accessibility
- The log region needs `role="log"` with `aria-live="polite"` while active, so assistive tech announces new finalized content without interrupting — set it to `aria-live="off"` once the session ends so historical scrollback isn't re-announced.
- Don't rely on italics/color alone to mark interim text — screen readers won't distinguish it, so consider only announcing segments once they're final, avoiding a flood of in-progress announcements per word.
- The jump-to-latest control must be a real, focusable button; its label states the action ("Jump to latest"), not an icon alone.
- Respect `prefers-reduced-motion` for the blinking cursor — a static dash or steady low-opacity mark communicates "still live" without the flash.
## Related patterns
- Listening State — the capture-is-active signal this transcript's content is the output of.
- Voice Waveform — the raw amplitude visualization that pairs with this transcript's recognized text.
- Terminal Stream — the same auto-scroll/jump-to-latest scrolling-log mechanics, applied to command output instead of speech.
- Chat Bubble — once a segment finalizes, hand its text off to a Chat Bubble as the sent message rather than leaving it styled as a transcript segment; the two don't overlap in the same UI element.
Command Palette
A searchable ⌘K overlay for jumping to sessions or running quick actions.
Quick actions
Recent
↑↓SelectOpenEscClose
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { CornerDownLeft, Search, X } from "lucide-react";
import { cn } from "@/lib/utils";
export interface CommandPaletteItem {
id: string;
label: string;
icon?: React.ComponentType<{ className?: string }>;
meta?: string;
}
export interface CommandPaletteGroup {
label: string;
items: CommandPaletteItem[];
}
export interface CommandPaletteProps {
open: boolean;
onOpenChange: (open: boolean) => void;
groups: CommandPaletteGroup[];
placeholder?: string;
emptyLabel?: string;
onSelect?: (item: CommandPaletteItem) => void;
className?: string;
}
export function CommandPalette({
open,
onOpenChange,
groups,
placeholder,
emptyLabel,
onSelect,
className,
}: CommandPaletteProps) {
function close() {
onOpenChange(false);
}
return (
<AnimatePresence>
{open && (
<div className={cn("fixed inset-0 z-50 flex justify-center px-4 pt-[12vh]", className)}>
<motion.div
className="absolute inset-0 bg-black/40 backdrop-blur-sm"
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={{ duration: 0.15 }}
onClick={close}
aria-hidden
/>
<motion.div
initial={{ opacity: 0, y: -8, scale: 0.98 }}
animate={{ opacity: 1, y: 0, scale: 1 }}
exit={{ opacity: 0, y: -8, scale: 0.98 }}
transition={{ duration: 0.15, ease: "easeOut" }}
className="relative z-10 w-full max-w-lg"
>
<CommandPaletteWindow
groups={groups}
placeholder={placeholder}
emptyLabel={emptyLabel}
autoFocus
onSelect={(item) => {
onSelect?.(item);
close();
}}
onClose={close}
/>
</motion.div>
</div>
)}
</AnimatePresence>
);
}
export interface CommandPaletteWindowProps {
groups: CommandPaletteGroup[];
placeholder?: string;
emptyLabel?: string;
onSelect?: (item: CommandPaletteItem) => void;
onClose?: () => void;
autoFocus?: boolean;
className?: string;
}
/** The palette's search input, result list, and key-hint footer, without the modal chrome (backdrop, fixed positioning). Used by `CommandPalette` for the real overlay, and reusable on its own wherever a static, non-modal preview of the window is useful. */
export function CommandPaletteWindow({
groups,
placeholder = "Search or run a command...",
emptyLabel = "No matches",
onSelect,
onClose,
autoFocus = false,
className,
}: CommandPaletteWindowProps) {
const listId = React.useId();
const [query, setQuery] = React.useState("");
const [activeIndex, setActiveIndex] = React.useState(0);
const inputRef = React.useRef<HTMLInputElement>(null);
const listRef = React.useRef<HTMLDivElement>(null);
const visibleGroups = React.useMemo(() => filterGroups(groups, query), [groups, query]);
const flatItems = React.useMemo(() => visibleGroups.flatMap((g) => g.items), [visibleGroups]);
React.useEffect(() => {
if (autoFocus) {
const id = requestAnimationFrame(() => inputRef.current?.focus());
return () => cancelAnimationFrame(id);
}
}, [autoFocus]);
const prevActiveIndexRef = React.useRef<number | null>(null);
React.useEffect(() => {
const prevActiveIndex = prevActiveIndexRef.current;
prevActiveIndexRef.current = activeIndex;
if (prevActiveIndex === null || prevActiveIndex === activeIndex) return;
const row = listRef.current?.querySelector<HTMLElement>(`[data-index="${activeIndex}"]`);
row?.scrollIntoView({ block: "nearest" });
}, [activeIndex]);
function commit(item: CommandPaletteItem | undefined) {
if (!item) return;
onSelect?.(item);
}
function handleKeyDown(e: React.KeyboardEvent) {
if (e.key === "Escape") {
e.preventDefault();
onClose?.();
} else if (e.key === "ArrowDown") {
e.preventDefault();
setActiveIndex((i) => Math.min(i + 1, flatItems.length - 1));
} else if (e.key === "ArrowUp") {
e.preventDefault();
setActiveIndex((i) => Math.max(i - 1, 0));
} else if (e.key === "Enter") {
e.preventDefault();
commit(flatItems[activeIndex]);
}
}
return (
<div
role="dialog"
aria-modal="true"
aria-label="Command palette"
onKeyDown={handleKeyDown}
className={cn(
"flex h-fit max-h-[70vh] w-full flex-col overflow-hidden rounded-2xl border bg-popover shadow-2xl",
className
)}
>
<div className="flex items-center gap-2.5 border-b px-4 py-3.5">
<Search className="size-4 shrink-0 text-muted-foreground" aria-hidden />
<input
ref={inputRef}
role="combobox"
aria-expanded="true"
aria-controls={listId}
aria-activedescendant={flatItems[activeIndex] ? `${listId}-item-${flatItems[activeIndex].id}` : undefined}
value={query}
onChange={(e) => {
setQuery(e.target.value);
setActiveIndex(0);
}}
placeholder={placeholder}
className="flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"
/>
{onClose && (
<button
type="button"
onClick={onClose}
aria-label="Close"
className="shrink-0 rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-4" />
</button>
)}
</div>
<div id={listId} role="listbox" ref={listRef} className="min-h-0 flex-1 overflow-y-auto p-2">
{flatItems.length === 0 ? (
<p className="px-3 py-8 text-center text-sm text-muted-foreground">{emptyLabel}</p>
) : (
visibleGroups.map((group) => (
<div key={group.label} className="mb-2 last:mb-0">
<p className="px-3 py-1.5 text-xs font-medium text-muted-foreground">{group.label}</p>
{group.items.map((item) => {
const index = flatItems.indexOf(item);
const active = index === activeIndex;
const Icon = item.icon;
return (
<button
key={item.id}
id={`${listId}-item-${item.id}`}
data-index={index}
role="option"
aria-selected={active}
type="button"
onMouseEnter={() => setActiveIndex(index)}
onClick={() => commit(item)}
className={cn(
"flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left text-sm transition-colors",
active ? "bg-accent text-accent-foreground" : "text-foreground"
)}
>
{Icon && <Icon className="size-4 shrink-0 text-muted-foreground" aria-hidden />}
<span className="min-w-0 flex-1 truncate">{item.label}</span>
{item.meta && <span className="shrink-0 text-xs text-muted-foreground">{item.meta}</span>}
</button>
);
})}
</div>
))
)}
</div>
<div className="flex items-center gap-3 border-t px-4 py-2.5 text-xs text-muted-foreground">
<span className="flex items-center gap-1.5">
<Kbd>↑</Kbd>
<Kbd>↓</Kbd>
Select
</span>
<span className="flex items-center gap-1.5">
<Kbd>
<CornerDownLeft className="size-3" />
</Kbd>
Open
</span>
<span className="ml-auto flex items-center gap-1.5">
<Kbd>Esc</Kbd>
Close
</span>
</div>
</div>
);
}
function Kbd({ children }: { children: React.ReactNode }) {
return (
<kbd className="flex h-5 min-w-5 items-center justify-center rounded border bg-muted px-1 font-sans text-[10px] font-medium text-muted-foreground">
{children}
</kbd>
);
}
function filterGroups(groups: CommandPaletteGroup[], query: string): CommandPaletteGroup[] {
const trimmed = query.trim().toLowerCase();
if (!trimmed) return groups;
return groups
.map((group) => ({
...group,
items: group.items.filter((item) => item.label.toLowerCase().includes(trimmed)),
}))
.filter((group) => group.items.length > 0);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Command Palette
## Summary
A search-first overlay for jumping to or launching something — a session, a document, a command — without leaving the keyboard. A single input filters a short list of quick actions and recent items; arrow keys move the highlight, Enter commits it.
## When to use
- Switching between many similar items (sessions, chats, files, projects) faster than a sidebar or list view allows.
- Surfacing a small set of global actions ("New session", "New chat") alongside recent history in one place.
- Any surface that already has a keyboard-shortcut culture (⌘K launchers, IDE-style command bars).
## When not to use
- A handful of items (fewer than ~6) that fit comfortably in a visible list or dropdown — the overlay adds a step for no benefit.
- Destructive or multi-step actions (delete, bulk export). The palette commits on a single Enter; anything needing confirmation belongs in its own flow.
- As the only way to reach a primary action. Always keep a visible trigger (button, menu item) alongside the keyboard shortcut — the shortcut is an accelerator, not the sole path.
## Anatomy
- Backdrop (dims and blurs the page behind the palette, closes on click).
- Search input with a leading search icon and a close (×) button.
- Scrollable result list, grouped into labeled sections (e.g. "Quick actions", "Recent").
- Each row: optional leading icon, label (truncates), optional trailing meta text (timestamp, source).
- Footer hint bar: keyboard legend for select / open / close.
## Behavior
- Opens via an explicit trigger (button) and/or a global shortcut (⌘K / Ctrl+K); the trigger must remain visible even where the shortcut exists.
- The search input autofocuses the moment the palette opens.
- With an empty query, show the full grouped list (quick actions first, then recent items) — don't force typing before anything is visible.
- Typing filters items by label across all groups in place; groups with no matches collapse out entirely rather than showing an empty header.
- Arrow Up/Down move the highlighted row, clamped at the first/last item (no wraparound) so repeated key-holds don't overshoot silently.
- Hovering a row also updates the highlight, kept in sync with keyboard navigation.
- Enter commits the highlighted row; clicking a row commits it directly.
- Escape, a backdrop click, or the × button close the palette without committing.
- Closing resets the query and highlight so the next open starts fresh.
- The highlighted row auto-scrolls into view as it changes, so keyboard navigation never drifts off-screen in a long list.
## Content guidelines
- Row labels are the item's real name (a session title, a file name) — never a truncated ID or slug.
- Meta text is short and secondary: a relative timestamp ("Just now", "Last hour") or a compact source tag ("PR #52"). Never wrap it.
- Group labels are short nouns ("Quick actions", "Recent") — not instructions.
- The empty-results message is a plain statement ("No matches"), not a call to action.
## Accessibility
- Root overlay uses `role="dialog"` with `aria-modal="true"` and a descriptive `aria-label`.
- The input uses `role="combobox"` with `aria-expanded` and `aria-controls` pointing at the result list, plus `aria-activedescendant` tracking the highlighted row's id.
- The result list uses `role="listbox"`; each row is `role="option"` with `aria-selected` reflecting the current highlight.
- All interaction must work from the keyboard alone: focus starts in the input, arrow keys and Enter never require a pointer.
- Respect `prefers-reduced-motion` by skipping the backdrop fade and panel scale/slide.
## Related patterns
- None. This is a standalone navigation/launcher pattern, not part of an agent-status sequence.
Collaborative Presence
An avatar stack showing who has access to a shared record and who is actively viewing it right now.
Simulate who's viewing the record
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { cn } from "@/lib/utils";
export interface Collaborator {
id: string;
name: string;
role: string;
initials: string;
/** Tailwind background color class, e.g. "bg-violet-500" */
color: string;
isOnline: boolean;
}
export interface CollaborativePresenceProps {
collaborators: Collaborator[];
/** Max avatars shown before collapsing into "+N" chip. Default 4. */
visibleCap?: number;
className?: string;
}
export function CollaborativePresence({
collaborators,
visibleCap = 4,
className,
}: CollaborativePresenceProps) {
const [panelOpen, setPanelOpen] = React.useState(false);
const [hoveredId, setHoveredId] = React.useState<string | null>(null);
const containerRef = React.useRef<HTMLDivElement>(null);
const panelId = React.useId();
const sorted = React.useMemo(
() => [...collaborators].sort((a, b) => Number(b.isOnline) - Number(a.isOnline)),
[collaborators],
);
const visible = sorted.slice(0, visibleCap);
const overflowCount = Math.max(0, sorted.length - visibleCap);
const onlineCount = collaborators.filter((c) => c.isOnline).length;
React.useEffect(() => {
if (!panelOpen) return;
function onOutsideClick(e: MouseEvent) {
if (!containerRef.current?.contains(e.target as Node)) {
setPanelOpen(false);
}
}
document.addEventListener("mousedown", onOutsideClick);
return () => document.removeEventListener("mousedown", onOutsideClick);
}, [panelOpen]);
const tooltipsActive = !panelOpen;
return (
<div ref={containerRef} className={cn("flex flex-col items-end", className)}>
{/* Clickable avatar row */}
<button
type="button"
aria-expanded={panelOpen}
aria-controls={panelId}
aria-label="View collaborators"
onClick={() => {
setPanelOpen((v) => !v);
setHoveredId(null);
}}
className="flex items-center rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
>
<div className="flex -space-x-2">
<AnimatePresence initial={false} mode="popLayout">
{visible.map((collab, i) => (
<AvatarPip
key={collab.id}
collab={collab}
zIndex={visibleCap - i}
showTooltip={tooltipsActive && hoveredId === collab.id}
onMouseEnter={() => setHoveredId(collab.id)}
onMouseLeave={() => setHoveredId(null)}
/>
))}
</AnimatePresence>
</div>
{overflowCount > 0 && (
<div
className="relative ml-1 flex size-8 shrink-0 items-center justify-center rounded-full border-2 border-background bg-muted text-xs font-medium text-muted-foreground"
onMouseEnter={() => setHoveredId("__overflow")}
onMouseLeave={() => setHoveredId(null)}
>
+{overflowCount}
<AnimatePresence>
{tooltipsActive && hoveredId === "__overflow" && (
<Tooltip>{overflowCount} more · click to see all</Tooltip>
)}
</AnimatePresence>
</div>
)}
</button>
{/* Inline detail panel — pushes page content down */}
<AnimatePresence>
{panelOpen && (
<motion.div
id={panelId}
initial={{ height: 0, opacity: 0 }}
animate={{ height: "auto", opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2, ease: [0.4, 0, 0.2, 1] }}
className="mt-2 w-64 overflow-hidden rounded-xl border bg-popover shadow-md"
>
<p className="px-3 py-2 text-xs text-muted-foreground">
{onlineCount > 0
? `${onlineCount} online now · ${collaborators.length} with access`
: `${collaborators.length} with access`}
</p>
<ul role="list">
<AnimatePresence initial={false}>
{sorted.map((collab) => (
<motion.li
key={collab.id}
layout
className="flex items-center gap-2.5 px-3 py-1.5"
>
<div className="relative shrink-0">
<div
className={cn(
"flex size-7 items-center justify-center rounded-full text-xs font-semibold text-white transition-opacity",
collab.color,
!collab.isOnline && "opacity-60",
)}
>
{collab.initials}
</div>
{collab.isOnline && (
<span
aria-hidden
className="absolute -bottom-0.5 -right-0.5 size-2 rounded-full bg-emerald-400 ring-1 ring-background"
/>
)}
</div>
<div className="min-w-0 flex-1">
<p className="truncate text-xs font-medium leading-snug">{collab.name}</p>
<p className="truncate text-[10px] leading-snug text-muted-foreground">{collab.role}</p>
</div>
<span
className={cn(
"shrink-0 text-[10px]",
collab.isOnline
? "text-emerald-500 dark:text-emerald-400"
: "text-muted-foreground",
)}
>
{collab.isOnline ? "Online" : "Has access"}
</span>
</motion.li>
))}
</AnimatePresence>
</ul>
</motion.div>
)}
</AnimatePresence>
</div>
);
}
interface AvatarPipProps {
collab: Collaborator;
zIndex: number;
showTooltip: boolean;
onMouseEnter: () => void;
onMouseLeave: () => void;
}
function AvatarPip({ collab, zIndex, showTooltip, onMouseEnter, onMouseLeave }: AvatarPipProps) {
return (
<motion.div
layout
initial={{ scale: 0.5, opacity: 0 }}
animate={{ scale: 1, opacity: collab.isOnline ? 1 : 0.55 }}
exit={{ scale: 0.5, opacity: 0 }}
transition={{ type: "spring", stiffness: 380, damping: 28 }}
style={{ zIndex }}
className="relative shrink-0"
onMouseEnter={onMouseEnter}
onMouseLeave={onMouseLeave}
>
<div
className={cn(
"flex size-8 items-center justify-center rounded-full border-2 border-background text-xs font-semibold text-white",
collab.color,
collab.isOnline && "ring-2 ring-emerald-400",
)}
>
{collab.initials}
</div>
<AnimatePresence>
{collab.isOnline && (
<motion.span
key="dot"
aria-hidden
initial={{ scale: 0 }}
animate={{ scale: 1 }}
exit={{ scale: 0 }}
className="absolute -bottom-0.5 -right-0.5 size-2.5 rounded-full bg-emerald-400 ring-1 ring-background"
/>
)}
</AnimatePresence>
<AnimatePresence>
{showTooltip && (
<Tooltip>
<span className="block font-semibold">{collab.name}</span>
<span className="block text-muted-foreground">
{collab.role} · {collab.isOnline ? "Online now" : "Has access"}
</span>
</Tooltip>
)}
</AnimatePresence>
</motion.div>
);
}
function Tooltip({ children }: { children: React.ReactNode }) {
return (
<motion.div
initial={{ opacity: 0, y: 6 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: 6 }}
transition={{ duration: 0.15, ease: "easeOut" }}
className="pointer-events-none absolute bottom-full left-1/2 z-50 mb-2.5 -translate-x-1/2 whitespace-nowrap rounded-md border bg-popover px-2.5 py-1.5 text-xs shadow-md"
>
{children}
</motion.div>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Collaborative Presence
## Summary
An avatar stack that communicates two things at once: who has access to a shared project, and who is actively viewing it right now. The access list is always shown so the component is meaningful even when no one else is online. Online avatars are visually distinguished with a colored ring and a green dot. This "presence on top of access list" approach is the same convention used by Google Docs, Figma, and Notion, adapted for async B2B workflows where concurrent viewers are infrequent.
## When to use
- A project or document is shared across a fixed team working asynchronously.
- The product has a real-time presence signal scoped to who is currently viewing a specific item — not just who is logged in.
- The team is small enough (typically 2–10 people) that individual avatars are recognizable and meaningful.
- Knowing "who's involved" has persistent value, not just when others happen to be online.
## When not to use
- The item has no access control (everyone can see it) — use a viewer count or activity feed instead.
- Teams are so large (50+) that the avatar stack conveys nothing meaningful.
- Real-time presence is not technically available — showing only an access list without a presence signal produces a static component that doesn't justify its space.
- Consumer social products where follower counts matter more than specific collaborator identity.
## Anatomy
- **Avatar stack** — overlapping circular avatars in online-first order, up to the visible cap (default 4). The full group (stack + overflow chip) is a single button that toggles the detail panel.
- **Presence ring** — an emerald ring wrapping each avatar whose collaborator is currently viewing the item.
- **Online dot** — a small green dot at the bottom-right corner of each online avatar; backs up the ring with a redundant signal that does not rely on color alone.
- **Offline dimming** — avatars for collaborators not currently viewing appear at ~55% opacity, receding without disappearing.
- **Overflow chip** — a "+N" circle shown only when the collaborator count exceeds the visible cap. Hovering shows a tooltip: "N more · click to see all."
- **Detail panel** — an inline (not floating) panel that expands below the stack, pushing page content down. Lists all collaborators in online-first order with avatar, name, role, and a text status label.
- **Tooltip** — appears above an individual avatar on hover. Shows name on line one, and "Role · Online now" or "Role · Has access" on line two. Fades in with a slight nudge. Suppressed while the detail panel is open.
## Behavior
### Ordering
Online collaborators sort to the front of the stack. Within each group the order is stable. The stack should never be empty — show the current user's avatar even if they are the only person with access.
### Overflow surfacing
When a collaborator inside the overflow chip comes online they surface to the front of the visible stack via the join animation, and whoever was previously in the last visible slot moves to overflow. The "+N" count stays the same. The displaced avatar requires no explicit exit animation. The reverse (going offline while visible) lets the stack re-settle naturally without pulling an overflow collaborator forward.
### Join animation
The avatar appears at scale 0.5 / opacity 0 and springs to full size as the ring and dot fade in. Existing avatars slide to make room. Duration: ~300 ms (spring, stiffness 380, damping 28).
### Leave animation
The avatar shrinks and fades (scale 1→0.5, opacity 1→0) and settles into its new offline position. The ring and dot disappear with a separate scale-out transition.
### Detail panel
Opens inline on click, pushing page content down. Shows all collaborators in online-first order with avatar, name, role, and status label. A summary line at the top shows the counts: "2 online now · 5 with access." Clicking the avatar group again or clicking outside closes the panel. If presence changes while the panel is open the list re-sorts in place without requiring the user to reopen it.
### Hover tooltips
On desktop, hovering an avatar shows a tooltip above it with the collaborator's name and status. Tooltips are suppressed while the detail panel is open. On touch devices, tapping the group goes directly to the panel.
## Content guidelines
- Panel status labels: "Online" and "Has access."
- Tooltip status: "Role · Online now" or "Role · Has access" (tooltip uses the longer form for clarity on hover).
- Overflow tooltip: "N more · click to see all."
- Panel summary line: "2 online now · 5 with access." Use plain numbers, not percentages.
- Avatar initials: two characters maximum (first-name initial + last-name initial).
- If exactly one person has access, show their avatar alone — never leave the slot empty.
## Accessibility
- The entire avatar stack renders as a single `<button>` with `aria-label="View collaborators"` and `aria-expanded` reflecting the panel state.
- The detail panel is linked via `aria-controls` pointing to the button's `id`.
- Presence is not communicated by color alone: the panel provides text labels for every collaborator, and the tooltip repeats the same information on hover.
- The ring and online dot are decorative (`aria-hidden`); the panel list is the authoritative accessible representation.
- Avatar initials must maintain WCAG AA contrast against their background color.
- All animations should respect `prefers-reduced-motion`.
## Related patterns
- **Invite Members** — the access management counterpart; opens a modal to add or remove people from the same project. Typically placed adjacent to this component.
- **Sources Stack** — same overlapping circular group visual applied to source favicons. Shares the overlap, cap, and "+N" overflow conventions.
Invite Members
A two-step modal for searching or emailing people to a record and assigning each a role, with a live current-members list.
"use client";
import * as React from "react";
import { createPortal } from "react-dom";
import { AnimatePresence, motion } from "motion/react";
import {
ArrowLeft,
ChevronDown,
Globe,
Lock,
Mail,
PlusCircle,
RefreshCw,
UserPlus,
X,
} from "lucide-react";
import { cn } from "@/lib/utils";
export interface Role {
id: string;
label: string;
}
export interface OrgMember {
id: string;
name: string;
email: string;
}
export interface Assignee {
id: string;
name: string;
email: string;
status: "confirmed" | "invited" | "awaiting";
roleId: string;
}
export interface PendingChip {
key: string;
type: "user" | "email";
id?: string;
name: string;
email: string;
roleId: string;
}
export type GeneralAccessLevel = "restricted" | "anyone";
export interface InviteMembersProps {
/** Ordered least-privileged first. Defaults the role selector to index 0. */
roles: Role[];
orgMembers?: OrgMember[];
initialAssignees?: Assignee[];
defaultMessage?: string;
initialGeneralAccess?: GeneralAccessLevel;
onSend?: (chips: PendingChip[], message: string) => void;
onAssigneesChange?: (assignees: Assignee[]) => void;
onGeneralAccessChange?: (level: GeneralAccessLevel) => void;
}
// ─── Helpers ────────────────────────────────────────────────────────────────
const AVATAR_COLORS = [
"bg-violet-500",
"bg-sky-500",
"bg-emerald-500",
"bg-amber-500",
"bg-rose-500",
"bg-indigo-500",
];
function avatarColor(id: string) {
let h = 0;
for (const c of id) h = (h * 31 + c.charCodeAt(0)) | 0;
return AVATAR_COLORS[Math.abs(h) % AVATAR_COLORS.length];
}
function initials(name: string) {
return name
.split(" ")
.map((w) => w[0] ?? "")
.join("")
.slice(0, 2)
.toUpperCase();
}
function useMounted() {
return React.useSyncExternalStore(
() => () => {},
() => true,
() => false,
);
}
// ─── Avatar ─────────────────────────────────────────────────────────────────
function Avatar({
id,
name,
emailOnly,
size = "md",
}: {
id: string;
name: string;
emailOnly?: boolean;
size?: "sm" | "md";
}) {
return (
<span
className={cn(
"relative flex shrink-0 items-center justify-center rounded-full border-2 border-background font-medium text-white",
size === "sm" ? "size-7 text-[10px]" : "size-8 text-xs",
emailOnly ? "bg-muted" : avatarColor(id),
)}
>
{emailOnly ? (
<Mail
className={cn("text-muted-foreground", size === "sm" ? "size-3" : "size-3.5")}
aria-hidden
/>
) : (
initials(name)
)}
</span>
);
}
// ─── Role picker (portal-based so it's never clipped) ────────────────────────
function RolePicker({
roles,
value,
onChange,
compact = false,
}: {
roles: Role[];
value: string;
onChange: (id: string) => void;
compact?: boolean;
}) {
const [open, setOpen] = React.useState(false);
const [dropPos, setDropPos] = React.useState<{ top: number; right: number } | null>(null);
const btnRef = React.useRef<HTMLButtonElement>(null);
const mounted = useMounted();
const current = roles.find((r) => r.id === value);
React.useEffect(() => {
if (!open) return;
function handle(e: MouseEvent) {
if (!btnRef.current?.contains(e.target as Node)) setOpen(false);
}
document.addEventListener("mousedown", handle);
return () => document.removeEventListener("mousedown", handle);
}, [open]);
function toggle() {
const rect = btnRef.current?.getBoundingClientRect();
if (rect) setDropPos({ top: rect.bottom + 4, right: window.innerWidth - rect.right });
setOpen((o) => !o);
}
return (
<div className="shrink-0">
<button
ref={btnRef}
type="button"
onClick={toggle}
aria-haspopup="listbox"
aria-expanded={open}
className={cn(
"inline-flex items-center gap-0.5 rounded font-medium transition-colors",
compact
? "px-1.5 py-0.5 text-[10px] text-muted-foreground hover:bg-accent hover:text-foreground"
: "gap-1 rounded-md border px-2.5 py-1.5 text-sm hover:bg-accent",
)}
>
{current?.label ?? ""}
<ChevronDown className="size-3 shrink-0 opacity-60" aria-hidden />
</button>
{mounted &&
createPortal(
<AnimatePresence>
{open && dropPos && (
<motion.ul
role="listbox"
style={{ position: "fixed", top: dropPos.top, right: dropPos.right, zIndex: 200 }}
initial={{ opacity: 0, y: -4, scale: 0.97 }}
animate={{ opacity: 1, y: 0, scale: 1 }}
exit={{ opacity: 0, y: -4, scale: 0.97 }}
transition={{ duration: 0.1 }}
className="min-w-[120px] overflow-hidden rounded-lg border bg-popover shadow-md"
>
{roles.map((role) => (
<li key={role.id}>
<button
type="button"
role="option"
aria-selected={role.id === value}
onClick={() => {
onChange(role.id);
setOpen(false);
}}
className={cn(
"w-full px-3 py-2 text-left text-xs transition-colors hover:bg-accent",
role.id === value && "font-semibold",
)}
>
{role.label}
</button>
</li>
))}
</motion.ul>
)}
</AnimatePresence>,
document.body,
)}
</div>
);
}
// ─── Chip ────────────────────────────────────────────────────────────────────
function Chip({ chip, onRemove }: { chip: PendingChip; onRemove: () => void }) {
return (
<span className="inline-flex items-center gap-1 rounded-full border bg-muted/60 py-0.5 pl-0.5 pr-1 text-xs">
<Avatar
id={chip.id ?? chip.email}
name={chip.name}
emailOnly={chip.type === "email"}
size="sm"
/>
<span className="max-w-[100px] truncate font-medium">{chip.name}</span>
<button
type="button"
onClick={onRemove}
aria-label={`Remove ${chip.name}`}
className="rounded p-0.5 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-3" aria-hidden />
</button>
</span>
);
}
// ─── Status badge ────────────────────────────────────────────────────────────
const STATUS_LABEL: Record<string, string> = {
confirmed: "Confirmed",
invited: "Invite sent",
awaiting: "Awaiting",
};
const STATUS_CLASS: Record<string, string> = {
confirmed:
"bg-emerald-50 text-emerald-700 border-emerald-200 dark:bg-emerald-950/40 dark:text-emerald-400 dark:border-emerald-800",
invited:
"bg-sky-50 text-sky-700 border-sky-200 dark:bg-sky-950/40 dark:text-sky-400 dark:border-sky-800",
awaiting:
"bg-amber-50 text-amber-700 border-amber-200 dark:bg-amber-950/40 dark:text-amber-400 dark:border-amber-800",
};
// ─── Assignee row ─────────────────────────────────────────────────────────────
function AssigneeRow({
assignee,
roles,
resending,
onRoleChange,
onResend,
onRemove,
}: {
assignee: Assignee;
roles: Role[];
resending: boolean;
onRoleChange: (roleId: string) => void;
onResend: () => void;
onRemove: () => void;
}) {
return (
<div className="flex items-center gap-2 rounded-lg px-2 py-1.5 transition-colors hover:bg-accent/40">
<Avatar
id={assignee.id}
name={assignee.name}
emailOnly={assignee.status === "invited"}
size="sm"
/>
<div className="min-w-0 flex-1">
<div className="truncate text-xs font-medium">{assignee.name}</div>
<div className="truncate text-xs text-muted-foreground">{assignee.email}</div>
</div>
<RolePicker roles={roles} value={assignee.roleId} onChange={onRoleChange} compact />
<span
className={cn(
"shrink-0 rounded-full border px-2 py-0.5 text-[10px]",
STATUS_CLASS[assignee.status],
)}
>
{STATUS_LABEL[assignee.status]}
</span>
<button
type="button"
onClick={onResend}
aria-label={resending ? "Invite resent" : "Resend invite"}
title={resending ? "Invite resent!" : "Resend invite"}
className={cn(
"shrink-0 rounded p-1 transition-colors",
resending
? "text-emerald-600 dark:text-emerald-400"
: "text-muted-foreground hover:bg-accent hover:text-foreground",
)}
>
<RefreshCw className={cn("size-3.5", resending && "animate-spin")} aria-hidden />
</button>
<button
type="button"
onClick={onRemove}
aria-label={`Remove ${assignee.name}`}
className="shrink-0 rounded p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-3.5" aria-hidden />
</button>
</div>
);
}
// ─── General access ──────────────────────────────────────────────────────────
const GENERAL_ACCESS_OPTIONS = [
{
level: "restricted" as const,
label: "Restricted",
description: "Only people added can access this project",
Icon: Lock,
},
{
level: "anyone" as const,
label: "Anyone with the link",
description: "Anyone with the link can view this project",
Icon: Globe,
},
];
function GeneralAccessSection({
roles,
value,
onValueChange,
roleId,
onRoleChange,
}: {
roles: Role[];
value: GeneralAccessLevel;
onValueChange: (v: GeneralAccessLevel) => void;
roleId: string;
onRoleChange: (id: string) => void;
}) {
const [open, setOpen] = React.useState(false);
const [dropPos, setDropPos] = React.useState<{ top: number; left: number } | null>(null);
const btnRef = React.useRef<HTMLButtonElement>(null);
const mounted = useMounted();
const current = GENERAL_ACCESS_OPTIONS.find((o) => o.level === value)!;
const Icon = current.Icon;
React.useEffect(() => {
if (!open) return;
function handle(e: MouseEvent) {
if (!btnRef.current?.contains(e.target as Node)) setOpen(false);
}
document.addEventListener("mousedown", handle);
return () => document.removeEventListener("mousedown", handle);
}, [open]);
function toggle() {
const rect = btnRef.current?.getBoundingClientRect();
if (rect) setDropPos({ top: rect.bottom + 4, left: rect.left });
setOpen((o) => !o);
}
return (
<div className="flex items-center gap-3 px-4 py-3">
<div className="flex size-8 shrink-0 items-center justify-center rounded-full bg-muted">
<Icon className="size-4 text-muted-foreground" aria-hidden />
</div>
<div className="min-w-0 flex-1">
<button
ref={btnRef}
type="button"
onClick={toggle}
className="inline-flex items-center gap-0.5 rounded text-xs font-medium transition-colors hover:text-muted-foreground"
>
{current.label}
<ChevronDown className="size-3 opacity-60" aria-hidden />
</button>
<p className="text-xs text-muted-foreground">{current.description}</p>
</div>
{value === "anyone" && (
<RolePicker roles={roles} value={roleId} onChange={onRoleChange} compact />
)}
{mounted &&
createPortal(
<AnimatePresence>
{open && dropPos && (
<motion.ul
style={{ position: "fixed", top: dropPos.top, left: dropPos.left, zIndex: 200 }}
initial={{ opacity: 0, y: -4, scale: 0.97 }}
animate={{ opacity: 1, y: 0, scale: 1 }}
exit={{ opacity: 0, y: -4, scale: 0.97 }}
transition={{ duration: 0.1 }}
className="min-w-[200px] overflow-hidden rounded-lg border bg-popover shadow-md"
>
{GENERAL_ACCESS_OPTIONS.map((opt) => (
<li key={opt.level}>
<button
type="button"
onClick={() => {
onValueChange(opt.level);
setOpen(false);
}}
className={cn(
"flex w-full items-center gap-2.5 px-3 py-2.5 text-left transition-colors hover:bg-accent",
opt.level === value && "font-semibold",
)}
>
<opt.Icon className="size-4 shrink-0 text-muted-foreground" aria-hidden />
<span>
<span className="block text-xs">{opt.label}</span>
<span className="block text-xs text-muted-foreground">{opt.description}</span>
</span>
</button>
</li>
))}
</motion.ul>
)}
</AnimatePresence>,
document.body,
)}
</div>
);
}
// ─── Modal ───────────────────────────────────────────────────────────────────
interface InviteModalProps {
roles: Role[];
orgMembers: OrgMember[];
assignees: Assignee[];
defaultMessage: string;
generalAccess: GeneralAccessLevel;
onSend: (chips: PendingChip[], message: string) => void;
onRoleChange: (id: string, roleId: string) => void;
onRemove: (id: string) => void;
onGeneralAccessChange: (level: GeneralAccessLevel) => void;
onClose: () => void;
}
function InviteModal({
roles,
orgMembers,
assignees,
defaultMessage,
generalAccess,
onSend,
onRoleChange,
onRemove,
onGeneralAccessChange,
onClose,
}: InviteModalProps) {
const [step, setStep] = React.useState<1 | 2>(1);
const [query, setQuery] = React.useState("");
const [chips, setChips] = React.useState<PendingChip[]>([]);
const [roleForNext, setRoleForNext] = React.useState(roles[0]?.id ?? "");
const [message, setMessage] = React.useState(defaultMessage);
const [dropdownOpen, setDropdownOpen] = React.useState(false);
const [removeConfirm, setRemoveConfirm] = React.useState<string | null>(null);
const [resendFeedback, setResendFeedback] = React.useState<string | null>(null);
const [generalAccessRole, setGeneralAccessRole] = React.useState(roles[0]?.id ?? "");
const inputRef = React.useRef<HTMLInputElement>(null);
const chipKeyRef = React.useRef(0);
React.useEffect(() => {
inputRef.current?.focus();
}, [step]);
React.useEffect(() => {
function handleKey(e: KeyboardEvent) {
if (e.key === "Escape") {
if (removeConfirm) { setRemoveConfirm(null); return; }
onClose();
}
}
document.addEventListener("keydown", handleKey);
return () => document.removeEventListener("keydown", handleKey);
}, [removeConfirm, onClose]);
const excludedIds = new Set([
...assignees.map((a) => a.id),
...chips.filter((c) => c.id).map((c) => c.id!),
]);
const filtered = orgMembers.filter(
(m) =>
!excludedIds.has(m.id) &&
(m.name.toLowerCase().includes(query.toLowerCase()) ||
m.email.toLowerCase().includes(query.toLowerCase())),
);
function addChip(chip: Omit<PendingChip, "key" | "roleId">) {
const key = `chip-${chipKeyRef.current++}`;
setChips((prev) => [...prev, { ...chip, key, roleId: roleForNext }]);
setQuery("");
setDropdownOpen(false);
if (step === 1) setStep(2);
}
function addEmailChip() {
const email = query.trim();
if (!email) return;
const match = orgMembers.find(
(m) => m.email.toLowerCase() === email.toLowerCase() && !excludedIds.has(m.id),
);
if (match) {
addChip({ type: "user", id: match.id, name: match.name, email: match.email });
} else {
addChip({ type: "email", name: email, email });
}
}
function removeChip(key: string) {
const next = chips.filter((c) => c.key !== key);
setChips(next);
if (next.length === 0) setStep(1);
}
function handleResend(id: string) {
setResendFeedback(id);
window.setTimeout(() => setResendFeedback(null), 2000);
}
return (
<>
{/* Backdrop */}
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
transition={{ duration: 0.15 }}
className="fixed inset-0 z-40 bg-black/40"
onClick={onClose}
aria-hidden
/>
{/* Dialog */}
<motion.div
role="dialog"
aria-modal
aria-label="Invite members"
initial={{ opacity: 0, scale: 0.97, y: 8 }}
animate={{ opacity: 1, scale: 1, y: 0 }}
exit={{ opacity: 0, scale: 0.97, y: 8 }}
transition={{ duration: 0.18, ease: "easeOut" }}
className="fixed left-1/2 top-1/2 z-50 w-full max-w-md -translate-x-1/2 -translate-y-1/2 rounded-2xl border bg-background shadow-xl"
onClick={(e) => e.stopPropagation()}
>
{/* Header */}
<div className="flex items-center gap-1 px-4 py-3">
<AnimatePresence mode="popLayout">
{step === 2 && (
<motion.button
key="back"
type="button"
initial={{ opacity: 0, x: -8 }}
animate={{ opacity: 1, x: 0 }}
exit={{ opacity: 0, x: -8 }}
transition={{ duration: 0.15 }}
onClick={() => { setChips([]); setQuery(""); setStep(1); }}
aria-label="Back to search"
className="rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<ArrowLeft className="size-4" aria-hidden />
</motion.button>
)}
</AnimatePresence>
<h2 className="flex-1 text-sm font-semibold">Invite members</h2>
<button
type="button"
onClick={onClose}
aria-label="Close"
className="rounded-md p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
<X className="size-4" aria-hidden />
</button>
</div>
{/* Search area — outside scroll container so dropdown is never clipped */}
<div className="px-4 py-3">
<div className="flex items-start gap-2">
{/* Chip + search field */}
<div
className="relative flex min-h-[38px] flex-1 cursor-text flex-wrap items-center gap-1 rounded-lg border bg-background px-2 py-1.5 focus-within:ring-2 focus-within:ring-ring"
onClick={() => inputRef.current?.focus()}
>
{chips.map((chip) => (
<Chip key={chip.key} chip={chip} onRemove={() => removeChip(chip.key)} />
))}
<input
ref={inputRef}
type="text"
value={query}
onChange={(e) => { setQuery(e.target.value); setDropdownOpen(true); }}
onFocus={() => setDropdownOpen(true)}
onBlur={() => window.setTimeout(() => setDropdownOpen(false), 150)}
onKeyDown={(e) => {
if (e.key === "Enter") { e.preventDefault(); if (query.trim()) addEmailChip(); }
if (e.key === "Backspace" && !query && chips.length > 0) {
removeChip(chips[chips.length - 1].key);
}
}}
placeholder={chips.length === 0 ? "Search by name or invite by email…" : "Add more people…"}
aria-label="Search members or enter email"
className="min-w-[140px] flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground"
/>
{/* Dropdown — not clipped since parent has no overflow restriction */}
<AnimatePresence>
{dropdownOpen && (
<motion.div
initial={{ opacity: 0, y: -4 }}
animate={{ opacity: 1, y: 0 }}
exit={{ opacity: 0, y: -4 }}
transition={{ duration: 0.1 }}
className="absolute left-0 right-0 top-full z-20 mt-1 overflow-hidden rounded-xl border bg-popover shadow-lg"
>
<button
type="button"
onMouseDown={(e) => { e.preventDefault(); addEmailChip(); }}
disabled={!query.trim()}
className="flex w-full items-center gap-2.5 px-3 py-2.5 text-left transition-colors hover:bg-accent disabled:pointer-events-none disabled:opacity-40"
>
<span className="flex size-7 shrink-0 items-center justify-center rounded-full border bg-muted">
<PlusCircle className="size-3.5 text-muted-foreground" aria-hidden />
</span>
<span className="min-w-0">
<span className="block truncate text-xs font-medium text-foreground">
{query.trim() ? query.trim() : "Type an email to invite"}
</span>
<span className="block text-xs text-muted-foreground">
They'll receive an email invitation to join.
</span>
</span>
</button>
{filtered.length > 0 && (
<div className="border-t">
{filtered.slice(0, 8).map((member) => (
<button
key={member.id}
type="button"
onMouseDown={(e) => {
e.preventDefault();
addChip({ type: "user", id: member.id, name: member.name, email: member.email });
}}
className="flex w-full items-center gap-2.5 px-3 py-2 text-left transition-colors hover:bg-accent"
>
<Avatar id={member.id} name={member.name} size="sm" />
<span className="min-w-0 flex-1">
<span className="block truncate text-xs font-medium">{member.name}</span>
<span className="block truncate text-xs text-muted-foreground">{member.email}</span>
</span>
</button>
))}
</div>
)}
</motion.div>
)}
</AnimatePresence>
</div>
{/* Role selector for pending invitees */}
<AnimatePresence>
{step === 2 && (
<motion.div
initial={{ opacity: 0, scale: 0.95 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.95 }}
transition={{ duration: 0.15 }}
>
<RolePicker roles={roles} value={roleForNext} onChange={setRoleForNext} />
</motion.div>
)}
</AnimatePresence>
</div>
{/* Invite message */}
<AnimatePresence>
{step === 2 && (
<motion.div
initial={{ opacity: 0, height: 0 }}
animate={{ opacity: 1, height: "auto" }}
exit={{ opacity: 0, height: 0 }}
transition={{ duration: 0.2 }}
className="overflow-hidden"
>
<textarea
value={message}
onChange={(e) => setMessage(e.target.value)}
rows={3}
aria-label="Invite message"
className="mt-3 w-full resize-none rounded-lg border bg-background px-3 py-2 text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring"
/>
</motion.div>
)}
</AnimatePresence>
</div>
{/* People with access — step 1 only */}
{step === 1 && assignees.length > 0 && (
<div className="max-h-52 overflow-y-auto">
<p className="px-4 pb-1 pt-2.5 text-xs font-medium text-muted-foreground">
People with access
</p>
<div className="px-2 pb-2">
<AnimatePresence initial={false}>
{assignees.map((assignee) => (
<motion.div
key={assignee.id}
layout
initial={{ opacity: 0, height: 0 }}
animate={{ opacity: 1, height: "auto" }}
exit={{ opacity: 0, height: 0 }}
transition={{ duration: 0.15 }}
>
<AssigneeRow
assignee={assignee}
roles={roles}
resending={resendFeedback === assignee.id}
onRoleChange={(roleId) => onRoleChange(assignee.id, roleId)}
onResend={() => handleResend(assignee.id)}
onRemove={() => setRemoveConfirm(assignee.id)}
/>
</motion.div>
))}
</AnimatePresence>
</div>
</div>
)}
{/* General access — step 1 only */}
{step === 1 && (
<GeneralAccessSection
roles={roles}
value={generalAccess}
onValueChange={onGeneralAccessChange}
roleId={generalAccessRole}
onRoleChange={setGeneralAccessRole}
/>
)}
{/* Footer */}
<div className="flex items-center justify-end gap-2 px-4 py-3">
<button
type="button"
onClick={onClose}
className="rounded-lg px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
>
{step === 1 ? "Done" : "Cancel"}
</button>
{step === 2 && (
<button
type="button"
onClick={() => onSend(chips, message)}
disabled={chips.length === 0}
className="inline-flex items-center gap-1.5 rounded-lg bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground transition-opacity hover:opacity-90 disabled:opacity-40"
>
Send invite
</button>
)}
</div>
{/* Remove confirmation overlay */}
<AnimatePresence>
{removeConfirm && (
<>
<motion.div
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
exit={{ opacity: 0 }}
className="absolute inset-0 z-10 rounded-2xl bg-background/80 backdrop-blur-sm"
/>
<motion.div
initial={{ opacity: 0, scale: 0.96 }}
animate={{ opacity: 1, scale: 1 }}
exit={{ opacity: 0, scale: 0.96 }}
transition={{ duration: 0.15 }}
className="absolute inset-x-6 top-1/2 z-20 -translate-y-1/2 rounded-xl border bg-background p-4 shadow-lg"
>
<p className="text-sm font-semibold">Remove member?</p>
<p className="mt-1 text-xs leading-relaxed text-muted-foreground">
{assignees.find((a) => a.id === removeConfirm)?.name ?? "This person"} will be
will lose access to this project.
</p>
<div className="mt-4 flex justify-end gap-2">
<button
type="button"
onClick={() => setRemoveConfirm(null)}
className="rounded-md px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:bg-accent"
>
Cancel
</button>
<button
type="button"
onClick={() => { onRemove(removeConfirm); setRemoveConfirm(null); }}
className="rounded-md bg-destructive px-3 py-1.5 text-sm font-medium text-destructive-foreground transition-opacity hover:opacity-90"
>
Remove
</button>
</div>
</motion.div>
</>
)}
</AnimatePresence>
</motion.div>
</>
);
}
// ─── Entry point trigger ──────────────────────────────────────────────────────
function Trigger({ assignees, onClick }: { assignees: Assignee[]; onClick: () => void }) {
const visible = assignees.slice(0, 4);
const overflow = assignees.length - 4;
if (assignees.length === 0) {
return (
<button
type="button"
onClick={onClick}
className="inline-flex items-center gap-1.5 rounded-md border border-dashed px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:border-foreground/30 hover:text-foreground"
>
<UserPlus className="size-4" aria-hidden />
Invite users
</button>
);
}
return (
<button
type="button"
onClick={onClick}
aria-label={`${assignees.length} member${assignees.length === 1 ? "" : "s"} — click to manage`}
className="flex items-center -space-x-1.5 transition-opacity hover:opacity-80"
>
{visible.map((a) => (
<Avatar key={a.id} id={a.id} name={a.name} emailOnly={a.status === "invited"} size="sm" />
))}
{overflow > 0 && (
<span className="relative z-10 flex size-7 items-center justify-center rounded-full border-2 border-background bg-muted text-[10px] font-medium text-muted-foreground">
+{overflow}
</span>
)}
</button>
);
}
// ─── Main export ──────────────────────────────────────────────────────────────
export function InviteMembers({
roles,
orgMembers = [],
initialAssignees = [],
defaultMessage = "I'd like to invite you to collaborate on this project.",
initialGeneralAccess = "restricted",
onSend,
onAssigneesChange,
onGeneralAccessChange,
}: InviteMembersProps) {
const [open, setOpen] = React.useState(false);
const [assignees, setAssignees] = React.useState<Assignee[]>(initialAssignees);
const [generalAccess, setGeneralAccess] = React.useState<GeneralAccessLevel>(initialGeneralAccess);
const mounted = useMounted();
function handleSend(chips: PendingChip[], msg: string) {
const next: Assignee[] = chips.map((chip) => ({
id: chip.id ?? `email:${chip.email}`,
name: chip.name,
email: chip.email,
status: chip.type === "user" ? "awaiting" : "invited",
roleId: chip.roleId,
}));
const updated = [...assignees, ...next];
setAssignees(updated);
onAssigneesChange?.(updated);
onSend?.(chips, msg);
setOpen(false);
}
function handleRoleChange(id: string, roleId: string) {
const updated = assignees.map((a) => (a.id === id ? { ...a, roleId } : a));
setAssignees(updated);
onAssigneesChange?.(updated);
}
function handleRemove(id: string) {
const updated = assignees.filter((a) => a.id !== id);
setAssignees(updated);
onAssigneesChange?.(updated);
}
function handleGeneralAccessChange(level: GeneralAccessLevel) {
setGeneralAccess(level);
onGeneralAccessChange?.(level);
}
const trigger = <Trigger assignees={assignees} onClick={() => setOpen(true)} />;
if (!mounted) return trigger;
return (
<>
{trigger}
{createPortal(
<AnimatePresence>
{open && (
<InviteModal
roles={roles}
orgMembers={orgMembers}
assignees={assignees}
defaultMessage={defaultMessage}
generalAccess={generalAccess}
onSend={handleSend}
onRoleChange={handleRoleChange}
onRemove={handleRemove}
onGeneralAccessChange={handleGeneralAccessChange}
onClose={() => setOpen(false)}
/>
)}
</AnimatePresence>,
document.body,
)}
</>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Invite Members Modal
## Summary
A two-step modal for adding people to any record — an assessment, workspace, or any object with an access list — and assigning them a role. Entry point shows an "Invite users" button when nobody has access, or a row of circular avatars once people are assigned. Role options are passed in by the calling surface, making the same modal work for a single-role workflow or a full Viewer/Editor/Admin hierarchy.
## When to use
- Any surface that manages per-record access with role assignment.
- When invitees come from two pools: searchable org members and external email addresses.
- When a record can have many collaborators and needs a centralized place to add, change, or remove them.
## When not to use
- Simple collaborator pickers with no roles (use a plain multi-select instead).
- When access is determined by team or group membership rather than individual assignment.
- When the invite is a one-off action with no persistent access list to manage afterward.
## Anatomy
### Entry point
- **Empty state**: Outlined dashed button with a user-plus icon and "Invite users" label.
- **Populated state**: A row of up to four circular avatars — initials on a color-coded background for known users, envelope icon for email-only invites — followed by a "+N" overflow chip when there are more than four. Clicking either state opens the modal.
### Modal — Step 1: Manage access
The default view when the modal opens.
- **Search field**: Full-width, placeholder "Search by name or invite by email…". Opens a dropdown on focus or typing.
- **Dropdown**:
- **Invite by email row** (always pinned at top): plus-circle icon; email typed so far as the primary label, or "Type an email to invite" when the field is empty; sub-text "They'll receive an email invitation to join." Disabled when field is empty.
- **Org member rows**: avatar with initials, name, email — filtered live. Members already assigned are excluded.
- **People with access**: Scrollable list below the search field, visible only when the record already has assignees. Each row: avatar, name, email, compact inline role selector, status badge ("Confirmed", "Invite sent", "Awaiting"), resend icon, remove icon. The role selector takes effect immediately. Resend shows a brief spinning animation then resets. Remove opens a nested confirmation.
- **General access**: Always visible at the bottom of step 1. A row with an icon, a label button ("Restricted" or "Anyone with the link"), and a description. Switching to "Anyone with the link" adds a compact role selector on the right of the row. Options: "Restricted — only people added can access this project" and "Anyone with the link — anyone with the link can view this project."
- **Footer**: A single "Done" button that closes the modal.
### Modal — Step 2: Compose invite
Reached automatically when the first chip is added from the dropdown.
- **Header**: Gains a back arrow. Pressing it clears all new chips and returns to step 1 without sending anything.
- **Search + chips field**: The search field carries forward and now shows chips for everyone being invited. Placeholder changes to "Add more people…" once at least one chip exists. New people can still be added.
- **Chips**: Each chip = avatar/envelope + truncated name + remove ×. No role label inside the chip.
- **Role selector**: Sits beside the search field, outside the chips. Sets the role that will be applied to the next person added. Defaults to the least-privileged role (index 0 of the roles array). Does not retroactively change chips already in the field.
- **Invite message**: Textarea below the search area, pre-filled with a caller-supplied default, fully editable.
- **Footer**: "Cancel" (discards chips, closes) and "Send invite" (saves, closes).
### Nested remove confirmation
Overlays the modal when the remove icon is clicked on a current member. Shows the person's name and the message "[Name] will lose access to this project.", with "Cancel" and a destructive "Remove" button.
## Behavior
- Adding the first chip automatically advances from step 1 to step 2.
- Removing all chips in step 2 returns to step 1.
- The role selector beside the search field only affects people added after it is changed.
- The inline role selector in "People with access" takes effect immediately; no separate save step.
- Resending an invite shows a brief spinning animation on the resend icon, then resets.
- Pressing Escape: closes an open remove confirmation first, then closes the modal.
- Backspace in an empty search field removes the last chip.
- Enter on a non-empty field adds the typed value as an email chip.
- Footer "Done" (step 1) closes without notification. "Send invite" (step 2) saves and closes. "Cancel" or ✕ discards unsent chips and closes without changes.
- Switching general access from "Anyone with the link" back to "Restricted" hides the role selector; the previously chosen link-role is remembered if the user switches back again.
## Content guidelines
- Entry point label: "Invite users" — not "Share", "Assign", or "Add collaborators".
- Modal title: "Invite members" — consistent regardless of which roles are available.
- Step 1 placeholder: "Search by name or invite by email…"
- Step 2 placeholder (chips present): "Add more people…"
- Invite-by-email sub-text: "They'll receive an email invitation to join." One sentence.
- Default invite message: caller-supplied; should be contextual, not generic.
- Status labels: "Confirmed", "Invite sent", "Awaiting" — sentence case.
- Remove dialog body: "[Name] will lose access to this project." — specific, not vague.
- If only one role exists, the selector still renders; it is never hidden.
## Accessibility
- Modal: `role="dialog"`, `aria-modal`, `aria-label="Invite members"`.
- Focus moves to the search input when the modal opens and when advancing to step 2.
- Escape closes an open remove confirmation first, then the modal.
- Role selectors use `aria-haspopup="listbox"` and `aria-expanded`; their dropdowns are portal-rendered to avoid clipping.
- Chip remove buttons carry `aria-label="Remove [name]"`.
- Resend button `aria-label` changes to "Invite resent" during the feedback window.
- Avatar stack trigger carries `aria-label="N member(s) — click to manage"`.
- Reduce motion: use opacity-only transitions; skip scale and y transforms.
## Related patterns
- Collaborative Presence — shows the same assignees as a live avatar stack; pairs naturally as the read view for what Invite Members writes
- Tool Approval — another modal-adjacent permission flow with confirm/deny actions
- Attachment Chip — chip removal shares the same backspace-to-remove and × affordance
Analysis List
A full-width indeterminate progress bar over a list whose items resolve from skeletons one by one.
"use client";
import * as React from "react";
import { AnimatePresence, motion } from "motion/react";
import { Check, FileCode2, Loader2 } from "lucide-react";
import { cn } from "@/lib/utils";
export type AnalysisItemStatus = "pending" | "loading" | "done";
export interface AnalysisItem {
id: string;
/** Revealed once status is "done". Ignored (skeleton shown instead) otherwise. Falls back to a generic icon when omitted or when the image fails to load. */
imageUrl?: string;
title?: string;
info?: string;
status: AnalysisItemStatus;
}
export interface AnalysisListProps {
items: AnalysisItem[];
/** Drives the indeterminate bar at top. Set to false once every item is done. */
analyzing: boolean;
className?: string;
}
export function AnalysisList({ items, analyzing, className }: AnalysisListProps) {
return (
<div className={cn("w-full overflow-hidden rounded-2xl border bg-card", className)}>
<IndeterminateBar active={analyzing} />
<ul aria-live="polite" className="divide-y divide-border/70">
{items.map((item) => (
<AnalysisRow key={item.id} item={item} />
))}
</ul>
</div>
);
}
/** Unmounts entirely once analysis finishes — a finished list shouldn't keep showing a loading affordance. */
function IndeterminateBar({ active }: { active: boolean }) {
return (
<AnimatePresence initial={false}>
{active && (
<motion.div
key="bar"
role="progressbar"
aria-label="Analyzing"
aria-valuetext="In progress"
initial={{ height: 0, opacity: 0 }}
animate={{ height: 4, opacity: 1 }}
exit={{ height: 0, opacity: 0 }}
transition={{ duration: 0.2, ease: "easeInOut" }}
className="relative w-full shrink-0 overflow-hidden bg-muted"
>
<motion.div
className="absolute inset-y-0 w-1/3 rounded-full bg-foreground/70"
initial={{ x: "-100%" }}
animate={{ x: ["-100%", "300%"] }}
transition={{ duration: 1.1, repeat: Infinity, ease: "easeInOut" }}
/>
</motion.div>
)}
</AnimatePresence>
);
}
function AnalysisRow({ item }: { item: AnalysisItem }) {
const revealed = item.status === "done";
const loading = item.status === "loading";
const [imageErrored, setImageErrored] = React.useState(false);
return (
<li
aria-busy={loading}
className={cn(
"flex items-center gap-2.5 px-3.5 py-2.5 transition-opacity duration-300",
item.status === "pending" && "opacity-50"
)}
>
<div className="flex size-9 shrink-0 items-center justify-center overflow-hidden rounded-lg bg-muted">
{revealed ? (
item.imageUrl && !imageErrored ? (
// eslint-disable-next-line @next/next/no-img-element
<img
src={item.imageUrl}
alt=""
className="size-full object-cover"
onError={() => setImageErrored(true)}
/>
) : (
<FileCode2 className="size-4 text-muted-foreground" aria-hidden />
)
) : (
<Skeleton className="size-full" active={loading} />
)}
</div>
<div className="min-w-0 flex-1 space-y-1">
{revealed && item.title ? (
<p className="truncate text-xs font-medium text-foreground">{item.title}</p>
) : (
<Skeleton className="h-3 w-2/3 rounded" active={loading} />
)}
{revealed && item.info ? (
<p className="truncate text-[11px] text-muted-foreground">{item.info}</p>
) : (
<Skeleton className="h-2.5 w-2/5 rounded" active={loading} />
)}
</div>
<span className="flex size-4 shrink-0 items-center justify-center" aria-hidden>
{loading && <Loader2 className="size-3.5 animate-spin text-muted-foreground" />}
{revealed && <Check className="size-3.5 text-emerald-600 dark:text-emerald-400" />}
</span>
</li>
);
}
function Skeleton({ className, active }: { className?: string; active: boolean }) {
return (
<span className={cn("block bg-muted-foreground/15", active && "animate-pulse", className)} />
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Analysis List
## Summary
A batch-processing loader: a full-width indeterminate progress bar sits above a list of items, and each item's thumbnail, title, and detail line resolve from a skeleton to real content one at a time, top to bottom, as the AI finishes analyzing it.
## When to use
- The AI is running the same analysis step over a known set of items — scanning uploaded photos, classifying a batch of documents, extracting metadata from files — and results arrive incrementally in a stable, known order.
- You already know how many items there are (so a list of rows can be rendered up front) but not yet what any individual result looks like.
## When not to use
- A single long-running operation with no distinct sub-items — use Thinking Loader instead.
- Work whose item count or order isn't known in advance (e.g. items streaming in one by one from a search) — skeleton placeholders imply a fixed, already-known list.
- When each item's result is already available immediately (no per-item latency) — just render the list; a skeleton that appears and clears in one frame is noise.
## Anatomy
- Indeterminate bar: a thin (4px), full-width track at the top of the list container with a short filled segment sweeping back and forth.
- Item rows, each with:
- Thumbnail (fixed square, rounded corners); falls back to a generic icon when the item has no image or it fails to load — never a broken-image glyph.
- Title line.
- Secondary info line (smaller, muted).
- Trailing status glyph: nothing while queued, a spinner while loading, a check once done.
## Behavior
- On mount, the first item is "loading" and every other item is "pending"; only one item loads at a time.
- A "pending" item's thumbnail and text render as static (non-animated), dimmed (~50% opacity) skeleton blocks — visually queued, not yet being worked on.
- A "loading" item's skeleton blocks switch to a pulsing animation and its trailing glyph shows a spinner — this is the one item actively resolving.
- The instant an item's real data is available, its skeletons are replaced by the actual thumbnail, title, and info text in place (no layout shift — skeleton and content occupy the same dimensions), the spinner is replaced by a check, and the next item flips from "pending" to "loading".
- The top progress bar keeps sweeping for as long as any item is not yet "done". The moment the last item finishes, unmount the bar entirely (collapse its height, don't just stop the sweep) — a finished list has no loading affordance left on screen.
- Rows never reorder during the process — position is stable; only each row's content state changes.
## Content guidelines
- Title: the item's real name/subject once known — a filename, a detected object, a person's name. Keep it one line, truncate with ellipsis rather than wrap.
- Info line: one short classification or metadata fragment ("Document · 3 pages", "Matches Tool Call Chip"), not a full sentence.
- Never show placeholder text ("Loading...", "TBD") inside a skeleton block — the skeleton shape itself communicates "not ready yet."
- Row text runs small (title and info are both secondary to the thumbnail/status glyph) — this is a scan list, not prose; keep both lines short enough that truncation is rare.
## Accessibility
- Mark the progress bar `role="progressbar"` and omit `aria-valuenow` (it's indeterminate); set `aria-valuetext` to "In progress" while it's mounted.
- Wrap the item list in an `aria-live="polite"` region so each reveal is announced without interrupting the user; mark a row `aria-busy="true"` while it is the active loading item.
- Respect `prefers-reduced-motion`: keep the skeleton-to-content swap (it's informational) but reduce the sweeping bar and pulsing skeleton to a static or much subtler state.
- Thumbnail images use empty `alt=""` when the adjacent title already names the item, to avoid redundant announcements.
## Related patterns
- Thinking Loader — the right choice for a single undifferentiated task instead of a list of sub-items.
- Tool Call Chip — a single inline chip's running → done transition, useful as the trailing glyph's model for this pattern's per-row status.
Setup Checklist
A stepped onboarding card with circular arc progress, dashed-circle pending states, and strikethrough for completed steps.
Set up Computer
1/3
Click a step to complete it
"use client";
import * as React from "react";
import { motion } from "motion/react";
import { Check, ChevronRight } from "lucide-react";
import { cn } from "@/lib/utils";
export type SetupStepStatus = "pending" | "done";
export interface AppIcon {
label: string;
/** Tailwind-compatible hex or CSS color string for the icon background. */
color: string;
initial: string;
}
export interface SetupStep {
id: string;
label: string;
status: SetupStepStatus;
/** Optional small app icons shown to the right of the label row. */
icons?: AppIcon[];
onClick?: () => void;
}
export interface SetupChecklistProps {
title: string;
steps: SetupStep[];
className?: string;
}
export function SetupChecklist({ title, steps, className }: SetupChecklistProps) {
const doneCount = steps.filter((s) => s.status === "done").length;
const total = steps.length;
return (
<div className={cn("rounded-2xl bg-muted/70 p-3", className)}>
<div className="mb-3 flex items-center justify-between px-1">
<span className="text-xs font-medium text-foreground">{title}</span>
<div className="flex items-center gap-2">
<span className="text-xs tabular-nums text-muted-foreground">
{doneCount}/{total}
</span>
<CircularProgress done={doneCount} total={total} />
</div>
</div>
<div className="overflow-hidden rounded-xl bg-card">
{steps.map((step, index) => (
<React.Fragment key={step.id}>
{index > 0 && <div className="mx-4 h-px bg-border/50" />}
<SetupRow step={step} />
</React.Fragment>
))}
</div>
</div>
);
}
function CircularProgress({ done, total }: { done: number; total: number }) {
const size = 22;
const strokeWidth = 2;
const radius = (size - strokeWidth) / 2;
const circumference = 2 * Math.PI * radius;
const progress = total === 0 ? 0 : done / total;
const strokeDashoffset = circumference * (1 - progress);
return (
<svg
width={size}
height={size}
viewBox={`0 0 ${size} ${size}`}
aria-hidden
style={{ transform: "rotate(-90deg)" }}
>
{/* Track */}
<circle
cx={size / 2}
cy={size / 2}
r={radius}
fill="none"
stroke="currentColor"
strokeWidth={strokeWidth}
className="text-border"
/>
{/* Progress arc */}
<motion.circle
cx={size / 2}
cy={size / 2}
r={radius}
fill="none"
stroke="currentColor"
strokeWidth={strokeWidth}
strokeLinecap="round"
strokeDasharray={circumference}
initial={false}
animate={{ strokeDashoffset }}
transition={{ duration: 0.45, ease: "easeOut" }}
className="text-foreground"
/>
</svg>
);
}
function SetupRow({ step }: { step: SetupStep }) {
const done = step.status === "done";
return (
<button
type="button"
onClick={done ? undefined : step.onClick}
disabled={done}
className={cn(
"flex w-full items-center gap-3 px-4 py-3.5 text-left transition-colors",
!done && "cursor-pointer hover:bg-muted/50",
done && "cursor-default"
)}
>
<StepIcon status={step.status} />
<span
className={cn(
"flex-1 text-xs font-medium",
done ? "text-muted-foreground line-through decoration-muted-foreground/60" : "text-foreground"
)}
>
{step.label}
</span>
{step.icons && step.icons.length > 0 && !done && (
<div className="flex items-center gap-0.5" aria-hidden>
{step.icons.map((icon) => (
<span
key={icon.label}
title={icon.label}
className="flex size-[18px] items-center justify-center rounded-md text-[9px] font-bold text-white"
style={{ backgroundColor: icon.color }}
>
{icon.initial}
</span>
))}
</div>
)}
{!done && <ChevronRight className="size-4 shrink-0 text-muted-foreground" aria-hidden />}
</button>
);
}
function StepIcon({ status }: { status: SetupStepStatus }) {
if (status === "done") {
return (
<motion.span
initial={{ scale: 0.6, opacity: 0 }}
animate={{ scale: 1, opacity: 1 }}
transition={{ type: "spring", stiffness: 380, damping: 22 }}
className="flex size-5 shrink-0 items-center justify-center rounded-full bg-muted-foreground/25"
aria-label="Completed"
>
<Check className="size-3 text-muted-foreground" strokeWidth={2.5} aria-hidden />
</motion.span>
);
}
return (
<svg
width="20"
height="20"
viewBox="0 0 20 20"
fill="none"
aria-label="Pending"
className="shrink-0"
>
<circle
cx="10"
cy="10"
r="8"
stroke="currentColor"
strokeWidth="1.5"
strokeDasharray="2.8 2.2"
strokeLinecap="round"
className="text-muted-foreground/40"
/>
</svg>
);
}
A UX spec for this pattern — written for agents implementing or reusing it, not the code.
# Setup Checklist
## Summary
A compact onboarding card that surfaces a short list of setup steps, tracks progress with a circular arc indicator, and lets users work through each step sequentially or in any order. Completed steps collapse into struck-through, muted rows while remaining steps stay actionable.
## When to use
- First-run onboarding for AI agents, desktop apps, or workspaces (e.g., "Set up Computer", "Connect your tools").
- Post-signup activation flows where completing each step unlocks value (connected integrations, notifications, first task).
- Re-surfacing incomplete setup inside a dashboard or sidebar when the user still has steps pending.
## When not to use
- Long multi-step wizards (more than ~5 steps) — use a dedicated onboarding screen with a stepper instead.
- Flows where steps must be completed in strict sequence and blocking is required — the checklist pattern implies optional ordering.
- Critical setup that must gate the core experience — surface a blocking modal instead.
## Anatomy
- **Header bar**: title (product or object being set up) on the left; step counter (e.g., "1 / 3") and circular arc progress indicator on the right.
- **Step list**: a card containing one row per step, separated by hairline dividers.
- **Step row**: status icon + label + optional app-icon cluster + chevron (pending only).
- **Status icon — pending**: dashed-stroke circle (conveys "not yet started" without implying failure).
- **Status icon — done**: filled muted circle with a checkmark; label gains line-through decoration.
- **App icons**: small colored squares shown for steps tied to integrations; hidden once the step is done.
- **Chevron**: right-pointing arrow on actionable rows; removed once done.
## Behavior
- Clicking a pending row triggers that step's action (e.g., opens an OAuth sheet or a settings panel) and, on success, marks it done.
- Marking a step done animates its status icon (spring scale-in) and immediately updates the circular arc.
- The arc animates to the new progress value with a short ease-out tween each time a step is completed.
- All steps done: show a completion affordance (e.g., confetti, success state, or a "Replay" button in demos).
- Steps may be completed in any order unless the product constrains it; the component does not enforce ordering.
## Content guidelines
- Title: short verb phrase naming the object being configured — "Set up Computer", "Connect your workspace". Not "Onboarding".
- Step labels: imperative sentence fragments starting with a verb — "Connect your apps", "Turn on notifications". Max ~35 characters so they fit on one line.
- App icons: max 3–4; beyond that they become unreadable. Use brand colors for recognition.
## Accessibility
- The progress arc is decorative (`aria-hidden`); the counter text ("1/3") is the accessible progress signal.
- Each step row must be a real `<button>` element; disabled when done so it is skipped by keyboard navigation.
- Status icons carry `aria-label` ("Completed" / "Pending") for screen reader users.
- The step list should be wrapped in an `aria-live` region so screen readers announce completion events.
## Related patterns
- Analysis List — sequential item resolution during an AI analysis run, not user-driven.
- Tool Approval — one-at-a-time permission prompts, not a persistent checklist.