Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Chat): add chat layout components — MessageList, Message, Bubble, Metadata, SystemMessage (#1180)

Cindy Zhang3e855df0d2bd
diff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsx
new file mode 100644
index 0000000000..f67c3b101d
--- /dev/null
+++ b/apps/storybook/stories/Chat.stories.tsx
@@ -0,0 +1,612 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSChatMessageList,
+ XDSChatMessage,
+ XDSChatMessageBubble,
+ XDSChatMessageMetadata,
+ XDSChatSystemMessage,
+} from '@xds/core/Chat';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSMarkdown} from '@xds/core/Markdown';
+import {XDSToken} from '@xds/core/Token';
+import {XDSHStack} from '@xds/core/Stack';
+import {XDSCodeBlock} from '@xds/core/CodeBlock';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSTimestamp} from '@xds/core/Timestamp';
+import {HandThumbUpIcon, HandThumbDownIcon} from '@heroicons/react/24/outline';
+import {ClipboardDocumentIcon} from '@heroicons/react/24/outline';
+import {useState, useEffect, useCallback} from 'react';
+
+const meta: Meta<typeof XDSChatMessageList> = {
+ title: 'Chat/XDSChatMessageList',
+ component: XDSChatMessageList,
+ tags: ['autodocs'],
+};
+export default meta;
+
+export const Minimal: StoryObj = {
+ name: 'Minimal',
+ render: () => (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>How do I center a div?</XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage sender="assistant">
+ <XDSMarkdown density="compact">{`There are several ways:
+
+**Flexbox** (most common):
+\`\`\`css
+display: flex;
+justify-content: center;
+align-items: center;
+\`\`\`
+
+**Grid** (simplest):
+\`\`\`css
+display: grid;
+place-items: center;
+\`\`\`
+
+Both work great.`}</XDSMarkdown>
+ </XDSChatMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>
+ What about absolute positioning?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage sender="assistant">
+ <XDSMarkdown density="compact">{`You can, but prefer flexbox or grid — they handle responsive layouts much better.`}</XDSMarkdown>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const Standard: StoryObj = {
+ name: 'Standard',
+ render: () => (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
+ <XDSChatMessage sender="user" name="Cindy">
+ <XDSChatMessageBubble>
+ Can you look at the chat component spec?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSMarkdown density="compact">{`I looked into the **chat component spec** and have some thoughts.
+
+The compound pattern we discussed handles all the 3P patterns:
+
+- **V0/Copilot**: artifact pane alongside chat
+- **Jules**: async session review
+- **Codex**: collapsed chain-of-thought
+
+No new components needed.`}</XDSMarkdown>
+ </XDSChatMessage>
+ <XDSChatMessage sender="user" name="Cindy">
+ <XDSChatMessageBubble>
+ Nice, what about system messages?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatSystemMessage>Cindy liked a message</XDSChatSystemMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const Maximal: StoryObj = {
+ name: 'Maximal',
+ render: () => (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatSystemMessage variant="divider">
+ March 15, 2026
+ </XDSChatSystemMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble>
+ <XDSMarkdown density="compact">{`Good afternoon! I've been looking at the **NDS gap analysis** and have the priority list ready.`}</XDSMarkdown>
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
+ }
+ />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="user"
+ name="Cindy"
+ avatar={<XDSAvatar name="Cindy" size="small" />}>
+ <XDSChatMessageBubble>Great, what's at the top?</XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
+ status="read"
+ />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble>
+ <XDSMarkdown density="compact">{`Chat components — **1,847 usages** across 42 apps.
+
+1. \`ChatBubble\` — 1,847 usages
+2. \`ChatTypingIndicator\` — 463 usages
+3. \`TextShimmer\` — 706 usages`}</XDSMarkdown>
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:30" format="time" />
+ }
+ />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="user"
+ name="Cindy"
+ avatar={<XDSAvatar name="Cindy" size="small" />}>
+ <XDSChatMessageBubble>
+ Let's start on that today.
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:32:00" format="time" />
+ }
+ status="read"
+ />
+ </XDSChatMessage>
+ <XDSChatSystemMessage>Conversation ended</XDSChatSystemMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const MixedContent: StoryObj = {
+ name: 'Mixed Content',
+ render: () => (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>
+ Show me the component files
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSMarkdown density="compact">
+ Here are the files you asked about:
+ </XDSMarkdown>
+ <XDSHStack gap={2} wrap="wrap">
+ <XDSToken label="Button.tsx" />
+ <XDSToken label="Card.tsx" />
+ <XDSToken label="Dialog.tsx" />
+ </XDSHStack>
+ <XDSMarkdown density="compact">
+ And here's the entry point:
+ </XDSMarkdown>
+ <XDSCodeBlock
+ code={
+ "export * from './Button';\nexport * from './Card';\nexport * from './Dialog';"
+ }
+ language="typescript"
+ />
+ <XDSMarkdown density="compact">
+ Let me know which one to open.
+ </XDSMarkdown>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const DensityComparison: StoryObj = {
+ name: 'Density Comparison',
+ render: () => {
+ const avatarSize = {
+ compact: 'xsmall' as const,
+ balanced: 'small' as const,
+ spacious: 'small' as const,
+ };
+ const messages = (density: 'compact' | 'balanced' | 'spacious') => (
+ <div
+ style={{
+ flex: 1,
+ display: 'flex',
+ flexDirection: 'column',
+ minWidth: 0,
+ border: '1px solid var(--color-border-primary)',
+ borderRadius: 8,
+ }}>
+ <div
+ style={{
+ padding: '8px 12px',
+ borderBottom: '1px solid var(--color-border-primary)',
+ fontSize: 12,
+ fontWeight: 600,
+ textTransform: 'uppercase',
+ letterSpacing: '0.05em',
+ }}>
+ {density}
+ </div>
+ <div
+ style={{
+ flex: 1,
+ display: 'flex',
+ flexDirection: 'column',
+ minHeight: 0,
+ }}>
+ <XDSChatMessageList density={density}>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>
+ How does the density system work?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Navi" size={avatarSize[density]} />}>
+ <XDSChatMessageBubble>
+ <XDSMarkdown density="compact">{`Density controls **spacing** at every level:
+
+- **Gap** between messages
+- **Padding** inside bubbles
+- **Gap** between child elements
+
+This is the **${density}** density. ${density === 'compact' ? 'Great for sidebars and panels where space is limited.' : density === 'spacious' ? 'Ideal for long-form reading where breathing room helps comprehension.' : 'The default — works well for most full-page chat interfaces.'}`}</XDSMarkdown>
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>Makes sense, thanks!</XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ </div>
+ );
+
+ return (
+ <div style={{display: 'flex', gap: 16, height: 500}}>
+ {messages('compact')}
+ {messages('balanced')}
+ {messages('spacious')}
+ </div>
+ );
+ },
+};
+
+export const SystemMessages: StoryObj = {
+ name: 'System Messages',
+ render: () => (
+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatSystemMessage variant="divider">
+ March 15, 2026
+ </XDSChatSystemMessage>
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble>Good morning!</XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatSystemMessage>Conversation started</XDSChatSystemMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>Hey Navi</XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
+ <XDSChatSystemMessage>Cindy shared a file</XDSChatSystemMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const AutoScroll: StoryObj = {
+ name: 'Auto Scroll',
+ render: () => {
+ const [messages, setMessages] = useState([
+ {id: 1, sender: 'user' as const, text: 'Tell me a story'},
+ {id: 2, sender: 'assistant' as const, text: 'Once upon a time...'},
+ ]);
+
+ const addMessage = useCallback(() => {
+ setMessages(prev => {
+ const isUser = prev[prev.length - 1]?.sender === 'assistant';
+ const id = prev.length + 1;
+ return [
+ ...prev,
+ {
+ id,
+ sender: isUser ? ('user' as const) : ('assistant' as const),
+ text: isUser
+ ? `Message #${id} from user`
+ : `This is a response to message #${id - 1}. The auto-scroll keeps the view pinned to the bottom as new messages arrive.`,
+ },
+ ];
+ });
+ }, []);
+
+ useEffect(() => {
+ const interval = setInterval(addMessage, 2000);
+ return () => clearInterval(interval);
+ }, [addMessage]);
+
+ return (
+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ {messages.map(msg =>
+ msg.sender === 'user' ? (
+ <XDSChatMessage key={msg.id} sender="user">
+ <XDSChatMessageBubble>{msg.text}</XDSChatMessageBubble>
+ </XDSChatMessage>
+ ) : (
+ <XDSChatMessage key={msg.id} sender="assistant">
+ <XDSChatMessageBubble>{msg.text}</XDSChatMessageBubble>
+ </XDSChatMessage>
+ ),
+ )}
+ </XDSChatMessageList>
+ </div>
+ );
+ },
+};
+
+export const EmptyState: StoryObj = {
+ name: 'Empty State',
+ render: () => (
+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList
+ emptyState={
+ <div style={{textAlign: 'center', opacity: 0.5}}>
+ <div style={{fontSize: 32, marginBottom: 8}}>💬</div>
+ <div>No messages yet. Start a conversation!</div>
+ </div>
+ }>
+ {[]}
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const MessageStatus: StoryObj = {
+ name: 'Message Status',
+ render: () => (
+ <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>Sending...</XDSChatMessageBubble>
+ <XDSChatMessageMetadata status="sending" />
+ </XDSChatMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>Sent</XDSChatMessageBubble>
+ <XDSChatMessageMetadata status="sent" />
+ </XDSChatMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>Delivered</XDSChatMessageBubble>
+ <XDSChatMessageMetadata status="delivered" />
+ </XDSChatMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>Read</XDSChatMessageBubble>
+ <XDSChatMessageMetadata status="read" />
+ </XDSChatMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>Failed to send</XDSChatMessageBubble>
+ <XDSChatMessageMetadata status="error" />
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const MultiBubble: StoryObj = {
+ name: 'Multi-Bubble Grouping',
+ render: () => (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble group="first">
+ Hey, can you review my PR?
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble group="middle">
+ It's the one for the chat components
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble group="last">
+ Link: github.com/xds/pull/1180
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
+ status="delivered"
+ />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble group="first">
+ Sure, looking at it now!
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble group="middle">
+ The compound pattern looks solid. A few minor comments on the
+ density styles.
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble group="last">
+ I'll leave them as review comments.
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:33:00" format="time" />
+ }
+ />
+ </XDSChatMessage>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>
+ Thanks, will address those
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:34:00" format="time" />
+ }
+ status="sending"
+ />
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const AssistantNoBubble: StoryObj = {
+ name: 'Assistant Without Bubble',
+ render: () => (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user" name="Cindy">
+ <XDSChatMessageBubble>
+ Explain the component architecture
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata status="read" />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSMarkdown density="compact">{`The architecture uses a **compound component** pattern:
+
+- **MessageList** — scrollable container with auto-scroll
+- **Message** — layout wrapper with sender context
+- **MessageBubble** — styled content container
+
+Each level provides context to its children via React context.`}</XDSMarkdown>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:35:00" format="time" />
+ }
+ />
+ </XDSChatMessage>
+ <XDSChatMessage sender="user" name="Cindy">
+ <XDSChatMessageBubble>
+ Makes sense. What about the density system?
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:36:00" format="time" />
+ }
+ status="delivered"
+ />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSMarkdown density="compact">{`Density flows from **MessageList → Message → Bubble** via context:
+
+1. \`compact\` — tight spacing, sidebar use
+2. \`balanced\` — default, full-page chat
+3. \`spacious\` — extra room, long-form reading`}</XDSMarkdown>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:36:30" format="time" />
+ }
+ />
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
+
+export const MessageFooter: StoryObj = {
+ name: 'Message Footer',
+ render: () => (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user" name="Cindy">
+ <XDSChatMessageBubble>
+ What's the best way to handle state?
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata status="read" />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSMarkdown density="compact">{`For most cases, **React's built-in state** is sufficient:
+
+- \`useState\` for local component state
+- \`useReducer\` for complex state logic
+- \`useContext\` for shared state across a subtree
+
+For server state, use a library like **TanStack Query** or **SWR**.`}</XDSMarkdown>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:35:00" format="time" />
+ }
+ footer={
+ <>
+ <span>Claude Opus 4.6</span>
+ <span>·</span>
+ <XDSButton
+ label="Thumbs up"
+ icon={<HandThumbUpIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Thumbs down"
+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ />
+ </>
+ }
+ />
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ name="Navi"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble>
+ Avoid global state managers unless you have a genuine need for
+ cross-cutting state. Most apps are over-engineered in this area.
+ </XDSChatMessageBubble>
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:36:00" format="time" />
+ }
+ footer={
+ <>
+ <span>Claude Opus 4.6</span>
+ <span>·</span>
+ <XDSButton
+ label="Thumbs up"
+ icon={<HandThumbUpIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Thumbs down"
+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ />
+ <XDSButton
+ label="Copy"
+ icon={
+ <ClipboardDocumentIcon style={{width: 14, height: 14}} />
+ }
+ variant="ghost"
+ size="sm"
+ />
+ </>
+ }
+ />
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
new file mode 100644
index 0000000000..ab1d6833fa
--- /dev/null
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -0,0 +1,96 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Chat',
+ description:
+ 'Chat layout components for AI chat interfaces. Composition model: XDSChatMessageList wraps XDSChatMessage and XDSChatSystemMessage. Messages contain optional XDSChatMessageBubble for styled content.',
+ keywords: ['chat', 'message', 'bubble', 'conversation', 'ai', 'assistant', 'thread', 'system-message'],
+ features: [
+ 'Composition model — MessageList > Message > Bubble',
+ 'Sender-aware styling (user, assistant, system) via context',
+ 'Auto-scroll with "New messages" indicator',
+ 'Infinite scroll via onScrollToTopAction with useTransition',
+ 'Density variants: compact, balanced, spacious (flows via context)',
+ 'System messages with optional divider variant for date separators',
+ 'Free-form children — not all content needs a bubble',
+ 'Timestamp display: hover or header',
+ 'Message status indicators (sending, sent, delivered, read, error)',
+ 'role="log" with aria-live="polite" for accessibility',
+ ],
+ examples: [
+ {
+ label: 'Basic conversation',
+ code: `<XDSChatMessageList>
+ <XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="sm" />}>
+ <XDSChatMessageBubble>Hello! How can I help?</XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage sender="user" name="Cindy">
+ <XDSChatMessageBubble>What's the status?</XDSChatMessageBubble>
+ </XDSChatMessage>
+</XDSChatMessageList>`,
+ },
+ {
+ label: 'System message with divider',
+ code: `<XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>`,
+ },
+ ],
+ components: [
+ {
+ name: 'XDSChatMessageList',
+ description: 'Scrollable message container with auto-scroll and infinite scroll support.',
+ props: [
+ {name: 'children', type: 'ReactNode', description: 'Message elements — typically XDSChatMessage or XDSChatSystemMessage.', required: true},
+ {name: 'hasAutoScroll', type: 'boolean', description: 'Enables auto-scroll to bottom on new content when near the bottom.', default: 'true'},
+ {name: 'scrollThreshold', type: 'number', description: 'Distance from bottom (px) within which new content triggers auto-scroll.', default: '50'},
+ {name: 'emptyState', type: 'ReactNode', description: 'Content shown when the list has no messages.'},
+ {name: 'onScrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages.'},
+ {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density — flows to child messages via context.', default: "'balanced'"},
+ ],
+ examples: [
+ {label: 'With infinite scroll', code: `<XDSChatMessageList onScrollToTopAction={loadOlder}>{messages.map(renderMessage)}</XDSChatMessageList>`},
+ ],
+ },
+ {
+ name: 'XDSChatMessage',
+ description: 'Sender context wrapper — handles avatar, name, and alignment based on sender role.',
+ props: [
+ {name: 'sender', type: "'user' | 'assistant' | 'system'", description: 'Who sent this message — controls alignment and layout.', required: true},
+ {name: 'children', type: 'ReactNode', description: 'Free-form content: bubbles, asset lists, tool calls, images.', required: true},
+ {name: 'avatar', type: 'ReactNode', description: 'Avatar element rendered beside the message. Typically XDSAvatar.'},
+ {name: 'name', type: 'string', description: 'Sender name displayed above the content.'},
+ {name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density. Inherited from list context if not set.'},
+ ],
+ examples: [
+ {label: 'Assistant message', code: `<XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="sm" />}>\n <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>\n</XDSChatMessage>`},
+ ],
+ },
+ {
+ name: 'XDSChatMessageBubble',
+ description: 'Styled bubble container — reads sender from parent context for auto-styling. Opt-in per content.',
+ props: [
+ {name: 'children', type: 'ReactNode', description: 'Bubble content — text, XDSMarkdown, or any ReactNode.', required: true},
+ {name: 'timestamp', type: 'Date | string', description: 'Timestamp for the bubble. Date is auto-formatted.'},
+ {name: 'timestampDisplay', type: "'header' | 'hover'", description: 'How the timestamp is shown.', default: "'hover'"},
+ {name: 'footer', type: 'ReactNode', description: 'Footer below the bubble for reactions, actions, read receipts.'},
+ {name: 'status', type: "'sending' | 'sent' | 'delivered' | 'read' | 'error'", description: 'Message status indicator. Only rendered for user messages.'},
+ ],
+ examples: [
+ {label: 'With timestamp', code: `<XDSChatMessageBubble timestamp="2:30 PM" timestampDisplay="header">Hello!</XDSChatMessageBubble>`},
+ ],
+ },
+ {
+ name: 'XDSChatSystemMessage',
+ description: 'Centered system/notice message for date separators, status updates, and non-sender content.',
+ props: [
+ {name: 'children', type: 'ReactNode', description: 'System message content.', required: true},
+ {name: 'variant', type: "'default' | 'divider'", description: 'Visual variant. Divider adds horizontal lines on each side.', default: "'default'"},
+ {name: 'icon', type: 'ReactNode', description: 'Icon rendered before the text.'},
+ {name: 'timestamp', type: 'Date | string', description: 'Timestamp displayed after the text.'},
+ ],
+ examples: [
+ {label: 'Date divider', code: `<XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>`},
+ {label: 'Status notice', code: `<XDSChatSystemMessage>Cindy shared a file</XDSChatSystemMessage>`},
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/Chat/README.md b/packages/core/src/Chat/README.md
new file mode 100644
index 0000000000..e7bed7aa1e
--- /dev/null
+++ b/packages/core/src/Chat/README.md
@@ -0,0 +1,31 @@
+# Chat
+
+Chat layout components for AI chat interfaces.
+
+## Files
+
+| File | Purpose |
+| -------------------------- | ----------------------------------------------------------------- |
+| `XDSChatMessageList.tsx` | Scrollable message container with auto-scroll and infinite scroll |
+| `XDSChatMessage.tsx` | Sender context wrapper — avatar, name, alignment by role |
+| `XDSChatMessageBubble.tsx` | Styled bubble container — reads sender from context |
+| `XDSChatSystemMessage.tsx` | Centered system/notice messages with optional divider |
+| `XDSChatContext.tsx` | Internal React contexts for sender and density propagation |
+| `index.ts` | Public exports |
+
+## Architecture
+
+```
+XDSChatMessageList — scrollable container, auto-scroll
+ XDSChatSystemMessage — date separators, status notices
+ XDSChatMessage — sender context (avatar, name, alignment)
+ XDSChatMessageBubble — styled bubble (optional per content)
+ (any other content) — asset lists, tool calls, images
+```
+
+## Context Flow
+
+- `XDSChatListContext` — density from list to messages
+- `XDSChatMessageContext` — sender + density from message to bubbles
+
+Both contexts are internal (not exported). Only types are public.
diff --git a/packages/core/src/Chat/XDSChatContext.tsx b/packages/core/src/Chat/XDSChatContext.tsx
new file mode 100644
index 0000000000..4c28c4139c
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatContext.tsx
@@ -0,0 +1,37 @@
+'use client';
+
+/**
+ * @file XDSChatContext.tsx
+ * @input Uses React createContext
+ * @output Exports XDSChatMessageContext for sharing sender/density between Chat components
+ * @position Internal context; consumed by XDSChatMessage and XDSChatMessageBubble
+ */
+
+import {createContext, useContext} from 'react';
+
+export type XDSChatMessageSender = 'user' | 'assistant' | 'system';
+export type XDSChatDensity = 'compact' | 'balanced' | 'spacious';
+
+export interface XDSChatMessageContextValue {
+ sender: XDSChatMessageSender;
+ density: XDSChatDensity;
+}
+
+export const XDSChatMessageContext =
+ createContext<XDSChatMessageContextValue | null>(null);
+
+export function useXDSChatMessageContext(): XDSChatMessageContextValue | null {
+ return useContext(XDSChatMessageContext);
+}
+
+export interface XDSChatListContextValue {
+ density: XDSChatDensity;
+}
+
+export const XDSChatListContext = createContext<XDSChatListContextValue | null>(
+ null,
+);
+
+export function useXDSChatListContext(): XDSChatListContextValue | null {
+ return useContext(XDSChatListContext);
+}
diff --git a/packages/core/src/Chat/XDSChatMessage.test.tsx b/packages/core/src/Chat/XDSChatMessage.test.tsx
new file mode 100644
index 0000000000..9aba343c9d
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatMessage.test.tsx
@@ -0,0 +1,94 @@
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSChatMessage} from './XDSChatMessage';
+import {XDSChatMessageBubble} from './XDSChatMessageBubble';
+
+describe('XDSChatMessage', () => {
+ it('renders children', () => {
+ render(
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble>Hello world</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ expect(screen.getByText('Hello world')).toBeTruthy();
+ });
+
+ it('renders sender name', () => {
+ render(
+ <XDSChatMessage sender="assistant" name="Navi">
+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ expect(screen.getByText('Navi')).toBeTruthy();
+ });
+
+ it('hides name for system sender', () => {
+ render(
+ <XDSChatMessage sender="system" name="System">
+ <span>Notice</span>
+ </XDSChatMessage>,
+ );
+ expect(screen.queryByText('System')).toBeNull();
+ });
+
+ it('renders avatar for assistant', () => {
+ render(
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<div data-testid="avatar">A</div>}>
+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ expect(screen.getByTestId('avatar')).toBeTruthy();
+ });
+
+ it('hides avatar for system', () => {
+ render(
+ <XDSChatMessage
+ sender="system"
+ avatar={<div data-testid="avatar">S</div>}>
+ <span>Notice</span>
+ </XDSChatMessage>,
+ );
+ expect(screen.queryByTestId('avatar')).toBeNull();
+ });
+
+ it('applies sender class', () => {
+ render(
+ <XDSChatMessage sender="user" data-testid="msg">
+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ const el = screen.getByTestId('msg');
+ expect(el.className).toContain('user');
+ });
+
+ it('sets accessible aria-label with name', () => {
+ render(
+ <XDSChatMessage sender="assistant" name="Navi" data-testid="msg">
+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ const el = screen.getByTestId('msg');
+ expect(el.getAttribute('aria-label')).toBe('Message from Navi');
+ });
+
+ it('sets accessible aria-label without name', () => {
+ render(
+ <XDSChatMessage sender="user" data-testid="msg">
+ <XDSChatMessageBubble>Hi</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ const el = screen.getByTestId('msg');
+ expect(el.getAttribute('aria-label')).toBe('Message from user');
+ });
+
+ it('renders non-bubble children', () => {
+ render(
+ <XDSChatMessage sender="assistant">
+ <div data-testid="custom-content">Custom widget</div>
+ </XDSChatMessage>,
+ );
+ expect(screen.getByTestId('custom-content')).toBeTruthy();
+ });
+});
diff --git a/packages/core/src/Chat/XDSChatMessage.tsx b/packages/core/src/Chat/XDSChatMessage.tsx
new file mode 100644
index 0000000000..c1884c00e4
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatMessage.tsx
@@ -0,0 +1,235 @@
+'use client';
+
+/**
+ * @file XDSChatMessage.tsx
+ * @input Uses React, StyleX, XDSChatContext, theme tokens
+ * @output Exports XDSChatMessage component and XDSChatMessageProps
+ * @position Sender context wrapper — handles avatar, name, alignment by sender role
+ *
+ * Layout (with avatar):
+ * [Avatar] [Name ]
+ * [Content/Bubbles ]
+ * [Metadata ]
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Chat/index.ts (exports)
+ * - /apps/storybook/stories/Chat.stories.tsx
+ */
+
+import {type ReactNode, useMemo} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ typeScaleVars,
+ fontWeightVars,
+} from '../theme/tokens.stylex';
+import {
+ XDSChatMessageContext,
+ useXDSChatListContext,
+ type XDSChatMessageSender,
+ type XDSChatDensity,
+} from './XDSChatContext';
+import {xdsClassName, mergeProps} from '../utils';
+
+export interface XDSChatMessageProps {
+ ref?: React.Ref<HTMLDivElement>;
+ sender: XDSChatMessageSender;
+ children: ReactNode;
+ avatar?: ReactNode;
+ name?: string;
+ density?: XDSChatDensity;
+ xstyle?: StyleXStyles;
+ className?: string;
+ style?: React.CSSProperties;
+ 'data-testid'?: string;
+}
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ alignItems: 'flex-start',
+ maxWidth: '100%',
+ },
+ rootGapCompact: {
+ gap: spacingVars['--spacing-2'],
+ },
+ rootGapBalanced: {
+ gap: spacingVars['--spacing-3'],
+ },
+ rootGapSpacious: {
+ gap: spacingVars['--spacing-3'],
+ },
+ rootAssistant: {
+ flexDirection: 'row',
+ justifyContent: 'flex-start',
+ },
+ rootUser: {
+ flexDirection: 'row-reverse',
+ justifyContent: 'flex-start',
+ },
+ rootSystem: {
+ flexDirection: 'row',
+ justifyContent: 'center',
+ },
+ avatarWrap: {
+ flexShrink: 0,
+ },
+ contentColumn: {
+ display: 'flex',
+ flexDirection: 'column',
+ minWidth: 0,
+ maxWidth: '80%',
+ },
+ contentColumnSystem: {
+ maxWidth: '90%',
+ alignItems: 'center',
+ },
+ contentColumnAssistant: {
+ alignItems: 'flex-start',
+ },
+ contentColumnUser: {
+ alignItems: 'flex-end',
+ },
+ name: {
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ color: colorVars['--color-text-secondary'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ marginBlockEnd: spacingVars['--spacing-1'],
+ },
+ childrenWrap: {
+ display: 'flex',
+ flexDirection: 'column',
+ minWidth: 0,
+ width: '100%',
+ },
+ childrenAssistant: {
+ alignItems: 'flex-start',
+ },
+ childrenUser: {
+ alignItems: 'flex-end',
+ },
+ childrenSystem: {
+ alignItems: 'center',
+ },
+ childrenGapCompact: {
+ gap: spacingVars['--spacing-0-5'],
+ },
+ childrenGapBalanced: {
+ gap: spacingVars['--spacing-1'],
+ },
+ childrenGapSpacious: {
+ gap: spacingVars['--spacing-1-5'],
+ },
+});
+
+/**
+ * Sender context wrapper for chat messages.
+ *
+ * Provides sender and density context to child components.
+ * Use XDSChatMessageMetadata as a child for timestamp, status, and footer.
+ *
+ * @example
+ * ```
+ * <XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="small" />}>
+ * <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>
+ * <XDSChatMessageMetadata timestamp="2:30 PM" />
+ * </XDSChatMessage>
+ * ```
+ */
+export function XDSChatMessage({
+ sender,
+ children,
+ avatar,
+ name,
+ density: densityProp,
+ xstyle,
+ className,
+ style: styleProp,
+ 'data-testid': testId,
+ ref,
+}: XDSChatMessageProps) {
+ const listContext = useXDSChatListContext();
+ const density = densityProp ?? listContext?.density ?? 'balanced';
+
+ const contextValue = useMemo(() => ({sender, density}), [sender, density]);
+
+ const rootGap =
+ density === 'compact'
+ ? styles.rootGapCompact
+ : density === 'spacious'
+ ? styles.rootGapSpacious
+ : styles.rootGapBalanced;
+
+ const childrenGap =
+ density === 'compact'
+ ? styles.childrenGapCompact
+ : density === 'spacious'
+ ? styles.childrenGapSpacious
+ : styles.childrenGapBalanced;
+
+ const rootAlignment =
+ sender === 'system'
+ ? styles.rootSystem
+ : sender === 'user'
+ ? styles.rootUser
+ : styles.rootAssistant;
+
+ const columnAlignment =
+ sender === 'system'
+ ? styles.contentColumnSystem
+ : sender === 'user'
+ ? styles.contentColumnUser
+ : styles.contentColumnAssistant;
+
+ const childrenAlignment =
+ sender === 'system'
+ ? styles.childrenSystem
+ : sender === 'user'
+ ? styles.childrenUser
+ : styles.childrenAssistant;
+
+ const isSystem = sender === 'system';
+ const hasAvatar = avatar != null && !isSystem;
+
+ return (
+ <XDSChatMessageContext.Provider value={contextValue}>
+ <article
+ ref={ref}
+ data-testid={testId}
+ aria-label={name ? `Message from ${name}` : `Message from ${sender}`}
+ {...mergeProps(
+ xdsClassName('chat-message', {sender}),
+ stylex.props(
+ styles.root,
+ rootAlignment,
+ hasAvatar && rootGap,
+ xstyle,
+ ),
+ className,
+ styleProp,
+ )}>
+ {hasAvatar && <div {...stylex.props(styles.avatarWrap)}>{avatar}</div>}
+
+ <div {...stylex.props(styles.contentColumn, columnAlignment)}>
+ {name != null && !isSystem && (
+ <span {...stylex.props(styles.name)}>{name}</span>
+ )}
+
+ <div
+ {...stylex.props(
+ styles.childrenWrap,
+ childrenAlignment,
+ childrenGap,
+ )}>
+ {children}
+ </div>
+ </div>
+ </article>
+ </XDSChatMessageContext.Provider>
+ );
+}
+
+XDSChatMessage.displayName = 'XDSChatMessage';
diff --git a/packages/core/src/Chat/XDSChatMessageBubble.test.tsx b/packages/core/src/Chat/XDSChatMessageBubble.test.tsx
new file mode 100644
index 0000000000..34e57a22f3
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatMessageBubble.test.tsx
@@ -0,0 +1,95 @@
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSChatMessage} from './XDSChatMessage';
+import {XDSChatMessageBubble} from './XDSChatMessageBubble';
+import {XDSChatMessageMetadata} from './XDSChatMessageMetadata';
+
+describe('XDSChatMessageBubble', () => {
+ it('renders children', () => {
+ render(
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble>Hello world</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ expect(screen.getByText('Hello world')).toBeTruthy();
+ });
+
+ it('applies sender-aware class from context', () => {
+ render(
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble data-testid="bubble">Hi</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ const el = screen.getByTestId('bubble');
+ expect(el.className).toContain('user');
+ });
+
+ it('defaults to assistant when no context', () => {
+ render(
+ <XDSChatMessageBubble data-testid="bubble">
+ Standalone
+ </XDSChatMessageBubble>,
+ );
+ const el = screen.getByTestId('bubble');
+ expect(el.className).toContain('assistant');
+ });
+
+ it('applies data-testid', () => {
+ render(
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble data-testid="my-bubble">Hi</XDSChatMessageBubble>
+ </XDSChatMessage>,
+ );
+ expect(screen.getByTestId('my-bubble')).toBeTruthy();
+ });
+});
+
+describe('XDSChatMessageMetadata', () => {
+ it('renders timestamp', () => {
+ render(
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageMetadata timestamp="2:30 PM" />
+ </XDSChatMessage>,
+ );
+ expect(screen.getByText('2:30 PM')).toBeTruthy();
+ });
+
+ it('renders footer content', () => {
+ render(
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageMetadata footer={<span>Liked</span>} />
+ </XDSChatMessage>,
+ );
+ expect(screen.getByText('Liked')).toBeTruthy();
+ });
+
+ it('renders status', () => {
+ render(
+ <XDSChatMessage sender="user">
+ <XDSChatMessageMetadata status="sent" />
+ </XDSChatMessage>,
+ );
+ expect(screen.getByLabelText('Message sent')).toBeTruthy();
+ });
+
+ it('renders timestamp and status on one row', () => {
+ render(
+ <XDSChatMessage sender="user">
+ <XDSChatMessageMetadata timestamp="2:30 PM" status="read" />
+ </XDSChatMessage>,
+ );
+ expect(screen.getByText('2:30 PM')).toBeTruthy();
+ expect(screen.getByLabelText('Message read')).toBeTruthy();
+ expect(screen.getByText('·')).toBeTruthy();
+ });
+
+ it('renders nothing when all props are empty', () => {
+ const {container} = render(
+ <XDSChatMessage sender="user">
+ <XDSChatMessageMetadata />
+ </XDSChatMessage>,
+ );
+ // Only the article wrapper from XDSChatMessage
+ expect(container.querySelectorAll('article').length).toBe(1);
+ });
+});
diff --git a/packages/core/src/Chat/XDSChatMessageBubble.tsx b/packages/core/src/Chat/XDSChatMessageBubble.tsx
new file mode 100644
index 0000000000..c782ff1d5a
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatMessageBubble.tsx
@@ -0,0 +1,225 @@
+'use client';
+
+/**
+ * @file XDSChatMessageBubble.tsx
+ * @input Uses React, StyleX, XDSChatMessageContext, theme tokens
+ * @output Exports XDSChatMessageBubble component and XDSChatMessageBubbleProps
+ * @position Styled content container — the actual "chat bubble" with sender-aware styling
+ *
+ * Reads sender from parent XDSChatMessage context to auto-style background.
+ * Optional — not all message content needs bubble treatment.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Chat/index.ts (exports)
+ * - /apps/storybook/stories/Chat.stories.tsx
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ typeScaleVars,
+ typographyVars,
+} from '../theme/tokens.stylex';
+import {useXDSChatMessageContext} from './XDSChatContext';
+import {xdsClassName, mergeProps} from '../utils';
+
+export type XDSChatMessageBubbleVariant = 'filled' | 'transparent';
+
+export interface XDSChatMessageBubbleProps {
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+
+ /**
+ * Bubble content — text, XDSMarkdown, or any ReactNode.
+ */
+ children: ReactNode;
+
+ /**
+ * Visual variant.
+ * - 'filled': background color based on sender (default)
+ * - 'transparent': no background, no padding — just the content
+ * @default 'filled'
+ */
+ variant?: XDSChatMessageBubbleVariant;
+
+ /**
+ * Position within a multi-bubble group.
+ * Controls corner radius reduction on the sender side.
+ * - 'first': bottom sender-side corner tightened
+ * - 'middle': both sender-side corners tightened
+ * - 'last': top sender-side corner tightened
+ * Leave unset for standalone bubbles (full radius).
+ */
+ group?: 'first' | 'middle' | 'last';
+
+ /** StyleX overrides. */
+ xstyle?: StyleXStyles;
+ /** CSS class name(s). */
+ className?: string;
+ /** Inline styles. */
+ style?: React.CSSProperties;
+ /** Test ID. */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ maxWidth: '100%',
+ borderRadius: radiusVars['--radius-container'],
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-body-size'],
+ lineHeight: typeScaleVars['--text-body-leading'],
+ overflowWrap: 'break-word',
+ wordBreak: 'break-word',
+ },
+ paddingCompact: {
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ },
+ paddingBalanced: {
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-4'],
+ },
+ paddingSpacious: {
+ paddingBlock: spacingVars['--spacing-4'],
+ paddingInline: spacingVars['--spacing-5'],
+ },
+ paddingNone: {
+ paddingBlock: 0,
+ paddingInline: 0,
+ },
+ assistant: {
+ backgroundColor: colorVars['--color-background-muted'],
+ color: colorVars['--color-text-primary'],
+ },
+ user: {
+ backgroundColor: colorVars['--color-background-muted'],
+ color: colorVars['--color-text-primary'],
+ },
+ system: {
+ backgroundColor: 'transparent',
+ color: colorVars['--color-text-secondary'],
+ },
+ transparent: {
+ backgroundColor: 'transparent',
+ color: colorVars['--color-text-primary'],
+ },
+ // Grouped bubble corners — assistant (left side tight)
+ groupFirstAssistant: {
+ borderBottomLeftRadius: radiusVars['--radius-inner'],
+ },
+ groupMiddleAssistant: {
+ borderTopLeftRadius: radiusVars['--radius-inner'],
+ borderBottomLeftRadius: radiusVars['--radius-inner'],
+ },
+ groupLastAssistant: {
+ borderTopLeftRadius: radiusVars['--radius-inner'],
+ },
+ // Grouped bubble corners — user (right side tight)
+ groupFirstUser: {
+ borderBottomRightRadius: radiusVars['--radius-inner'],
+ },
+ groupMiddleUser: {
+ borderTopRightRadius: radiusVars['--radius-inner'],
+ borderBottomRightRadius: radiusVars['--radius-inner'],
+ },
+ groupLastUser: {
+ borderTopRightRadius: radiusVars['--radius-inner'],
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Styled content container — the chat "bubble."
+ *
+ * Reads sender from parent XDSChatMessage context to auto-style background.
+ * Use `group` prop for multi-bubble corner grouping.
+ *
+ * @example
+ * ```
+ * <XDSChatMessage sender="user">
+ * <XDSChatMessageBubble group="first">Hey</XDSChatMessageBubble>
+ * <XDSChatMessageBubble group="last">What's up?</XDSChatMessageBubble>
+ * <XDSChatMessageMetadata timestamp="2:30 PM" status="read" />
+ * </XDSChatMessage>
+ * ```
+ */
+export function XDSChatMessageBubble({
+ children,
+ variant = 'filled',
+ group,
+ xstyle,
+ className,
+ style: styleProp,
+ 'data-testid': testId,
+ ref,
+}: XDSChatMessageBubbleProps) {
+ const msgContext = useXDSChatMessageContext();
+ const sender = msgContext?.sender ?? 'assistant';
+ const density = msgContext?.density ?? 'balanced';
+
+ const paddingStyle =
+ variant === 'transparent'
+ ? styles.paddingNone
+ : density === 'compact'
+ ? styles.paddingCompact
+ : density === 'spacious'
+ ? styles.paddingSpacious
+ : styles.paddingBalanced;
+
+ const senderStyle =
+ variant === 'transparent'
+ ? styles.transparent
+ : (styles[sender] ?? styles.assistant);
+
+ const isUser = sender === 'user';
+ const groupStyle =
+ group === 'first'
+ ? isUser
+ ? styles.groupFirstUser
+ : styles.groupFirstAssistant
+ : group === 'middle'
+ ? isUser
+ ? styles.groupMiddleUser
+ : styles.groupMiddleAssistant
+ : group === 'last'
+ ? isUser
+ ? styles.groupLastUser
+ : styles.groupLastAssistant
+ : null;
+
+ return (
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('chat-message-bubble', {sender, variant}),
+ stylex.props(
+ styles.root,
+ senderStyle,
+ paddingStyle,
+ groupStyle,
+ xstyle,
+ ),
+ className,
+ styleProp,
+ )}>
+ {children}
+ </div>
+ );
+}
+
+XDSChatMessageBubble.displayName = 'XDSChatMessageBubble';
diff --git a/packages/core/src/Chat/XDSChatMessageList.test.tsx b/packages/core/src/Chat/XDSChatMessageList.test.tsx
new file mode 100644
index 0000000000..8d3b96ab8b
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatMessageList.test.tsx
@@ -0,0 +1,66 @@
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSChatMessageList} from './XDSChatMessageList';
+import {XDSChatMessage} from './XDSChatMessage';
+import {XDSChatMessageBubble} from './XDSChatMessageBubble';
+
+describe('XDSChatMessageList', () => {
+ it('renders children', () => {
+ render(
+ <XDSChatMessageList>
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble>Hello</XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>,
+ );
+ expect(screen.getByText('Hello')).toBeTruthy();
+ });
+
+ it('renders with role="log"', () => {
+ render(
+ <XDSChatMessageList data-testid="list">
+ <div>msg</div>
+ </XDSChatMessageList>,
+ );
+ const el = screen.getByTestId('list');
+ expect(el.getAttribute('role')).toBe('log');
+ });
+
+ it('renders empty state when no children', () => {
+ render(
+ <XDSChatMessageList emptyState={<div>No messages yet</div>}>
+ {[]}
+ </XDSChatMessageList>,
+ );
+ expect(screen.getByText('No messages yet')).toBeTruthy();
+ });
+
+ it('applies density class', () => {
+ render(
+ <XDSChatMessageList density="compact" data-testid="list">
+ <div>msg</div>
+ </XDSChatMessageList>,
+ );
+ const el = screen.getByTestId('list');
+ expect(el.className).toContain('compact');
+ });
+
+ it('applies data-testid', () => {
+ render(
+ <XDSChatMessageList data-testid="chat-list">
+ <div>msg</div>
+ </XDSChatMessageList>,
+ );
+ expect(screen.getByTestId('chat-list')).toBeTruthy();
+ });
+
+ it('has new messages button (hidden by default)', () => {
+ render(
+ <XDSChatMessageList>
+ <div>msg</div>
+ </XDSChatMessageList>,
+ );
+ const button = screen.getByLabelText(/New messages/);
+ expect(button).toBeTruthy();
+ });
+});
diff --git a/packages/core/src/Chat/XDSChatMessageList.tsx b/packages/core/src/Chat/XDSChatMessageList.tsx
new file mode 100644
index 0000000000..e118584381
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatMessageList.tsx
@@ -0,0 +1,348 @@
+'use client';
+
+/**
+ * @file XDSChatMessageList.tsx
+ * @input Uses React, StyleX, XDSChatListContext, XDSButton, theme tokens
+ * @output Exports XDSChatMessageList component and XDSChatMessageListProps
+ * @position Scrollable message container — holds XDSChatMessage children with auto-scroll
+ *
+ * Renders a scrollable container with role="log" for chat message histories.
+ * Handles auto-scroll (pins to bottom during streaming), a "New messages"
+ * indicator when scrolled up, and onScrollToTopAction for infinite scroll.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Chat/index.ts (exports)
+ * - /apps/storybook/stories/Chat.stories.tsx
+ */
+
+import {
+ type ReactNode,
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useTransition,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ typeScaleVars,
+ fontWeightVars,
+ durationVars,
+ easeVars,
+} from '../theme/tokens.stylex';
+import {XDSChatListContext, type XDSChatDensity} from './XDSChatContext';
+import {xdsClassName, mergeProps} from '../utils';
+import {XDSSpinner} from '../Spinner';
+import {useAutoScroll} from './useAutoScroll';
+
+export interface XDSChatMessageListProps {
+ /** Ref forwarded to the scrollable container element */
+ ref?: React.Ref<HTMLDivElement>;
+
+ /**
+ * Message elements — typically XDSChatMessage components.
+ * Also accepts XDSDivider (date separators) or any ReactNode.
+ */
+ children: ReactNode;
+
+ /**
+ * Whether auto-scroll behavior is enabled.
+ * When true (default), the list scrolls to bottom on new content
+ * if the user is near the bottom. When false, no auto-scrolling
+ * occurs — useful for static/view-only conversation history.
+ * @default true
+ */
+ hasAutoScroll?: boolean;
+
+ /**
+ * Distance from bottom (in px) within which new content triggers auto-scroll.
+ * Only applies when `hasAutoScroll` is true.
+ * @default 12
+ */
+ scrollThreshold?: number;
+
+ /**
+ * Custom content when the list has no messages.
+ */
+ emptyState?: ReactNode;
+
+ /**
+ * Async action when the user scrolls to the top.
+ * Use for loading older messages. Wrapped in useTransition —
+ * shows a spinner at the top while pending.
+ */
+ onScrollToTopAction?: () => Promise<void>;
+
+ /**
+ * Visual density — flows to child messages via context.
+ * Individual messages can override.
+ * @default 'balanced'
+ */
+ density?: XDSChatDensity;
+
+ /**
+ * StyleX overrides.
+ */
+ xstyle?: StyleXStyles;
+ /** CSS class name(s) appended to the root element. */
+ className?: string;
+ /** Inline styles. */
+ style?: React.CSSProperties;
+ /** Test ID. */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ outer: {
+ position: 'relative',
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minHeight: 0,
+ },
+ root: {
+ display: 'flex',
+ flexDirection: 'column',
+ overflowY: 'auto',
+ overflowX: 'hidden',
+ overflowAnchor: 'auto',
+ flex: 1,
+ minHeight: 0,
+ },
+ inner: {
+ display: 'flex',
+ flexDirection: 'column',
+ flex: 1,
+ minHeight: 0,
+ },
+ gapCompact: {
+ gap: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ },
+ gapBalanced: {
+ gap: spacingVars['--spacing-4'],
+ paddingBlock: spacingVars['--spacing-4'],
+ paddingInline: spacingVars['--spacing-4'],
+ },
+ gapSpacious: {
+ gap: spacingVars['--spacing-6'],
+ paddingBlock: spacingVars['--spacing-6'],
+ paddingInline: spacingVars['--spacing-6'],
+ },
+ spacer: {
+ flex: 1,
+ minHeight: 0,
+ },
+ loadingTop: {
+ display: 'flex',
+ justifyContent: 'center',
+ paddingBlock: spacingVars['--spacing-3'],
+ },
+ newMessagesButton: {
+ position: 'absolute',
+ bottom: spacingVars['--spacing-3'],
+ left: '50%',
+ transform: 'translateX(-50%)',
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ paddingBlock: spacingVars['--spacing-1-5'],
+ paddingInline: spacingVars['--spacing-3'],
+ backgroundColor: colorVars['--color-accent'],
+ color: colorVars['--color-on-accent'],
+ border: 'none',
+ borderRadius: radiusVars['--radius-full'],
+ cursor: 'pointer',
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ boxShadow: '0 2px 8px rgba(0,0,0,0.15)',
+ transitionProperty: 'opacity, transform',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ zIndex: 1,
+ },
+ newMessagesHidden: {
+ opacity: 0,
+ pointerEvents: 'none',
+ transform: 'translate(-50%, 8px)',
+ },
+ newMessagesVisible: {
+ opacity: 1,
+ pointerEvents: 'auto',
+ transform: 'translate(-50%, 0)',
+ },
+ emptyState: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ flex: 1,
+ minHeight: 0,
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Scrollable container for chat messages with auto-scroll and infinite scroll support.
+ *
+ * Pins to the bottom when the user is near the end. Shows a "New messages" button
+ * when scrolled up. Supports loading older messages via `onScrollToTopAction`.
+ *
+ * @example
+ * ```
+ * <XDSChatMessageList>
+ * <XDSChatMessage sender="assistant" name="Navi" avatar={<XDSAvatar name="Navi" size="sm" />}>
+ * <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>
+ * </XDSChatMessage>
+ * <XDSChatMessage sender="user" name="Cindy">
+ * <XDSChatMessageBubble>Hey there!</XDSChatMessageBubble>
+ * </XDSChatMessage>
+ * </XDSChatMessageList>
+ * ```
+ */
+export function XDSChatMessageList({
+ children,
+ hasAutoScroll = true,
+ scrollThreshold = 12,
+ emptyState,
+ onScrollToTopAction,
+ density = 'balanced',
+ xstyle,
+ className,
+ style,
+ 'data-testid': testId,
+ ref,
+}: XDSChatMessageListProps) {
+ const {
+ scrollRef,
+ showNewMessages,
+ handleScroll,
+ dismissNewMessages,
+ onContentChange,
+ } = useAutoScroll({enabled: hasAutoScroll, threshold: scrollThreshold});
+
+ const sentinelRef = useRef<HTMLDivElement>(null);
+ const [isLoadingTop, startTransition] = useTransition();
+
+ // Track whether children exist (for empty state)
+ const hasChildren =
+ children != null &&
+ children !== false &&
+ !(Array.isArray(children) && children.length === 0);
+
+ // Auto-scroll on new content (children change)
+ useEffect(() => {
+ onContentChange();
+ }, [children, onContentChange]);
+
+ // IntersectionObserver for scroll-to-top infinite scroll
+ useEffect(() => {
+ if (!onScrollToTopAction || !sentinelRef.current || !scrollRef.current)
+ return;
+
+ const observer = new IntersectionObserver(
+ entries => {
+ if (entries[0]?.isIntersecting) {
+ startTransition(async () => {
+ await onScrollToTopAction();
+ });
+ }
+ },
+ {root: scrollRef.current, threshold: 0},
+ );
+
+ observer.observe(sentinelRef.current);
+ return () => observer.disconnect();
+ }, [onScrollToTopAction, scrollRef]);
+
+ const contextValue = useMemo(() => ({density}), [density]);
+
+ const gapStyle =
+ density === 'compact'
+ ? styles.gapCompact
+ : density === 'spacious'
+ ? styles.gapSpacious
+ : styles.gapBalanced;
+
+ // Merge refs
+ const setRefs = useCallback(
+ (el: HTMLDivElement | null) => {
+ (scrollRef as React.MutableRefObject<HTMLDivElement | null>).current = el;
+ if (typeof ref === 'function') {
+ ref(el);
+ } else if (ref) {
+ (ref as React.MutableRefObject<HTMLDivElement | null>).current = el;
+ }
+ },
+ [ref, scrollRef],
+ );
+
+ return (
+ <XDSChatListContext.Provider value={contextValue}>
+ <div {...stylex.props(styles.outer)}>
+ <div
+ ref={setRefs}
+ role="log"
+ aria-live="polite"
+ tabIndex={0}
+ data-testid={testId}
+ onScroll={handleScroll}
+ {...mergeProps(
+ xdsClassName('chat-message-list', {density}),
+ stylex.props(styles.root, xstyle),
+ className,
+ style,
+ )}>
+ <div {...stylex.props(styles.inner, gapStyle)}>
+ {/* Sentinel for infinite scroll */}
+ {onScrollToTopAction && <div ref={sentinelRef} aria-hidden />}
+
+ {/* Loading spinner at top */}
+ {isLoadingTop && (
+ <div {...stylex.props(styles.loadingTop)}>
+ <XDSSpinner size="sm" />
+ </div>
+ )}
+
+ {/* Spacer pushes messages to bottom when list isn't full */}
+ <div {...stylex.props(styles.spacer)} aria-hidden />
+
+ {/* Messages or empty state */}
+ {hasChildren ? (
+ children
+ ) : emptyState ? (
+ <div {...stylex.props(styles.emptyState)}>{emptyState}</div>
+ ) : null}
+ </div>
+ </div>
+
+ {/* New messages button */}
+ <button
+ type="button"
+ aria-label="New messages — scroll to bottom"
+ onClick={dismissNewMessages}
+ {...stylex.props(
+ styles.newMessagesButton,
+ showNewMessages
+ ? styles.newMessagesVisible
+ : styles.newMessagesHidden,
+ )}>
+ New messages ↓
+ </button>
+ </div>
+ </XDSChatListContext.Provider>
+ );
+}
+
+XDSChatMessageList.displayName = 'XDSChatMessageList';
diff --git a/packages/core/src/Chat/XDSChatMessageMetadata.tsx b/packages/core/src/Chat/XDSChatMessageMetadata.tsx
new file mode 100644
index 0000000000..1f470b54a1
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatMessageMetadata.tsx
@@ -0,0 +1,150 @@
+'use client';
+
+/**
+ * @file XDSChatMessageMetadata.tsx
+ * @input Uses React, StyleX, XDSChatContext, XDSIcon, theme tokens
+ * @output Exports XDSChatMessageMetadata component
+ * @position Shared metadata row used by composing inside XDSChatMessage
+ *
+ * Renders: <timestamp> · <footer> · <status>
+ * Direction reverses for user sender.
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ typeScaleVars,
+ fontWeightVars,
+} from '../theme/tokens.stylex';
+import {useXDSChatMessageContext} from './XDSChatContext';
+import {XDSIcon} from '../Icon';
+import type {XDSIconName} from '../Icon/globalIconRegistry';
+
+export type XDSChatMessageStatus =
+ | 'sending'
+ | 'sent'
+ | 'delivered'
+ | 'read'
+ | 'error';
+
+const STATUS_CONFIG: Record<
+ XDSChatMessageStatus,
+ {icon: XDSIconName; label: string}
+> = {
+ sending: {icon: 'clock', label: 'Sending'},
+ sent: {icon: 'check', label: 'Sent'},
+ delivered: {icon: 'checkDouble', label: 'Delivered'},
+ read: {icon: 'checkDouble', label: 'Read'},
+ error: {icon: 'xCircle', label: 'Failed'},
+};
+
+const pulseKeyframes = stylex.keyframes({
+ '0%, 100%': {opacity: 1},
+ '50%': {opacity: 0.5},
+});
+
+const styles = stylex.create({
+ meta: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ marginBlockStart: spacingVars['--spacing-1'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ lineHeight: typeScaleVars['--text-supporting-leading'],
+ color: colorVars['--color-text-secondary'],
+ },
+ metaUser: {
+ flexDirection: 'row-reverse',
+ },
+ metaAssistant: {
+ flexDirection: 'row',
+ },
+ statusRow: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ },
+ statusError: {
+ color: colorVars['--color-error'],
+ },
+ statusPulse: {
+ animationName: pulseKeyframes,
+ animationDuration: '1.5s',
+ animationTimingFunction: 'ease-in-out',
+ animationIterationCount: 'infinite',
+ '@media (prefers-reduced-motion: reduce)': {
+ animationName: 'none',
+ },
+ },
+});
+
+export interface XDSChatMessageMetadataProps {
+ /** Timestamp content — ReactNode (e.g. XDSTimestamp) or string. */
+ timestamp?: ReactNode;
+ /** Footer content — model info, ratings, reactions. */
+ footer?: ReactNode;
+ /** Message delivery status. */
+ status?: XDSChatMessageStatus;
+}
+
+/**
+ * Composable metadata row for chat messages.
+ *
+ * Renders: timestamp · footer · status
+ * Renders nothing if all props are null/undefined.
+ *
+ * @example
+ * ```
+ * <XDSChatMessage sender="user">
+ * <XDSChatMessageBubble>Hello!</XDSChatMessageBubble>
+ * <XDSChatMessageMetadata timestamp={<XDSTimestamp value="..." format="time" />} status="read" />
+ * </XDSChatMessage>
+ * ```
+ */
+export function XDSChatMessageMetadata({
+ timestamp,
+ footer,
+ status,
+}: XDSChatMessageMetadataProps) {
+ const msgContext = useXDSChatMessageContext();
+ const sender = msgContext?.sender ?? 'assistant';
+
+ const statusConfig = status != null ? STATUS_CONFIG[status] : null;
+
+ const hasContent =
+ timestamp != null || footer != null || statusConfig != null;
+ if (!hasContent) return null;
+
+ return (
+ <div
+ {...stylex.props(
+ styles.meta,
+ sender === 'user' ? styles.metaUser : styles.metaAssistant,
+ )}>
+ {timestamp != null && <span>{timestamp}</span>}
+ {timestamp != null && (footer != null || statusConfig != null) && (
+ <span>·</span>
+ )}
+ {footer != null && footer}
+ {footer != null && statusConfig != null && <span>·</span>}
+ {statusConfig != null && (
+ <span
+ title={statusConfig.label}
+ aria-label={'Message ' + statusConfig.label.toLowerCase()}
+ {...stylex.props(
+ styles.statusRow,
+ status === 'error' && styles.statusError,
+ status === 'sending' && styles.statusPulse,
+ )}>
+ <XDSIcon icon={statusConfig.icon} size="xsm" color="inherit" />
+ <span>{statusConfig.label}</span>
+ </span>
+ )}
+ </div>
+ );
+}
+
+XDSChatMessageMetadata.displayName = 'XDSChatMessageMetadata';
diff --git a/packages/core/src/Chat/XDSChatSystemMessage.test.tsx b/packages/core/src/Chat/XDSChatSystemMessage.test.tsx
new file mode 100644
index 0000000000..50a9c39ceb
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatSystemMessage.test.tsx
@@ -0,0 +1,60 @@
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSChatSystemMessage} from './XDSChatSystemMessage';
+
+describe('XDSChatSystemMessage', () => {
+ it('renders children', () => {
+ render(<XDSChatSystemMessage>Conversation started</XDSChatSystemMessage>);
+ expect(screen.getByText('Conversation started')).toBeTruthy();
+ });
+
+ it('has role="status"', () => {
+ render(
+ <XDSChatSystemMessage data-testid="sys">Notice</XDSChatSystemMessage>,
+ );
+ const el = screen.getByTestId('sys');
+ expect(el.getAttribute('role')).toBe('status');
+ });
+
+ it('renders default variant without divider lines', () => {
+ const {container} = render(
+ <XDSChatSystemMessage>Hello</XDSChatSystemMessage>,
+ );
+ // Divider lines have aria-hidden, so check there are none
+ const hiddenElements = container.querySelectorAll('[aria-hidden]');
+ expect(hiddenElements.length).toBe(0);
+ });
+
+ it('renders divider variant with XDSDivider', () => {
+ render(
+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>,
+ );
+ expect(screen.getByText('Today')).toBeTruthy();
+ });
+
+ it('renders icon', () => {
+ render(
+ <XDSChatSystemMessage icon={<span data-testid="icon">*</span>}>
+ Notice
+ </XDSChatSystemMessage>,
+ );
+ expect(screen.getByTestId('icon')).toBeTruthy();
+ });
+
+ it('applies variant class', () => {
+ render(
+ <XDSChatSystemMessage variant="divider" data-testid="sys">
+ Today
+ </XDSChatSystemMessage>,
+ );
+ const el = screen.getByTestId('sys');
+ expect(el.className).toContain('divider');
+ });
+
+ it('applies data-testid', () => {
+ render(
+ <XDSChatSystemMessage data-testid="my-sys">Hello</XDSChatSystemMessage>,
+ );
+ expect(screen.getByTestId('my-sys')).toBeTruthy();
+ });
+});
diff --git a/packages/core/src/Chat/XDSChatSystemMessage.tsx b/packages/core/src/Chat/XDSChatSystemMessage.tsx
new file mode 100644
index 0000000000..eb737db498
--- /dev/null
+++ b/packages/core/src/Chat/XDSChatSystemMessage.tsx
@@ -0,0 +1,168 @@
+'use client';
+
+/**
+ * @file XDSChatSystemMessage.tsx
+ * @input Uses React, StyleX, theme tokens
+ * @output Exports XDSChatSystemMessage component and XDSChatSystemMessageProps
+ * @position Centered system/notice message in a chat thread
+ *
+ * Renders centered, muted system messages like "conversation started",
+ * date separators, or status updates. Not a sender message — no avatar,
+ * no bubble, no alignment. Think of it as the chat equivalent of a banner
+ * or status line.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Chat/index.ts (exports)
+ * - /apps/storybook/stories/Chat.stories.tsx
+ */
+
+import {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ typeScaleVars,
+ fontWeightVars,
+ typographyVars,
+} from '../theme/tokens.stylex';
+import {xdsClassName, mergeProps} from '../utils';
+import {XDSDivider} from '../Divider';
+
+export type XDSChatSystemMessageVariant = 'default' | 'divider';
+
+export interface XDSChatSystemMessageProps {
+ /** Ref forwarded to the root element */
+ ref?: React.Ref<HTMLDivElement>;
+
+ /**
+ * System message content — text or any ReactNode.
+ */
+ children: ReactNode;
+
+ /**
+ * Visual variant.
+ * - 'default': plain centered text
+ * - 'divider': text with horizontal lines on each side (date separator style)
+ * @default 'default'
+ */
+ variant?: XDSChatSystemMessageVariant;
+
+ /**
+ * Optional icon rendered before the text.
+ * Accepts any ReactNode — typically an XDSIcon.
+ */
+ icon?: ReactNode;
+
+ /** StyleX overrides. */
+ xstyle?: StyleXStyles;
+ /** CSS class name(s). */
+ className?: string;
+ /** Inline styles. */
+ style?: React.CSSProperties;
+ /** Test ID. */
+ 'data-testid'?: string;
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+ root: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ gap: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ color: colorVars['--color-text-secondary'],
+ textAlign: 'center',
+ userSelect: 'none',
+ },
+ dividerWrap: {
+ width: '100%',
+ },
+ // Icon
+ icon: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ flexShrink: 0,
+ },
+ // Content wrapper (to keep text + icon together)
+ content: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1-5'],
+ flexShrink: 0,
+ whiteSpace: 'nowrap',
+ },
+});
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Centered system message for chat threads.
+ *
+ * Use for non-sender content: date separators, "conversation started",
+ * "user joined", status changes. Supports a divider variant with horizontal
+ * lines on each side of the text.
+ *
+ * @example
+ * ```
+ * <XDSChatSystemMessage>Conversation started</XDSChatSystemMessage>
+ * <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
+ * <XDSChatSystemMessage variant="divider">March 15, 2026</XDSChatSystemMessage>
+ * ```
+ */
+export function XDSChatSystemMessage({
+ children,
+ variant = 'default',
+ icon,
+ xstyle,
+ className,
+ style: styleProp,
+ 'data-testid': testId,
+ ref,
+}: XDSChatSystemMessageProps) {
+ if (variant === 'divider') {
+ return (
+ <div
+ ref={ref}
+ role="status"
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('chat-system-message', {variant}),
+ stylex.props(styles.dividerWrap, xstyle),
+ className,
+ styleProp,
+ )}>
+ <XDSDivider label={children} />
+ </div>
+ );
+ }
+
+ return (
+ <div
+ ref={ref}
+ role="status"
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('chat-system-message', {variant}),
+ stylex.props(styles.root, xstyle),
+ className,
+ styleProp,
+ )}>
+ <span {...stylex.props(styles.content)}>
+ {icon != null && <span {...stylex.props(styles.icon)}>{icon}</span>}
+ {children}
+ </span>
+ </div>
+ );
+}
+
+XDSChatSystemMessage.displayName = 'XDSChatSystemMessage';
diff --git a/packages/core/src/Chat/index.ts b/packages/core/src/Chat/index.ts
index b1a8fdca30..2fa6e8b96b 100644
--- a/packages/core/src/Chat/index.ts
+++ b/packages/core/src/Chat/index.ts
@@ -2,6 +2,8 @@
/**
* @file Chat component barrel export
+ *
+ * SYNC: When modified, update /packages/core/src/index.ts
*/
export {XDSChatComposer} from './XDSChatComposer';
@@ -14,10 +16,42 @@ export type {
export {XDSChatComposerAttachments} from './XDSChatComposerAttachments';
export type {XDSChatComposerAttachmentsProps} from './XDSChatComposerAttachments';
-export {XDSChatComposerInput, XDSChatComposerTokenElement} from './XDSChatComposerInput';
+export {
+ XDSChatComposerInput,
+ XDSChatComposerTokenElement,
+} from './XDSChatComposerInput';
export type {
XDSChatComposerInputProps,
XDSChatComposerToken,
XDSChatComposerTrigger,
XDSChatComposerTriggerItem,
} from './XDSChatComposerInput';
+
+export {XDSChatMessageList} from './XDSChatMessageList';
+export type {XDSChatMessageListProps} from './XDSChatMessageList';
+
+export {XDSChatMessage} from './XDSChatMessage';
+export type {XDSChatMessageProps} from './XDSChatMessage';
+
+export {XDSChatMessageBubble} from './XDSChatMessageBubble';
+export type {
+ XDSChatMessageBubbleProps,
+ XDSChatMessageBubbleVariant,
+} from './XDSChatMessageBubble';
+
+export {XDSChatMessageMetadata} from './XDSChatMessageMetadata';
+export type {
+ XDSChatMessageMetadataProps,
+ XDSChatMessageStatus,
+} from './XDSChatMessageMetadata';
+
+export {XDSChatSystemMessage} from './XDSChatSystemMessage';
+export type {
+ XDSChatSystemMessageProps,
+ XDSChatSystemMessageVariant,
+} from './XDSChatSystemMessage';
+
+export {useAutoScroll} from './useAutoScroll';
+export type {UseAutoScrollOptions, UseAutoScrollReturn} from './useAutoScroll';
+
+export type {XDSChatMessageSender, XDSChatDensity} from './XDSChatContext';
diff --git a/packages/core/src/Chat/useAutoScroll.ts b/packages/core/src/Chat/useAutoScroll.ts
new file mode 100644
index 0000000000..abcb592255
--- /dev/null
+++ b/packages/core/src/Chat/useAutoScroll.ts
@@ -0,0 +1,127 @@
+'use client';
+
+/**
+ * @file useAutoScroll.ts
+ * @input Uses React refs, state, and effects
+ * @output Exports useAutoScroll hook for scroll-pinning behavior
+ * @position Utility hook — used by XDSChatMessageList, also usable standalone
+ */
+
+import {useCallback, useEffect, useRef, useState} from 'react';
+
+export interface UseAutoScrollOptions {
+ /**
+ * Whether auto-scroll is enabled.
+ * @default true
+ */
+ enabled?: boolean;
+
+ /**
+ * Distance from bottom (in px) within which new content triggers auto-scroll.
+ * @default 12
+ */
+ threshold?: number;
+}
+
+export interface UseAutoScrollReturn {
+ /** Ref to attach to the scrollable container element. */
+ scrollRef: React.RefObject<HTMLDivElement | null>;
+
+ /** Whether the "new messages" indicator should be shown. */
+ showNewMessages: boolean;
+
+ /** Scroll handler — attach to onScroll on the scrollable element. */
+ handleScroll: () => void;
+
+ /** Scroll to the bottom of the container. */
+ scrollToBottom: (smooth?: boolean) => void;
+
+ /** Dismiss the new messages indicator and scroll to bottom. */
+ dismissNewMessages: () => void;
+
+ /** Notify the hook that content changed (triggers auto-scroll check). */
+ onContentChange: () => void;
+}
+
+/**
+ * Hook that manages auto-scroll behavior for scrollable containers.
+ *
+ * Pins to the bottom when the user is near the end. Shows a "new messages"
+ * indicator when new content arrives while scrolled up.
+ *
+ * @example
+ * ```
+ * const {scrollRef, showNewMessages, handleScroll, dismissNewMessages} = useAutoScroll();
+ *
+ * return (
+ * <div ref={scrollRef} onScroll={handleScroll}>
+ * {messages}
+ * {showNewMessages && <button onClick={dismissNewMessages}>New messages</button>}
+ * </div>
+ * );
+ * ```
+ */
+export function useAutoScroll({
+ enabled = true,
+ threshold = 12,
+}: UseAutoScrollOptions = {}): UseAutoScrollReturn {
+ const scrollRef = useRef<HTMLDivElement | null>(null);
+ const [showNewMessages, setShowNewMessages] = useState(false);
+ const isNearBottomRef = useRef(true);
+
+ const scrollToBottom = useCallback((smooth = true) => {
+ const el = scrollRef.current;
+ if (!el) return;
+ if (typeof el.scrollTo === 'function') {
+ el.scrollTo({
+ top: el.scrollHeight,
+ behavior: smooth ? 'smooth' : 'instant',
+ });
+ } else {
+ el.scrollTop = el.scrollHeight;
+ }
+ }, []);
+
+ const checkNearBottom = useCallback(() => {
+ const el = scrollRef.current;
+ if (!el) return true;
+ const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+ return distanceFromBottom <= threshold;
+ }, [threshold]);
+
+ const handleScroll = useCallback(() => {
+ const nearBottom = checkNearBottom();
+ isNearBottomRef.current = nearBottom;
+ if (nearBottom) {
+ setShowNewMessages(false);
+ }
+ }, [checkNearBottom]);
+
+ const onContentChange = useCallback(() => {
+ if (!enabled) return;
+ if (isNearBottomRef.current) {
+ scrollToBottom(true);
+ } else {
+ setShowNewMessages(true);
+ }
+ }, [enabled, scrollToBottom]);
+
+ const dismissNewMessages = useCallback(() => {
+ scrollToBottom();
+ setShowNewMessages(false);
+ }, [scrollToBottom]);
+
+ // Scroll to bottom on mount
+ useEffect(() => {
+ scrollToBottom(false);
+ }, []);
+
+ return {
+ scrollRef,
+ showNewMessages,
+ handleScroll,
+ scrollToBottom,
+ dismissNewMessages,
+ onContentChange,
+ };
+}
diff --git a/packages/core/src/Icon/defaultIcons.tsx b/packages/core/src/Icon/defaultIcons.tsx
index 3fa7e2e6a2..7926211da4 100644
--- a/packages/core/src/Icon/defaultIcons.tsx
+++ b/packages/core/src/Icon/defaultIcons.tsx
@@ -227,4 +227,12 @@ export const defaultIcons: XDSIconRegistry = {
<path d="M16 18v2a2 2 0 01-2 2H6a2 2 0 01-2-2V9a2 2 0 012-2h2" />
</svg>
),
+
+ /** ✓✓ — double checkmark (delivered/read) */
+ checkDouble: (
+ <svg {...svgProps}>
+ <path d="M2 13l4 4L14 7" />
+ <path d="M9 13l4 4L21 7" />
+ </svg>
+ ),
};
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
index 8863f7eb0a..3bfa171c65 100644
--- a/packages/core/src/Icon/globalIconRegistry.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -43,7 +43,8 @@ export type XDSIconName =
| 'funnel'
| 'eyeSlash'
| 'viewColumns'
- | 'copy';
+ | 'copy'
+ | 'checkDouble';
/**
* Icon registry mapping semantic names to React nodes.
diff --git a/packages/core/src/List/XDSListItem.tsx b/packages/core/src/List/XDSListItem.tsx
index 7e40f41af7..b24401e851 100644
--- a/packages/core/src/List/XDSListItem.tsx
+++ b/packages/core/src/List/XDSListItem.tsx
@@ -255,7 +255,7 @@ const markerStyles = stylex.create({
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
- width: spacingVars['--spacing-3'],
+ width: spacingVars['--spacing-4'],
// Vertically center the dot/circle with the first line of text:
// shift down by (lineHeight - dotSize) / 2
marginTop: `calc((1em * ${typeScaleVars['--text-body-leading']} - ${MARKER_DOT_SIZE}px) / 2)`,
@@ -281,7 +281,7 @@ const markerStyles = stylex.create({
color: colorVars['--color-text-primary'],
fontSize: typeScaleVars['--text-body-size'],
lineHeight: typeScaleVars['--text-body-leading'],
- width: spacingVars['--spacing-3'],
+ width: spacingVars['--spacing-4'],
'::before': {
content: 'counter(xds-list) "."',
},
diff --git a/packages/themes/default/src/icons.tsx b/packages/themes/default/src/icons.tsx
index d0083c87f2..025ed24cfa 100644
--- a/packages/themes/default/src/icons.tsx
+++ b/packages/themes/default/src/icons.tsx
@@ -68,4 +68,5 @@ export const defaultIconRegistry: XDSIconRegistry = {
eyeSlash: <EyeSlashIcon {...iconProps} />,
viewColumns: <ViewColumnsIcon {...iconProps} />,
copy: <ClipboardDocumentIcon {...iconProps} />,
+ checkDouble: <CheckIcon {...iconProps} />,
};
diff --git a/packages/themes/meta/src/icons.tsx b/packages/themes/meta/src/icons.tsx
index 3cf51fa901..0542955882 100644
--- a/packages/themes/meta/src/icons.tsx
+++ b/packages/themes/meta/src/icons.tsx
@@ -69,4 +69,5 @@ export const metaIconRegistry: XDSIconRegistry = {
eyeSlash: <EyeSlashIcon {...iconProps} />,
viewColumns: <ViewColumnsIcon {...iconProps} />,
copy: <ClipboardDocumentIcon {...iconProps} />,
+ checkDouble: <CheckIcon {...iconProps} />,
};
diff --git a/packages/themes/neutral/src/icons.tsx b/packages/themes/neutral/src/icons.tsx
index 435b6fd165..0ea78c6f53 100644
--- a/packages/themes/neutral/src/icons.tsx
+++ b/packages/themes/neutral/src/icons.tsx
@@ -34,6 +34,7 @@ import {
EyeOff,
Columns,
Copy,
+ CheckCheck,
} from 'lucide-react';
const iconProps = {
@@ -64,4 +65,5 @@ export const neutralIconRegistry: XDSIconRegistry = {
eyeSlash: <EyeOff {...iconProps} />,
viewColumns: <Columns {...iconProps} />,
copy: <Copy {...iconProps} />,
+ checkDouble: <CheckCheck {...iconProps} />,
};
diff --git a/packages/themes/whatsapp/src/icons.tsx b/packages/themes/whatsapp/src/icons.tsx
index 4d5bfc025a..d8625b8ef0 100644
--- a/packages/themes/whatsapp/src/icons.tsx
+++ b/packages/themes/whatsapp/src/icons.tsx
@@ -66,4 +66,5 @@ export const whatsappIconRegistry: XDSIconRegistry = {
eyeSlash: <EyeSlashIcon {...iconProps} />,
viewColumns: <ViewColumnsIcon {...iconProps} />,
copy: <ClipboardDocumentIcon {...iconProps} />,
+ checkDouble: <CheckIcon {...iconProps} />,
};