Skip to content

Open-source agentic AI Search Execution Platform. Track AI visibility, find opportunities, and let agents turn signals into prioritized actions and drafted fixes across ChatGPT, Claude, Gemini, Google AI Overviews, Google AI Mode, Perplexity, Grok, and Microsoft Copilot.

feat(ui): add the shared agent pieces: avatar, status pill, list dot, New pill and badge (#1760)

Cihana8697ae277b0
diff --git a/web/messages/en.json b/web/messages/en.json
index 4942cff9c..a29f001b7 100644
--- a/web/messages/en.json
+++ b/web/messages/en.json
@@ -3046,6 +3046,99 @@
"step": "Dismissed prompt suggestion"
}
},
+ "agentic": {
+ "avatar": {
+ "idle": "Agent · idle",
+ "working": "Agent · working",
+ "waiting": "Agent · needs you",
+ "done": "Agent · done",
+ "failed": "Agent · failed"
+ },
+ "status": {
+ "working": "Working",
+ "answering": "Answering",
+ "needsYou": "Needs you",
+ "done": "Done",
+ "answered": "Answered",
+ "ready": "Ready",
+ "planReady": "Plan ready",
+ "draft": "Draft",
+ "failed": "Failed"
+ },
+ "approval": {
+ "auto": "Auto",
+ "asks": "Asks you",
+ "logged": "Auto · logged",
+ "loggedTip": "Runs without a card in Full auto. Logged in the Activity log, with Undo.",
+ "click": "Needs your click",
+ "clickTip": "Goes live or leaves the workspace. Always needs your click, in every mode.",
+ "done": "Done"
+ },
+ "step": {
+ "label": "Step {number} · {state}",
+ "pending": "Not started",
+ "current": "Running",
+ "waiting": "Needs you",
+ "failed": "Failed",
+ "done": "Done"
+ },
+ "dot": {
+ "running": "Running",
+ "needsYou": "Needs you",
+ "done": "Done",
+ "failed": "Stopped or failed",
+ "idle": "Idle",
+ "paused": "Paused",
+ "progress": "Progress",
+ "legend": {
+ "title": "What the dots mean",
+ "running": "The agent is working. The thin line shows progress.",
+ "needsYou": "Waiting for your OK or click. Nothing moves until you reply.",
+ "done": "Finished. Bold until you open the result.",
+ "failed": "You stopped it, or a step failed. Open it to retry.",
+ "idle": "A normal chat. Nothing is running."
+ }
+ },
+ "newPill": "New",
+ "attention": {
+ "needsYou": "{count, plural, one {# needs you} other {# need you}}",
+ "items": "{count, plural, one {# item} other {# items}}",
+ "itemsNeedYou": "{count, plural, one {# item} other {# items}} · {needsYou}"
+ },
+ "tick": "Done",
+ "preview": {
+ "title": "Chat pieces",
+ "description": "The agent's shared pieces in every state, for design sign-off. Nothing here runs.",
+ "motion": "With Reduce motion on, nothing moves.",
+ "sections": {
+ "avatar": "Agent avatar",
+ "avatarList": "Agent avatar in the Agents list",
+ "statusPill": "Status pill",
+ "approvalPill": "Approval pills",
+ "steps": "Step states",
+ "dots": "List dots",
+ "newPill": "New pill",
+ "attention": "Attention badge",
+ "tick": "Done tick"
+ },
+ "avatarStates": {
+ "idle": "Idle",
+ "working": "Working",
+ "waiting": "Needs you",
+ "done": "Done",
+ "failed": "Failed"
+ },
+ "avatarListNote": "Still, at 30 px: grey when idle, paused or stopped",
+ "avatarSizes": "30, 26 and 22 px",
+ "size": "{size} px",
+ "progress": "Progress line",
+ "legend": "Legend",
+ "onIcon": "On a menu icon",
+ "countNeedsYou": "Count, 1 needs you",
+ "countNone": "Count, nothing needs you",
+ "tickPop": "Pops in once"
+ }
+ },
"audit": {
"title": "Site Audit",
"description": "Score any page against the 48-signal AEO/GEO",
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/chat/preview/page.test.tsx b/web/src/app/[locale]/(dashboard)/dashboard/chat/preview/page.test.tsx
new file mode 100644
index 000000000..bafc4f074
--- /dev/null
+++ b/web/src/app/[locale]/(dashboard)/dashboard/chat/preview/page.test.tsx
@@ -0,0 +1,118 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { NextIntlClientProvider } from 'next-intl';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import messages from '../../../../../../../messages/en.json';
+
+/**
+ * The Chat pieces preview (Chat P0, D1): there only with the new Chat on for
+ * the workspace, and every piece in every state on it.
+ */
+
+const session = vi.hoisted(() => ({
+ user: { id: 'user-1' } as { id: string } | null,
+ orgId: 'org-1',
+}));
+vi.mock('@/lib/supabase/server', () => ({
+ createClient: async () => ({
+ auth: { getUser: async () => ({ data: { user: session.user } }) },
+ from: () => ({
+ select: () => ({
+ eq: () => ({ single: async () => ({ data: { organization_id: session.orgId } }) }),
+ }),
+ }),
+ }),
+}));
+const notFound = vi.hoisted(() =>
+ vi.fn(() => {
+ throw new Error('NEXT_NOT_FOUND');
+ }),
+);
+vi.mock('next/navigation', () => ({ notFound }));
+
+import ChatPiecesPreviewPage from './page';
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+ session.user = { id: 'user-1' };
+ session.orgId = 'org-1';
+ notFound.mockClear();
+ vi.stubEnv('CHAT_AGENTIC', 'true');
+ vi.stubEnv('CHAT_AGENTIC_ORGS', '');
+});
+
+afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+ vi.unstubAllEnvs();
+});
+
+async function render() {
+ const ui = await ChatPiecesPreviewPage();
+ await act(async () =>
+ root.render(
+ <NextIntlClientProvider locale="en" messages={messages}>
+ {ui}
+ </NextIntlClientProvider>,
+ ),
+ );
+}
+const slots = (slot: string) => container.querySelectorAll(`[data-slot="${slot}"]`);
+
+describe('the Chat pieces preview', () => {
+ it.each([undefined, '', 'false'])('is not found with CHAT_AGENTIC=%s', async (value) => {
+ vi.stubEnv('CHAT_AGENTIC', value);
+ await expect(ChatPiecesPreviewPage()).rejects.toThrow('NEXT_NOT_FOUND');
+ expect(notFound).toHaveBeenCalledOnce();
+ });
+
+ it("is not found for a workspace Chat isn't on for", async () => {
+ vi.stubEnv('CHAT_AGENTIC_ORGS', 'org-2, org-3');
+ await expect(ChatPiecesPreviewPage()).rejects.toThrow('NEXT_NOT_FOUND');
+ vi.stubEnv('CHAT_AGENTIC_ORGS', 'org-2, ORG-1');
+ await render();
+ expect(container.querySelector('h1')!.textContent).toBe('Chat pieces');
+ });
+
+ it('is not found signed out', async () => {
+ session.user = null;
+ await expect(ChatPiecesPreviewPage()).rejects.toThrow('NEXT_NOT_FOUND');
+ });
+
+ it('shows every piece in every state', async () => {
+ await render();
+ expect(notFound).not.toHaveBeenCalled();
+ // 5 states in 3 sizes, and the 5 still ones of the Agents list.
+ const avatars = [...slots('agent-avatar')] as HTMLElement[];
+ const states = new Set(['idle', 'working', 'waiting', 'done', 'failed']);
+ const live = avatars.filter((el) => el.dataset.tone === 'live');
+ const muted = avatars.filter((el) => el.dataset.tone === 'muted');
+ expect(live).toHaveLength(15);
+ expect(new Set(live.map((el) => el.dataset.state))).toEqual(states);
+ expect(muted).toHaveLength(5);
+ expect(new Set(muted.map((el) => el.dataset.state))).toEqual(states);
+ expect(slots('status-pill')).toHaveLength(9);
+ expect(slots('approval-pill')).toHaveLength(5);
+ expect(slots('step-marker')).toHaveLength(5);
+ expect(slots('list-dot')).toHaveLength(6);
+ expect(slots('list-progress')).toHaveLength(1);
+ expect(slots('new-pill')).toHaveLength(1);
+ expect(slots('attention-dot')).toHaveLength(1);
+ expect(slots('attention-count')).toHaveLength(2);
+ expect(slots('done-tick')).toHaveLength(3);
+ });
+
+ it('gives every control on it a data-action id', async () => {
+ await render();
+ const controls = [...container.querySelectorAll<HTMLElement>('button, a, [role="button"]')];
+ expect(controls.map((el) => el.dataset.action)).toEqual(['chatMenu.dotLegend']);
+ });
+});
diff --git a/web/src/app/[locale]/(dashboard)/dashboard/chat/preview/page.tsx b/web/src/app/[locale]/(dashboard)/dashboard/chat/preview/page.tsx
new file mode 100644
index 000000000..ecc7a0843
--- /dev/null
+++ b/web/src/app/[locale]/(dashboard)/dashboard/chat/preview/page.tsx
@@ -0,0 +1,182 @@
+import { notFound } from 'next/navigation';
+import { useTranslations } from 'next-intl';
+import { Sparkles } from 'lucide-react';
+import { createClient } from '@/lib/supabase/server';
+import { chatAgenticEnabled } from '@/lib/chat/flag';
+import {
+ AGENT_AVATAR_STATES,
+ AgentAvatar,
+ type AgentAvatarSize,
+} from '@/components/agentic/agent-avatar';
+import { STATUS_PILL_STATES, StatusPill } from '@/components/agentic/status-pill';
+import { APPROVAL_PILL_KINDS, ApprovalPill } from '@/components/agentic/approval-pill';
+import { STEP_MARKER_STATES, StepMarker } from '@/components/agentic/step-marker';
+import { LIST_DOT_STATES, ListDot, ListProgress } from '@/components/agentic/list-dot';
+import { DotLegend } from '@/components/agentic/dot-legend';
+import { NewPill } from '@/components/agentic/new-pill';
+import { AttentionCount, AttentionDot } from '@/components/agentic/attention-badge';
+import { DoneTick } from '@/components/agentic/done-tick';
+
+const AVATAR_SIZES: readonly AgentAvatarSize[] = ['md', 'sm', 'xs'];
+
+function Section({
+ title,
+ note,
+ children,
+}: {
+ title: string;
+ /** A short muted line beside the title. */
+ note?: string;
+ children: React.ReactNode;
+}) {
+ return (
+ <section className="rounded-[14px] border bg-card p-4 shadow-[0_1px_2px_rgba(10,10,10,.04)]">
+ <h2 className="mb-4 text-sm font-semibold">
+ {title}
+ {note && <span className="ml-2 font-normal text-muted-foreground">{note}</span>}
+ </h2>
+ <div className="flex flex-wrap items-end gap-x-8 gap-y-5">{children}</div>
+ </section>
+ );
+}
+
+/** One piece in one state, its name under it. */
+function Sample({ caption, children }: { caption?: string; children: React.ReactNode }) {
+ return (
+ <figure className="m-0 flex flex-col items-center gap-2">
+ <div className="flex min-h-10 items-center justify-center gap-3">{children}</div>
+ {caption && (
+ <figcaption className="text-xs whitespace-nowrap text-muted-foreground">
+ {caption}
+ </figcaption>
+ )}
+ </figure>
+ );
+}
+
+/** Every shared agent piece in every state, side by side, in this theme. */
+function ChatPiecesPreview() {
+ const t = useTranslations('agentic.preview');
+ const tStep = useTranslations('agentic.step');
+ const tDot = useTranslations('agentic.dot');
+ return (
+ <div className="mx-auto max-w-5xl space-y-6">
+ <div>
+ <h1 className="text-2xl font-bold tracking-tight">{t('title')}</h1>
+ <p className="text-sm text-muted-foreground">{t('description')}</p>
+ <p className="text-sm text-muted-foreground">{t('motion')}</p>
+ </div>
+
+ <Section title={t('sections.avatar')} note={t('avatarSizes')}>
+ {AGENT_AVATAR_STATES.map((state) => (
+ <Sample key={state} caption={t(`avatarStates.${state}`)}>
+ {AVATAR_SIZES.map((size) => (
+ <AgentAvatar key={size} state={state} size={size} />
+ ))}
+ </Sample>
+ ))}
+ </Section>
+
+ <Section title={t('sections.avatarList')} note={t('avatarListNote')}>
+ {AGENT_AVATAR_STATES.map((state) => (
+ <Sample key={state} caption={t(`avatarStates.${state}`)}>
+ <AgentAvatar state={state} tone="muted" />
+ </Sample>
+ ))}
+ </Section>
+
+ <Section title={t('sections.statusPill')}>
+ {STATUS_PILL_STATES.map((state) => (
+ <Sample key={state}>
+ <StatusPill state={state} />
+ </Sample>
+ ))}
+ </Section>
+
+ <Section title={t('sections.approvalPill')}>
+ {APPROVAL_PILL_KINDS.map((kind) => (
+ <Sample key={kind}>
+ <ApprovalPill kind={kind} className="w-[104px]" />
+ </Sample>
+ ))}
+ </Section>
+
+ <Section title={t('sections.steps')}>
+ {STEP_MARKER_STATES.map((state, i) => (
+ <Sample key={state} caption={tStep(state)}>
+ <StepMarker number={i + 1} state={state} />
+ </Sample>
+ ))}
+ </Section>
+
+ <Section title={t('sections.dots')}>
+ {LIST_DOT_STATES.map((state) => (
+ <Sample key={state} caption={tDot(state)}>
+ <ListDot state={state} />
+ </Sample>
+ ))}
+ <Sample caption={t('progress')}>
+ <ListProgress value={30} className="w-28" />
+ </Sample>
+ <Sample caption={t('legend')}>
+ <DotLegend />
+ </Sample>
+ </Section>
+
+ <Section title={t('sections.newPill')}>
+ <Sample>
+ <NewPill />
+ </Sample>
+ </Section>
+
+ <Section title={t('sections.attention')}>
+ <Sample caption={t('onIcon')}>
+ <span className="relative inline-flex size-8 items-center justify-center rounded-lg bg-sidebar text-sidebar-foreground">
+ <Sparkles aria-hidden className="size-[17px]" />
+ <AttentionDot needsYou={1} className="absolute top-0.5 right-0.5" />
+ </span>
+ </Sample>
+ <Sample caption={t('countNeedsYou')}>
+ <AttentionCount count={3} needsYou={1} />
+ </Sample>
+ <Sample caption={t('countNone')}>
+ <AttentionCount count={3} />
+ </Sample>
+ </Section>
+
+ <Section title={t('sections.tick')}>
+ <Sample caption={t('size', { size: 20 })}>
+ <DoneTick />
+ </Sample>
+ <Sample caption={t('size', { size: 16 })}>
+ <DoneTick size="sm" />
+ </Sample>
+ <Sample caption={t('tickPop')}>
+ <DoneTick pop />
+ </Sample>
+ </Section>
+ </div>
+ );
+}
+
+/**
+ * Chat's shared agent pieces for design sign-off (Chat P0, D1). Only with the
+ * new Chat on for this workspace (CHAT_AGENTIC); otherwise the page isn't
+ * there. Not linked from the menu.
+ */
+export default async function ChatPiecesPreviewPage() {
+ const supabase = await createClient();
+ const {
+ data: { user },
+ } = await supabase.auth.getUser();
+ if (!user) notFound();
+
+ const { data: profile } = await supabase
+ .from('profiles')
+ .select('organization_id')
+ .eq('id', user.id)
+ .single();
+ if (!chatAgenticEnabled(profile?.organization_id)) notFound();
+
+ return <ChatPiecesPreview />;
+}
diff --git a/web/src/app/globals.css b/web/src/app/globals.css
index 5dd3bfcf7..653a3d8b4 100644
--- a/web/src/app/globals.css
+++ b/web/src/app/globals.css
@@ -270,3 +270,94 @@
}
}
}
+
+/*
+ * Chat's shared agent pieces (components/agentic), as in the Chat v2
+ * mockups: the avatar at work (breathes and bobs) and waiting (an amber ring
+ * that grows out), the list dots (a ring out of the running dot, a nudge of
+ * the one that needs you), the step under way and the done tick that pops in
+ * once. The avatar reuses the Content Agent's blink, spark, look and sweep.
+ * Each element that moves also takes motion-reduce:animate-none.
+ */
+@theme {
+ --color-agent-spark: #d9b98a;
+ --animate-agent-work:
+ agent-breathe 1.6s ease-in-out infinite, agent-bob 1.4s ease-in-out infinite;
+ --animate-agent-wait: agent-wait 2s ease-out infinite;
+ --animate-agent-dot-ring: agent-dot-ring 1.6s ease-out infinite;
+ --animate-agent-nudge: agent-nudge 2.4s ease-in-out infinite;
+ --animate-agent-step: agent-step 2s ease-in-out infinite;
+ --animate-agent-tick: agent-tick 0.42s ease-out 1;
+
+ @keyframes agent-bob {
+ 0%,
+ 100% {
+ transform: translateY(0) rotate(0);
+ }
+ 25% {
+ transform: translateY(-2px) rotate(-3deg);
+ }
+ 50% {
+ transform: translateY(0) rotate(0);
+ }
+ 75% {
+ transform: translateY(-1px) rotate(3deg);
+ }
+ }
+ @keyframes agent-wait {
+ 0% {
+ transform: scale(0.92);
+ opacity: 0.9;
+ }
+ 100% {
+ transform: scale(1.2);
+ opacity: 0;
+ }
+ }
+ @keyframes agent-dot-ring {
+ 0% {
+ transform: scale(0.5);
+ opacity: 0.8;
+ }
+ 100% {
+ transform: scale(1.3);
+ opacity: 0;
+ }
+ }
+ @keyframes agent-nudge {
+ 0%,
+ 90%,
+ 100% {
+ transform: translateY(0);
+ }
+ 93% {
+ transform: translateY(-2px);
+ }
+ 96% {
+ transform: translateY(1px);
+ }
+ }
+ /* The step's soft ring (its ring-* colour) widens and fades back. */
+ @keyframes agent-step {
+ 0%,
+ 100% {
+ box-shadow: 0 0 0 3px var(--tw-ring-color);
+ }
+ 50% {
+ box-shadow: 0 0 0 6px color-mix(in oklab, var(--tw-ring-color) 60%, transparent);
+ }
+ }
+ @keyframes agent-tick {
+ 0% {
+ transform: scale(0.55);
+ opacity: 0;
+ }
+ 65% {
+ transform: scale(1.12);
+ opacity: 1;
+ }
+ 100% {
+ transform: scale(1);
+ }
+ }
+}
diff --git a/web/src/components/agentic/agent-avatar.tsx b/web/src/components/agentic/agent-avatar.tsx
new file mode 100644
index 000000000..140bcdd1a
--- /dev/null
+++ b/web/src/components/agentic/agent-avatar.tsx
@@ -0,0 +1,159 @@
+import { useTranslations } from 'next-intl';
+import { cn } from '@/lib/utils';
+
+/**
+ * What the agent is doing, the same in Chat and Content Editor (Chat agentic
+ * plan §2): idle, working, waiting for the person, done, or stopped on a
+ * failed step (CHAT-03 items 16–21, the mockup's failed run).
+ */
+export type AgentAvatarState = 'idle' | 'working' | 'waiting' | 'done' | 'failed';
+
+export const AGENT_AVATAR_STATES: readonly AgentAvatarState[] = [
+ 'idle',
+ 'working',
+ 'waiting',
+ 'done',
+ 'failed',
+];
+
+/**
+ * live: Chat and Content Editor, where the agent at hand moves. muted: the
+ * Agents list (CHAT-21), where many agents sit still side by side: an idle,
+ * paused or stopped one is a grey tile and one waiting for the person wears
+ * a fixed amber ring.
+ */
+export type AgentAvatarTone = 'live' | 'muted';
+
+/** md: 30 px (answers, Agents list); sm: 26 px (runs tray, finder); xs: 22 px (card headers, menus). */
+export type AgentAvatarSize = 'md' | 'sm' | 'xs';
+
+const TILE: Record<AgentAvatarSize, string> = {
+ md: 'size-[30px] rounded-[10px]',
+ sm: 'size-[26px] rounded-[10px]',
+ xs: 'size-[22px] rounded-[7px]',
+};
+const RING: Record<AgentAvatarSize, string> = {
+ md: 'rounded-[13px]',
+ sm: 'rounded-[13px]',
+ xs: 'rounded-[10px]',
+};
+const ICON: Record<AgentAvatarSize, string> = {
+ md: 'size-[17px]',
+ sm: 'size-[17px]',
+ xs: 'size-[13px]',
+};
+
+/** The tile's colours: dark, or soft green done, soft red failed (both themes). */
+function tileTone(state: AgentAvatarState, tone: AgentAvatarTone): string {
+ if (state === 'done') return 'bg-green-100 text-green-700 dark:bg-green-950 dark:text-green-400';
+ if (state === 'failed') return 'bg-red-100 text-red-700 dark:bg-red-950 dark:text-red-400';
+ if (tone === 'muted' && state === 'idle') return 'bg-foreground/10 text-foreground/70';
+ return 'bg-foreground text-background';
+}
+
+/**
+ * The robot: live, its eyes blink, or look from side to side while it works,
+ * and a gold spark twinkles by its antenna; muted, it sits still, with no
+ * spark (the Agents list in the governance mockup).
+ */
+function Robot({
+ working,
+ live,
+ className,
+}: {
+ working: boolean;
+ live: boolean;
+ className: string;
+}) {
+ return (
+ <svg
+ viewBox="0 0 24 24"
+ aria-hidden
+ className={cn(
+ 'fill-none stroke-current [stroke-linecap:round] [stroke-linejoin:round] [stroke-width:1.8]',
+ className,
+ )}
+ >
+ <rect x="4" y="8" width="16" height="11" rx="3.5" />
+ <path d="M12 8V5" />
+ <circle cx="12" cy="4" r="1" className="fill-current" />
+ <g
+ className={cn(
+ live && '[transform-box:fill-box] [transform-origin:center] motion-reduce:animate-none',
+ live && (working ? 'animate-agent-look' : 'animate-agent-blink'),
+ )}
+ >
+ <path d="M9 13v1.5M15 13v1.5" className="[stroke-width:2.2]" />
+ </g>
+ <path d="M2 12.5v2M22 12.5v2" />
+ {live && (
+ <path
+ d="M19 2.5l.6 1.6 1.6.6-1.6.6-.6 1.6-.6-1.6-1.6-.6 1.6-.6z"
+ className="animate-agent-spark fill-agent-spark stroke-agent-spark [stroke-width:0.8] [transform-box:fill-box] [transform-origin:center] motion-reduce:animate-none"
+ />
+ )}
+ </svg>
+ );
+}
+
+/**
+ * The agent (Chat v2 mockups): a dark tile with the robot. Working, it
+ * breathes and bobs while a light sweeps over it; waiting for the person, an
+ * amber ring grows out of it; done, it turns soft green; failed, soft red.
+ * Never a spinning ring. In the Agents list (`tone="muted"`) it is still:
+ * grey when idle, a fixed amber ring when waiting. It says its state to a
+ * screen reader, unless the words beside it already do (`decorative`).
+ */
+export function AgentAvatar({
+ state = 'idle',
+ tone = 'live',
+ size = 'md',
+ decorative = false,
+ className,
+}: {
+ state?: AgentAvatarState;
+ tone?: AgentAvatarTone;
+ size?: AgentAvatarSize;
+ decorative?: boolean;
+ className?: string;
+}) {
+ const t = useTranslations('agentic.avatar');
+ const live = tone === 'live';
+ return (
+ <span
+ {...(decorative ? { 'aria-hidden': true } : { role: 'img', 'aria-label': t(state) })}
+ data-slot="agent-avatar"
+ data-state={state}
+ data-tone={tone}
+ className={cn(
+ 'relative inline-flex shrink-0 items-center justify-center',
+ TILE[size],
+ tileTone(state, tone),
+ live && state === 'working' && 'animate-agent-work motion-reduce:animate-none',
+ // The governance mockup's ring: 3 px soft amber, then a 1 px amber line.
+ !live &&
+ state === 'waiting' &&
+ 'ring-1 ring-amber-200 ring-offset-3 ring-offset-amber-100 dark:ring-amber-900 dark:ring-offset-amber-950',
+ className,
+ )}
+ >
+ {live && state === 'waiting' && (
+ <span
+ aria-hidden
+ className={cn(
+ 'pointer-events-none absolute -inset-1 animate-agent-wait border-2 border-amber-600/50 motion-reduce:animate-none dark:border-amber-400/50',
+ RING[size],
+ )}
+ />
+ )}
+ <Robot working={state === 'working'} live={live} className={ICON[size]} />
+ {/* The light passes over the robot, as the mockup's ::after does. */}
+ {live && state === 'working' && (
+ <span
+ aria-hidden
+ className="pointer-events-none absolute inset-0 animate-agent-sweep rounded-[inherit] bg-[linear-gradient(115deg,transparent_30%,color-mix(in_oklab,var(--background)_25%,transparent)_50%,transparent_70%)] bg-[length:250%_100%] motion-reduce:animate-none"
+ />
+ )}
+ </span>
+ );
+}
diff --git a/web/src/components/agentic/agentic.test.tsx b/web/src/components/agentic/agentic.test.tsx
new file mode 100644
index 000000000..85a8dfc40
--- /dev/null
+++ b/web/src/components/agentic/agentic.test.tsx
@@ -0,0 +1,355 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ReactElement } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { NextIntlClientProvider } from 'next-intl';
+import { describe, expect, it } from 'vitest';
+import messages from '../../../messages/en.json';
+import { AGENT_AVATAR_STATES, AgentAvatar } from './agent-avatar';
+import { STATUS_PILL_STATES, StatusPill } from './status-pill';
+import { APPROVAL_PILL_KINDS, ApprovalPill } from './approval-pill';
+import { STEP_MARKER_STATES, StepMarker } from './step-marker';
+import { LIST_DOT_STATES, ListDot, ListProgress } from './list-dot';
+import { NewPill } from './new-pill';
+import { AttentionCount, AttentionDot } from './attention-badge';
+import { DoneTick } from './done-tick';
+
+/**
+ * Chat's shared agent pieces (Chat agentic plan §2, Chat v2 design polish):
+ * each state says what it is to a screen reader, wears its mockup colours in
+ * both themes, and stops moving with reduced motion.
+ */
+
+function render(ui: ReactElement): HTMLElement {
+ const html = renderToStaticMarkup(
+ <NextIntlClientProvider locale="en" messages={messages}>
+ {ui}
+ </NextIntlClientProvider>,
+ );
+ const body = new DOMParser().parseFromString(`<div>${html}</div>`, 'text/html').body;
+ return body.firstElementChild as HTMLElement;
+}
+const root = (ui: ReactElement) => render(ui).firstElementChild as HTMLElement;
+const classOf = (el: Element) => el.getAttribute('class') ?? '';
+
+/** Every piece in every state, as the preview page shows them. */
+function everyPiece(): ReactElement {
+ return (
+ <>
+ {AGENT_AVATAR_STATES.map((state) => (
+ <AgentAvatar key={state} state={state} />
+ ))}
+ {AGENT_AVATAR_STATES.map((state) => (
+ <AgentAvatar key={`muted-${state}`} state={state} tone="muted" />
+ ))}
+ {STATUS_PILL_STATES.map((state) => (
+ <StatusPill key={state} state={state} />
+ ))}
+ {APPROVAL_PILL_KINDS.map((kind) => (
+ <ApprovalPill key={kind} kind={kind} />
+ ))}
+ {STEP_MARKER_STATES.map((state, i) => (
+ <StepMarker key={state} number={i + 1} state={state} />
+ ))}
+ {LIST_DOT_STATES.map((state) => (
+ <ListDot key={state} state={state} />
+ ))}
+ <ListProgress value={30} />
+ <NewPill />
+ <AttentionDot needsYou={1} />
+ <AttentionCount count={3} needsYou={1} />
+ <DoneTick pop />
+ </>
+ );
+}
+
+describe('AgentAvatar', () => {
+ it.each([
+ ['idle', 'Agent · idle'],
+ ['working', 'Agent · working'],
+ ['waiting', 'Agent · needs you'],
+ ['done', 'Agent · done'],
+ ['failed', 'Agent · failed'],
+ ] as const)('says %s to a screen reader, in Chat and in the Agents list', (state, label) => {
+ for (const tone of ['live', 'muted'] as const) {
+ const el = root(<AgentAvatar state={state} tone={tone} />);
+ expect(el.getAttribute('role')).toBe('img');
+ expect(el.getAttribute('aria-label')).toBe(label);
+ expect(el.dataset.state).toBe(state);
+ expect(el.dataset.tone).toBe(tone);
+ }
+ });
+
+ it('is hidden from screen readers when the words beside it say the state', () => {
+ const el = root(<AgentAvatar state="working" decorative />);
+ expect(el.getAttribute('aria-hidden')).toBe('true');
+ expect(el.hasAttribute('role')).toBe(false);
+ expect(el.hasAttribute('aria-label')).toBe(false);
+ });
+
+ it('works by breathing, bobbing and a sweep: its eyes look around, no spinning ring', () => {
+ const el = root(<AgentAvatar state="working" />);
+ expect(classOf(el)).toContain('animate-agent-work');
+ expect(el.querySelector('[class*="animate-agent-sweep"]')).not.toBeNull();
+ expect(el.querySelector('g[class*="animate-agent-look"]')).not.toBeNull();
+ expect(el.querySelector('[class*="animate-agent-wait"]')).toBeNull();
+ expect(el.outerHTML).not.toMatch(/animate-spin|rotate/);
+ });
+
+ it('waits for the person with an amber ring that grows out of it', () => {
+ const el = root(<AgentAvatar state="waiting" />);
+ const ring = el.querySelector('[class*="animate-agent-wait"]')!;
+ expect(classOf(ring)).toContain('border-amber-600/50');
+ expect(classOf(ring)).toContain('dark:border-amber-400/50');
+ expect(classOf(el)).not.toContain('animate-agent-work');
+ });
+
+ it('idles on the dark tile, blinking; turns soft green when done, in both themes', () => {
+ const idle = root(<AgentAvatar state="idle" />);
+ expect(classOf(idle)).toContain('bg-foreground');
+ expect(idle.querySelector('g[class*="animate-agent-blink"]')).not.toBeNull();
+ const done = root(<AgentAvatar state="done" />);
+ expect(classOf(done)).toContain('bg-green-100');
+ expect(classOf(done)).toContain('dark:bg-green-950');
+ expect(classOf(done)).not.toContain('bg-foreground');
+ });
+
+ it('turns soft red when a step failed, still blinking as the mockup does', () => {
+ const el = root(<AgentAvatar state="failed" />);
+ expect(classOf(el)).toContain('bg-red-100');
+ expect(classOf(el)).toContain('text-red-700');
+ expect(classOf(el)).toContain('dark:bg-red-950');
+ expect(classOf(el)).not.toContain('bg-foreground');
+ expect(el.querySelector('g[class*="animate-agent-blink"]')).not.toBeNull();
+ expect(el.querySelector('[class*="animate-agent-wait"]')).toBeNull();
+ });
+
+ it('sits still in the Agents list: grey when idle, a fixed amber ring when waiting', () => {
+ const idle = root(<AgentAvatar state="idle" tone="muted" />);
+ expect(classOf(idle)).toContain('bg-foreground/10');
+ expect(classOf(idle)).not.toContain('bg-foreground ');
+ const waiting = root(<AgentAvatar state="waiting" tone="muted" />);
+ expect(classOf(waiting)).toContain('ring-offset-amber-100');
+ expect(classOf(waiting)).toContain('ring-amber-200');
+ expect(classOf(waiting)).toContain('bg-foreground');
+ expect(waiting.querySelector('[class*="animate-agent-wait"]')).toBeNull();
+ for (const state of AGENT_AVATAR_STATES) {
+ const el = root(<AgentAvatar state={state} tone="muted" />);
+ expect(el.outerHTML).not.toContain('animate-');
+ // No spark: the governance mockup's robot has none.
+ expect(el.querySelector('[class*="agent-spark"]')).toBeNull();
+ }
+ // In Chat, idle stays the dark tile.
+ const chatIdle = root(<AgentAvatar state="idle" />);
+ expect(classOf(chatIdle)).toContain('bg-foreground text-background');
+ expect(chatIdle.querySelector('[class*="agent-spark"]')).not.toBeNull();
+ });
+
+ it.each([
+ ['md', 'size-[30px]'],
+ ['sm', 'size-[26px]'],
+ ['xs', 'size-[22px]'],
+ ] as const)('comes in the %s size of the mockup', (size, cls) => {
+ expect(classOf(root(<AgentAvatar size={size} />))).toContain(cls);
+ });
+});
+
+describe('StatusPill', () => {
+ it.each([
+ ['working', 'Working', 'border-foreground'],
+ ['answering', 'Answering', 'border-foreground'],
+ ['needsYou', 'Needs you', 'bg-amber-100'],
+ ['done', 'Done', 'bg-green-100'],
+ ['answered', 'Answered', 'bg-green-100'],
+ ['ready', 'Ready', 'bg-green-100'],
+ ['planReady', 'Plan ready', 'text-muted-foreground'],
+ ['draft', 'Draft', 'text-muted-foreground'],
+ ['failed', 'Failed', 'bg-red-100'],
+ ] as const)('shows %s as "%s"', (state, label, tone) => {
+ const el = root(<StatusPill state={state} />);
+ expect(el.textContent).toBe(label);
+ expect(el.dataset.state).toBe(state);
+ expect(el.hasAttribute('aria-hidden')).toBe(false);
+ expect(classOf(el)).toContain(tone);
+ });
+});
+
+describe('ApprovalPill', () => {
+ it.each([
+ ['auto', 'Auto'],
+ ['asks', 'Asks you'],
+ ['logged', 'Auto · logged'],
+ ['click', 'Needs your click'],
+ ['done', 'Done'],
+ ] as const)('shows %s as "%s"', (kind, label) => {
+ const el = root(<ApprovalPill kind={kind} />);
+ expect(el.textContent).toBe(label);
+ expect(el.dataset.state).toBe(kind);
+ });
+
+ it('keeps Needs your click the only dark pill', () => {
+ const dark = APPROVAL_PILL_KINDS.filter((kind) =>
+ classOf(root(<ApprovalPill kind={kind} />)).includes('bg-foreground'),
+ );
+ expect(dark).toEqual(['click']);
+ });
+
+ it('says why in a tooltip for Auto · logged and Needs your click, and dots the logged one', () => {
+ expect(root(<ApprovalPill kind="logged" />).title).toBe(
+ 'Runs without a card in Full auto. Logged in the Activity log, with Undo.',
+ );
+ expect(root(<ApprovalPill kind="click" />).title).toBe(
+ 'Goes live or leaves the workspace. Always needs your click, in every mode.',
+ );
+ expect(root(<ApprovalPill kind="auto" />).hasAttribute('title')).toBe(false);
+ expect(root(<ApprovalPill kind="logged" />).querySelector('[aria-hidden]')).not.toBeNull();
+ expect(root(<ApprovalPill kind="auto" />).querySelector('[aria-hidden]')).toBeNull();
+ });
+});
+
+describe('StepMarker', () => {
+ it.each([
+ ['pending', 'Step 2 · Not started', '2'],
+ ['current', 'Step 2 · Running', '2'],
+ ['waiting', 'Step 2 · Needs you', '2'],
+ ['failed', 'Step 2 · Failed', '!'],
+ ['done', 'Step 2 · Done', ''],
+ ] as const)('says %s with the step to a screen reader', (state, label, text) => {
+ const el = root(<StepMarker number={2} state={state} />);
+ expect(el.getAttribute('role')).toBe('img');
+ expect(el.getAttribute('aria-label')).toBe(label);
+ expect(el.textContent).toBe(text);
+ });
+
+ it('ticks a done step, and pulses only the one under way', () => {
+ expect(root(<StepMarker number={1} state="done" />).querySelector('svg path')).not.toBeNull();
+ const pulsing = STEP_MARKER_STATES.filter((state) =>
+ classOf(root(<StepMarker number={1} state={state} />)).includes('animate-agent-step'),
+ );
+ expect(pulsing).toEqual(['current']);
+ });
+});
+
+describe('ListDot', () => {
+ it.each([
+ ['running', 'Running'],
+ ['needsYou', 'Needs you'],
+ ['done', 'Done'],
+ ['failed', 'Stopped or failed'],
+ ['idle', 'Idle'],
+ ['paused', 'Paused'],
+ ] as const)('says %s to a screen reader and in its tooltip', (state, label) => {
+ const el = root(<ListDot state={state} />);
+ expect(el.getAttribute('role')).toBe('img');
+ expect(el.getAttribute('aria-label')).toBe(label);
+ expect(el.title).toBe(label);
+ });
+
+ it('rings while running, nudges when it needs you and ticks when done', () => {
+ const running = root(<ListDot state="running" />);
+ expect(running.querySelector('[class*="animate-agent-dot-ring"]')).not.toBeNull();
+ expect(classOf(root(<ListDot state="needsYou" />))).toContain('animate-agent-nudge');
+ expect(root(<ListDot state="done" />).querySelector('svg')).not.toBeNull();
+ expect(root(<ListDot state="idle" />).querySelector('[class*="animate-"]')).toBeNull();
+ });
+
+ it('is hidden from screen readers next to its own words', () => {
+ const el = root(<ListDot state="running" decorative />);
+ expect(el.getAttribute('aria-hidden')).toBe('true');
+ expect(el.hasAttribute('title')).toBe(false);
+ });
+
+ it('draws progress as a bar a screen reader reads, kept between 0 and 100', () => {
+ const bar = root(<ListProgress value={30} />);
+ expect(bar.getAttribute('role')).toBe('progressbar');
+ expect(bar.getAttribute('aria-label')).toBe('Progress');
+ expect(bar.getAttribute('aria-valuenow')).toBe('30');
+ expect((bar.firstElementChild as HTMLElement).style.width).toBe('30%');
+ expect(root(<ListProgress value={140} />).getAttribute('aria-valuenow')).toBe('100');
+ expect(root(<ListProgress value={-3} />).getAttribute('aria-valuenow')).toBe('0');
+ });
+});
+
+describe('NewPill', () => {
+ it('reads "New" in an outlined grey pill', () => {
+ const el = root(<NewPill />);
+ expect(el.textContent).toBe('New');
+ expect(classOf(el)).toContain('border');
+ expect(classOf(el)).toContain('rounded-full');
+ });
+});
+
+describe('the attention badge', () => {
+ it('dots a menu icon while something needs the person, and says how many', () => {
+ expect(render(<AttentionDot needsYou={0} />).innerHTML).toBe('');
+ expect(root(<AttentionDot needsYou={1} />).getAttribute('aria-label')).toBe('1 needs you');
+ expect(root(<AttentionDot needsYou={2} />).getAttribute('aria-label')).toBe('2 need you');
+ });
+
+ it('counts Home, with an amber dot first while any of it needs the person', () => {
+ expect(render(<AttentionCount count={0} />).innerHTML).toBe('');
+ const needs = root(<AttentionCount count={3} needsYou={1} />);
+ expect(needs.getAttribute('role')).toBe('img');
+ expect(needs.getAttribute('aria-label')).toBe('3 items · 1 needs you');
+ expect(needs.textContent).toBe('3');
+ expect(needs.querySelector('[class*="bg-amber-600"]')).not.toBeNull();
+ const calm = root(<AttentionCount count={1} />);
+ expect(calm.getAttribute('aria-label')).toBe('1 item');
+ expect(calm.querySelector('[class*="bg-amber-600"]')).toBeNull();
+ });
+});
+
+describe('DoneTick', () => {
+ it('says Done, and pops in only when asked', () => {
+ const el = root(<DoneTick />);
+ expect(el.getAttribute('aria-label')).toBe('Done');
+ expect(classOf(el)).not.toContain('animate-agent-tick');
+ expect(classOf(root(<DoneTick pop />))).toContain('animate-agent-tick');
+ expect(root(<DoneTick decorative />).getAttribute('aria-hidden')).toBe('true');
+ });
+});
+
+describe('every piece', () => {
+ it('stops every motion with reduced motion', () => {
+ const all = render(everyPiece());
+ const moving = [...all.querySelectorAll('[class*="animate-"]')];
+ expect(moving.length).toBeGreaterThan(10);
+ for (const el of moving) expect(classOf(el)).toContain('motion-reduce:animate-none');
+ const sliding = [...all.querySelectorAll('[class*="transition"]')];
+ for (const el of sliding) expect(classOf(el)).toContain('motion-reduce:transition-none');
+ });
+
+ it('gives each coloured state its dark-theme colour', () => {
+ const all = render(everyPiece());
+ for (const el of [all, ...all.querySelectorAll('*')]) {
+ const cls = classOf(el).split(/\s+/);
+ for (const hue of ['green', 'amber', 'red']) {
+ const light = cls.filter((c) =>
+ new RegExp(`^(bg|text|border|ring|ring-offset)-${hue}-`).test(c),
+ );
+ for (const c of light) {
+ const kind = c.slice(0, c.indexOf(`-${hue}-`));
+ expect(cls.some((d) => d.startsWith(`dark:${kind}-${hue}-`))).toBe(true);
+ }
+ }
+ }
+ });
+
+ it('only moves with an animation globals.css defines', () => {
+ const css = readFileSync(join(__dirname, '../../app/globals.css'), 'utf8');
+ const used = new Set(
+ [...render(everyPiece()).querySelectorAll('[class*="animate-agent"]')].flatMap((el) =>
+ classOf(el)
+ .split(/\s+/)
+ .filter((c) => c.startsWith('animate-agent-')),
+ ),
+ );
+ expect(used.size).toBeGreaterThan(5);
+ for (const cls of used) expect(css).toContain(`--${cls}:`);
+ });
+
+ it('has nothing clickable: the pieces are shown, not pressed', () => {
+ const all = render(everyPiece());
+ expect(all.querySelectorAll('button, a, [role="button"], [tabindex]')).toHaveLength(0);
+ });
+});
diff --git a/web/src/components/agentic/approval-pill.tsx b/web/src/components/agentic/approval-pill.tsx
new file mode 100644
index 000000000..7b4e8d881
--- /dev/null
+++ b/web/src/components/agentic/approval-pill.tsx
@@ -0,0 +1,59 @@
+import { useTranslations } from 'next-intl';
+import { cn } from '@/lib/utils';
+
+/**
+ * How a step runs (CHAT-20 approval classes, CHAT-23 P10): READ runs by
+ * itself (auto); a WRITE asks, or runs and is logged in Full auto; an
+ * EXECUTE always needs the person's click; done once it ran.
+ */
+export type ApprovalPillKind = 'auto' | 'asks' | 'logged' | 'click' | 'done';
+
+export const APPROVAL_PILL_KINDS: readonly ApprovalPillKind[] = [
+ 'auto',
+ 'asks',
+ 'logged',
+ 'click',
+ 'done',
+];
+
+const KIND: Record<ApprovalPillKind, string> = {
+ auto: 'bg-muted text-foreground/70',
+ asks: 'bg-amber-100 text-amber-700 dark:bg-amber-950 dark:text-amber-300',
+ logged: 'bg-muted text-foreground/70',
+ click: 'bg-foreground text-background',
+ done: 'bg-green-100 text-green-700 dark:bg-green-950 dark:text-green-300',
+};
+
+/** The two that need saying why, in their tooltip (the mockup's titles). */
+const TIP: Partial<Record<ApprovalPillKind, 'loggedTip' | 'clickTip'>> = {
+ logged: 'loggedTip',
+ click: 'clickTip',
+};
+
+/**
+ * A step's approval pill (Chat v2 design polish, "Status pills"): soft grey
+ * Auto, soft amber Asks you, grey Auto · logged with a small dot, soft green
+ * Done, and Needs your click, the only dark pill, so it stands out. In a
+ * step row the pill takes a fixed width (`className`), so the pills line up.
+ */
+export function ApprovalPill({ kind, className }: { kind: ApprovalPillKind; className?: string }) {
+ const t = useTranslations('agentic.approval');
+ const tip = TIP[kind];
+ return (
+ <span
+ data-slot="approval-pill"
+ data-state={kind}
+ title={tip ? t(tip) : undefined}
+ className={cn(
+ 'inline-flex shrink-0 items-center justify-center rounded-full px-2 py-px text-[11px] leading-[14px] whitespace-nowrap',
+ KIND[kind],
+ className,
+ )}
+ >
+ {kind === 'logged' && (
+ <span aria-hidden className="mr-[5px] size-[5px] shrink-0 rounded-full bg-current" />
+ )}
+ {t(kind)}
+ </span>
+ );
+}
diff --git a/web/src/components/agentic/attention-badge.tsx b/web/src/components/agentic/attention-badge.tsx
new file mode 100644
index 000000000..965916192
--- /dev/null
+++ b/web/src/components/agentic/attention-badge.tsx
@@ -0,0 +1,70 @@
+import { useTranslations } from 'next-intl';
+import { formatNumber } from '@/lib/format';
+import { cn } from '@/lib/utils';
+
+/**
+ * The amber dot on the Chat icon in the main menu (or Content's, when a page
+ * needs the person), while anything needs them (Chat agentic plan §2,
+ * "Attention badge"). The caller places it on the icon's corner. Nothing
+ * shows at 0.
+ */
+export function AttentionDot({ needsYou, className }: { needsYou: number; className?: string }) {
+ const t = useTranslations('agentic.attention');
+ if (needsYou <= 0) return null;
+ return (
+ <span
+ role="img"
+ aria-label={t('needsYou', { count: needsYou })}
+ data-slot="attention-dot"
+ className={cn(
+ 'inline-block size-[9px] shrink-0 rounded-full border-2 border-sidebar bg-amber-600 dark:bg-amber-400',
+ className,
+ )}
+ />
+ );
+}
+
+/**
+ * The count on Home (Chat's Inbox in the mockup): how many items wait there,
+ * with an amber dot first while any of them needs the person. Nothing shows
+ * at 0.
+ */
+export function AttentionCount({
+ count,
+ needsYou = 0,
+ className,
+}: {
+ count: number;
+ /** Of `count`, the ones that need the person. */
+ needsYou?: number;
+ className?: string;
+}) {
+ const t = useTranslations('agentic.attention');
+ if (count <= 0) return null;
+ const label =
+ needsYou > 0
+ ? t('itemsNeedYou', { count, needsYou: t('needsYou', { count: needsYou }) })
+ : t('items', { count });
+ return (
+ <span
+ role="img"
+ aria-label={label}
+ title={label}
+ data-slot="attention-count"
+ className={cn('inline-flex shrink-0 items-center gap-1.5', className)}
+ >
+ {needsYou > 0 && (
+ <span
+ aria-hidden
+ className="size-[7px] shrink-0 rounded-full bg-amber-600 dark:bg-amber-400"
+ />
+ )}
+ <span
+ aria-hidden
+ className="min-w-[22px] rounded-[6px] bg-foreground/10 px-1.5 text-center text-[11px] leading-[18px] text-foreground/80 tabular-nums"
+ >
+ {formatNumber(count)}
+ </span>
+ </span>
+ );
+}
diff --git a/web/src/components/agentic/done-tick.tsx b/web/src/components/agentic/done-tick.tsx
new file mode 100644
index 000000000..ec1dc77f7
--- /dev/null
+++ b/web/src/components/agentic/done-tick.tsx
@@ -0,0 +1,57 @@
+import { useTranslations } from 'next-intl';
+import { cn } from '@/lib/utils';
+
+/** The check inside every done mark: a rounded stroke, never a filled circle. */
+export function TickIcon({ className }: { className?: string }) {
+ return (
+ <svg
+ viewBox="0 0 24 24"
+ aria-hidden
+ className={cn(
+ 'fill-none stroke-current [stroke-linecap:round] [stroke-linejoin:round] [stroke-width:3.4]',
+ className,
+ )}
+ >
+ <path d="M5.5 12.5l4.2 4.2L18.5 8" />
+ </svg>
+ );
+}
+
+/** The soft green circle around a tick: the tick, a done step, a done list dot. */
+export const TICK_CIRCLE = 'bg-green-100 text-green-600 dark:bg-green-950 dark:text-green-400';
+
+/**
+ * Done (Chat v2 design polish, "Done tick"): a soft green circle with a green
+ * check, for completed steps, checklists and included rows. `pop` animates it
+ * in once, for a success moment; reduced motion shows it at once.
+ */
+export function DoneTick({
+ size = 'md',
+ pop = false,
+ decorative = false,
+ className,
+}: {
+ /** md: 20 px (steps, checklists); sm: 16 px (beside small text). */
+ size?: 'md' | 'sm';
+ pop?: boolean;
+ /** Next to words that already say it's done: hidden from screen readers. */
+ decorative?: boolean;
+ className?: string;
+}) {
+ const t = useTranslations('agentic');
+ return (
+ <span
+ {...(decorative ? { 'aria-hidden': true } : { role: 'img', 'aria-label': t('tick') })}
+ data-slot="done-tick"
+ className={cn(
+ 'inline-flex shrink-0 items-center justify-center rounded-full align-middle',
+ TICK_CIRCLE,
+ size === 'md' ? 'size-5' : 'size-4',
+ pop && 'animate-agent-tick motion-reduce:animate-none',
+ className,
+ )}
+ >
+ <TickIcon className={size === 'md' ? 'size-[13px]' : 'size-[11px]'} />
+ </span>
+ );
+}
diff --git a/web/src/components/agentic/dot-legend.test.tsx b/web/src/components/agentic/dot-legend.test.tsx
new file mode 100644
index 000000000..e3291e8dc
--- /dev/null
+++ b/web/src/components/agentic/dot-legend.test.tsx
@@ -0,0 +1,75 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { NextIntlClientProvider } from 'next-intl';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import messages from '../../../messages/en.json';
+import { DotLegend } from './dot-legend';
+
+/**
+ * "?" beside Agents at work (CHAT-23 `chatMenu.dotLegend`): opens "What the
+ * dots mean" and closes with Esc, focus back on the button.
+ */
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(async () => {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ root = createRoot(container);
+ await act(async () =>
+ root.render(
+ <NextIntlClientProvider locale="en" messages={messages}>
+ <DotLegend />
+ </NextIntlClientProvider>,
+ ),
+ );
+});
+
+afterEach(() => {
+ act(() => root.unmount());
+ container.remove();
+});
+
+const trigger = () => container.querySelector<HTMLButtonElement>('button')!;
+const popup = () => document.querySelector<HTMLElement>('[data-slot="popover-content"]');
+
+describe('DotLegend', () => {
+ it('is a labelled button with its CHAT-23 id', () => {
+ expect(container.querySelectorAll('button')).toHaveLength(1);
+ expect(trigger().dataset.action).toBe('chatMenu.dotLegend');
+ // The button says what it opens, in the popover's own words.
+ expect(trigger().getAttribute('aria-label')).toBe('What the dots mean');
+ expect(trigger().title).toBe('What the dots mean');
+ expect(popup()).toBeNull();
+ });
+
+ it('explains every dot, in the mockup order, and closes with Esc', async () => {
+ trigger().focus();
+ await act(async () => trigger().click());
+ await act(async () => {});
+ expect(popup()!.textContent).toContain('What the dots mean');
+ const rows = [...popup()!.querySelectorAll('li')].map(
+ (li) => li.querySelector('b')!.textContent,
+ );
+ expect(rows).toEqual(['Running', 'Needs you', 'Done', 'Stopped or failed', 'Idle']);
+ // The words say the state: the dots beside them are not read twice.
+ for (const dot of popup()!.querySelectorAll('[data-slot="list-dot"]')) {
+ expect(dot.getAttribute('aria-hidden')).toBe('true');
+ }
+ // The open popover stops reduced-motion users' zoom too.
+ expect(popup()!.className).toContain('motion-reduce:animate-none!');
+
+ await act(async () =>
+ document.activeElement!.dispatchEvent(
+ new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }),
+ ),
+ );
+ await act(async () => {});
+ expect(popup()).toBeNull();
+ expect(document.activeElement).toBe(trigger());
+ });
+});
diff --git a/web/src/components/agentic/dot-legend.tsx b/web/src/components/agentic/dot-legend.tsx
new file mode 100644
index 000000000..78225900c
--- /dev/null
+++ b/web/src/components/agentic/dot-legend.tsx
@@ -0,0 +1,54 @@
+'use client';
+
+import { useTranslations } from 'next-intl';
+import { Popover, PopoverContent, PopoverTitle, PopoverTrigger } from '@/components/ui/popover';
+import { cn } from '@/lib/utils';
+import { ListDot, type ListDotState } from './list-dot';
+
+/** The legend's rows, in the mockup's order: paused stays out of it. */
+const LEGEND: readonly ListDotState[] = ['running', 'needsYou', 'done', 'failed', 'idle'];
+
+/**
+ * "?" beside a list of runs (Agents at work): opens "What the dots mean", one
+ * row per dot (CHAT-23 `chatMenu.dotLegend`). Esc, a click outside or the
+ * button closes it, and focus goes back to the button.
+ */
+export function DotLegend({ className }: { className?: string }) {
+ const t = useTranslations('agentic.dot');
+ return (
+ <Popover>
+ <PopoverTrigger
+ data-action="chatMenu.dotLegend"
+ aria-label={t('legend.title')}
+ title={t('legend.title')}
+ className={cn(
+ 'inline-flex size-4 shrink-0 items-center justify-center rounded-full border border-foreground/20 text-[10px] leading-none text-muted-foreground outline-none hover:text-foreground focus-visible:ring-[3px] focus-visible:ring-ring/50',
+ className,
+ )}
+ >
+ ?
+ </PopoverTrigger>
+ <PopoverContent
+ align="start"
+ className="w-[280px] rounded-[14px] p-1.5 shadow-[0_12px_32px_rgba(10,10,10,.12)] motion-reduce:animate-none!"
+ >
+ <PopoverTitle className="px-2 pt-2 pb-1 text-[11px] font-normal tracking-[.4px] text-muted-foreground uppercase">
+ {t('legend.title')}
+ </PopoverTitle>
+ <ul className="grid gap-1.5 p-2">
+ {LEGEND.map((state) => (
+ <li key={state} className="flex items-start gap-2.5 text-[12.5px]">
+ <ListDot state={state} decorative className="mt-0.5" />
+ <span>
+ <b className="block font-bold">{t(state)}</b>
+ <span className="block text-[11.5px] text-muted-foreground">
+ {t(`legend.${state}`)}
+ </span>
+ </span>
+ </li>
+ ))}
+ </ul>
+ </PopoverContent>
+ </Popover>
+ );
+}
diff --git a/web/src/components/agentic/list-dot.tsx b/web/src/components/agentic/list-dot.tsx
new file mode 100644
index 000000000..4e68366e1
--- /dev/null
+++ b/web/src/components/agentic/list-dot.tsx
@@ -0,0 +1,103 @@
+import { useTranslations } from 'next-intl';
+import { cn } from '@/lib/utils';
+import { TICK_CIRCLE, TickIcon } from './done-tick';
+
+/**
+ * A chat's or a run's state in a list (Chat agentic plan §2, "List status
+ * dot"): the chat list, Agents at work, Content Library and Action Center rows.
+ */
+export type ListDotState = 'idle' | 'running' | 'needsYou' | 'done' | 'failed' | 'paused';
+
+export const LIST_DOT_STATES: readonly ListDotState[] = [
+ 'running',
+ 'needsYou',
+ 'done',
+ 'failed',
+ 'idle',
+ 'paused',
+];
+
+/**
+ * The list dot (Chat v2 mockups): a grey dot when nothing runs; a dark one
+ * with a ring that grows out while running; amber with a soft halo, nudging
+ * now and then, when it needs the person; a green tick when done; red on soft
+ * red when it stopped or failed; a lighter grey while paused. Motion stops
+ * with reduced motion. It says its state to a screen reader and in its
+ * tooltip, unless the words beside it already do (`decorative`).
+ */
+export function ListDot({
+ state,
+ decorative = false,
+ className,
+}: {
+ state: ListDotState;
+ decorative?: boolean;
+ className?: string;
+}) {
+ const t = useTranslations('agentic.dot');
+ return (
+ <span
+ {...(decorative
+ ? { 'aria-hidden': true }
+ : { role: 'img', 'aria-label': t(state), title: t(state) })}
+ data-slot="list-dot"
+ data-state={state}
+ className={cn(
+ 'relative inline-flex size-4 shrink-0 items-center justify-center rounded-full',
+ state === 'needsYou' && 'animate-agent-nudge motion-reduce:animate-none',
+ state === 'done' && TICK_CIRCLE,
+ state === 'failed' && 'bg-red-100 dark:bg-red-950',
+ className,
+ )}
+ >
+ {state === 'done' ? (
+ <TickIcon className="size-[11px]" />
+ ) : (
+ <span
+ aria-hidden
+ className={cn(
+ 'size-1.5 rounded-full',
+ state === 'idle' && 'bg-foreground/20',
+ state === 'paused' && 'bg-foreground/35',
+ state === 'running' && 'bg-foreground',
+ state === 'needsYou' &&
+ 'bg-amber-600 ring-3 ring-amber-100 dark:bg-amber-400 dark:ring-amber-950',
+ state === 'failed' && 'bg-red-600 dark:bg-red-400',
+ )}
+ />
+ )}
+ {state === 'running' && (
+ <span
+ aria-hidden
+ className="pointer-events-none absolute inset-0.5 animate-agent-dot-ring rounded-full border-[1.5px] border-foreground opacity-0 motion-reduce:animate-none"
+ />
+ )}
+ </span>
+ );
+}
+
+/**
+ * The thin progress line under a running row (Chat agentic plan §2): how far
+ * the run is, out of 100. Moves to a new value smoothly, at once with reduced
+ * motion.
+ */
+export function ListProgress({ value, className }: { value: number; className?: string }) {
+ const t = useTranslations('agentic.dot');
+ const percent = Math.min(100, Math.max(0, Math.round(value)));
+ return (
+ <span
+ role="progressbar"
+ aria-label={t('progress')}
+ aria-valuemin={0}
+ aria-valuemax={100}
+ aria-valuenow={percent}
+ data-slot="list-progress"
+ className={cn('block h-[3px] overflow-hidden rounded-[3px] bg-border', className)}
+ >
+ <span
+ className="block h-full bg-foreground transition-[width] duration-600 motion-reduce:transition-none"
+ style={{ width: `${percent}%` }}
+ />
+ </span>
+ );
+}
diff --git a/web/src/components/agentic/new-pill.tsx b/web/src/components/agentic/new-pill.tsx
new file mode 100644
index 000000000..d6f80284f
--- /dev/null
+++ b/web/src/components/agentic/new-pill.tsx
@@ -0,0 +1,21 @@
+import { useTranslations } from 'next-intl';
+import { cn } from '@/lib/utils';
+
+/**
+ * "New" on a new area or feature (Chat agentic plan §2): an outlined grey
+ * pill, shown until the person first opens it (the caller decides when).
+ */
+export function NewPill({ className }: { className?: string }) {
+ const t = useTranslations('agentic');
+ return (
+ <span
+ data-slot="new-pill"
+ className={cn(
+ 'inline-flex shrink-0 items-center rounded-full border border-foreground/20 bg-card px-[7px] text-[10.5px] leading-4 font-medium whitespace-nowrap text-foreground/80',
+ className,
+ )}
+ >
+ {t('newPill')}
+ </span>
+ );
+}
diff --git a/web/src/components/agentic/status-pill.tsx b/web/src/components/agentic/status-pill.tsx
new file mode 100644
index 000000000..6186e0cf4
--- /dev/null
+++ b/web/src/components/agentic/status-pill.tsx
@@ -0,0 +1,73 @@
+import { useTranslations } from 'next-intl';
+import { cn } from '@/lib/utils';
+
+/** Where a chat or a page stands, in the pill next to its title (Chat agentic plan §2). */
+export type StatusPillState =
+ | 'working'
+ | 'answering'
+ | 'needsYou'
+ | 'done'
+ | 'answered'
+ | 'ready'
+ | 'planReady'
+ | 'draft'
+ | 'failed';
+
+export const STATUS_PILL_STATES: readonly StatusPillState[] = [
+ 'working',
+ 'answering',
+ 'needsYou',
+ 'done',
+ 'answered',
+ 'ready',
+ 'planReady',
+ 'draft',
+ 'failed',
+];
+
+type Tone = 'ink' | 'grey' | 'green' | 'amber' | 'red';
+
+const TONE_OF: Record<StatusPillState, Tone> = {
+ working: 'ink',
+ answering: 'ink',
+ needsYou: 'amber',
+ done: 'green',
+ answered: 'green',
+ ready: 'green',
+ planReady: 'grey',
+ draft: 'grey',
+ failed: 'red',
+};
+
+const TONE: Record<Tone, string> = {
+ ink: 'border-foreground text-foreground',
+ grey: 'border-border text-muted-foreground',
+ green:
+ 'border-green-200 bg-green-100 text-green-700 dark:border-green-900 dark:bg-green-950 dark:text-green-300',
+ amber:
+ 'border-amber-200 bg-amber-100 text-amber-700 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-300',
+ red: 'border-red-200 bg-red-100 text-red-700 dark:border-red-900 dark:bg-red-950 dark:text-red-300',
+};
+
+/**
+ * The status pill beside a chat's or a page's title (Chat v2 mockups):
+ * Working with a dark outline, Needs you in amber, Done, Answered and Ready
+ * in green, Draft and Plan ready in grey, Failed in red. Its words are its
+ * state, so a screen reader reads it as it is.
+ */
+export function StatusPill({ state, className }: { state: StatusPillState; className?: string }) {
+ const t = useTranslations('agentic.status');
+ return (
+ <span
+ data-slot="status-pill"
+ data-state={state}
+ className={cn(
+ 'inline-flex shrink-0 items-center rounded-full border px-[9px] py-px text-[11.5px] leading-[14px] whitespace-nowrap',
+ TONE[TONE_OF[state]],
+ className,
+ )}
+ >
+ {t(state)}
+ </span>
+ );
+}
diff --git a/web/src/components/agentic/step-marker.tsx b/web/src/components/agentic/step-marker.tsx
new file mode 100644
index 000000000..2110ec978
--- /dev/null
+++ b/web/src/components/agentic/step-marker.tsx
@@ -0,0 +1,64 @@
+import { useTranslations } from 'next-intl';
+import { cn } from '@/lib/utils';
+import { TICK_CIRCLE, TickIcon } from './done-tick';
+
+/** Where a step of a run stands (Chat v2 design polish, "Step states"). */
+export type StepMarkerState = 'pending' | 'current' | 'waiting' | 'failed' | 'done';
+
+export const STEP_MARKER_STATES: readonly StepMarkerState[] = [
+ 'pending',
+ 'current',
+ 'waiting',
+ 'failed',
+ 'done',
+];
+
+const STATE: Record<StepMarkerState, string> = {
+ pending: 'border-foreground/20 bg-card text-muted-foreground',
+ current:
+ 'animate-agent-step border-amber-500 bg-card text-amber-700 ring-3 ring-amber-100 motion-reduce:animate-none dark:border-amber-400 dark:text-amber-300 dark:ring-amber-950',
+ waiting:
+ 'border-amber-600 bg-amber-100 text-amber-700 dark:border-amber-500 dark:bg-amber-950 dark:text-amber-300',
+ failed:
+ 'border-red-600 bg-red-100 text-red-700 dark:border-red-500 dark:bg-red-950 dark:text-red-300',
+ done: cn('border-transparent', TICK_CIRCLE),
+};
+
+/**
+ * A step's number circle in a plan or a run: grey outlined while it waits its
+ * turn; with a soft amber ring that pulses while it runs (still with reduced
+ * motion); amber while it waits for the person; soft red with "!" when it
+ * failed; a green tick once done. It says the step and its state to a screen
+ * reader ("Step 2 · Running").
+ */
+export function StepMarker({
+ number,
+ state,
+ className,
+}: {
+ /** The step's place in the run, from 1. */
+ number: number;
+ state: StepMarkerState;
+ className?: string;
+}) {
+ const t = useTranslations('agentic.step');
+ return (
+ <span
+ role="img"
+ aria-label={t('label', { number, state: t(state) })}
+ data-slot="step-marker"
+ data-state={state}
+ className={cn(
+ 'inline-flex size-5 shrink-0 items-center justify-center rounded-full border-[1.5px] text-[11px] leading-none font-semibold tabular-nums',
+ STATE[state],
+ className,
+ )}
+ >
+ {state === 'done' ? (
+ <TickIcon className="size-[13px]" />
+ ) : (
+ <span aria-hidden>{state === 'failed' ? '!' : number}</span>
+ )}
+ </span>
+ );
+}