Skip to content

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

TypeScript

feat(Chat): bubble ghost variant, header/metadata slots, compact radius (#1293)

Cindy Zhang7d011fba522d
diff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsx
index 70c6f118e2..13e70f1ad1 100644
--- a/apps/storybook/stories/Chat.stories.tsx
+++ b/apps/storybook/stories/Chat.stories.tsx
@@ -12,12 +12,9 @@ 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 {XDSEmptyState} from '@xds/core/EmptyState';
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',
@@ -29,182 +26,278 @@ export default meta;
export const Default: StoryObj = {
name: 'Default',
render: () => (
- <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <div style={{height: 600, display: 'flex', flexDirection: 'column'}}>
<XDSChatMessageList>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>How do I center a div?</XDSChatMessageBubble>
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:30:00" format="time" />}
+ status="read"
+ />
+ }>
+ How should I handle state management in a React app?
+ </XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="assistant">
- <XDSMarkdown density="compact">{`There are several ways:
+ <XDSMarkdown density="compact">{`For most cases, **React's built-in state** is sufficient:
-**Flexbox** (most common):
-\`\`\`css
-display: flex;
-justify-content: center;
-align-items: center;
-\`\`\`
+- \`useState\` for local component state
+- \`useReducer\` for complex state logic
+- \`useContext\` for shared state across a subtree
-**Grid** (simplest):
-\`\`\`css
-display: grid;
-place-items: center;
-\`\`\`
+For **server state**, use a library like **TanStack Query** or **SWR** — they handle caching, revalidation, and loading states out of the box.
-Both work great.`}</XDSMarkdown>
+Avoid global state managers unless you have a genuine need for cross-cutting state. Most apps are over-engineered in this area.`}</XDSMarkdown>
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:30:30" 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"
+ isIconOnly
+ />
+ <XDSButton
+ label="Thumbs down"
+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ isIconOnly
+ />
+ <XDSButton
+ label="Copy"
+ icon={<ClipboardDocumentIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ isIconOnly
+ />
+ </>
+ }
+ />
</XDSChatMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>
- What about absolute positioning?
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}
+ status="read"
+ />
+ }>
+ Can you show me a useReducer example?
</XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="assistant">
- <XDSMarkdown density="compact">{`You can, but prefer flexbox or grid — they handle responsive layouts much better.`}</XDSMarkdown>
+ <XDSMarkdown density="compact">Here's a common pattern for form state:</XDSMarkdown>
+ <XDSCodeBlock
+ code={`const reducer = (state, action) => {
+ switch (action.type) {
+ case 'SET_FIELD':
+ return { ...state, [action.field]: action.value };
+ case 'RESET':
+ return initialState;
+ default:
+ return state;
+ }
+};
+
+const [state, dispatch] = useReducer(reducer, initialState);`}
+ language="tsx"
+ />
+ <XDSMarkdown density="compact">{`This keeps all your form logic in one place. The reducer is pure and easy to test — just pass in state and action, assert on the output.`}</XDSMarkdown>
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:31:30" 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"
+ isIconOnly
+ />
+ <XDSButton
+ label="Thumbs down"
+ icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ isIconOnly
+ />
+ <XDSButton
+ label="Copy"
+ icon={<ClipboardDocumentIcon style={{width: 14, height: 14}} />}
+ variant="ghost"
+ size="sm"
+ isIconOnly
+ />
+ </>
+ }
+ />
</XDSChatMessage>
</XDSChatMessageList>
</div>
),
};
-export const Detailed: StoryObj = {
- name: 'Detailed',
+export const MixedContent: StoryObj = {
+ name: 'Mixed Content',
render: () => (
- <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <div style={{height: 600, display: 'flex', flexDirection: 'column'}}>
<XDSChatMessageList>
- <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
- <XDSChatMessage sender="user" name="Cindy">
+ <XDSChatMessage sender="user">
<XDSChatMessageBubble>
- Can you look at the chat component spec?
+ Show me the component files and explain the architecture
</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
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble>
+ Sure! Here's an overview of the component architecture.
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble variant="ghost">
+ <XDSMarkdown density="compact">{`The system uses a **compound component** pattern with three layers:
-No new components needed.`}</XDSMarkdown>
- </XDSChatMessage>
- <XDSChatMessage sender="user" name="Cindy">
+1. **MessageList** — scrollable container with auto-scroll
+2. **Message** — layout wrapper with sender context
+3. **Bubble** — styled content container`}</XDSMarkdown>
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble variant="ghost">
+ <XDSMarkdown density="compact">Here are the files:</XDSMarkdown>
+ <XDSHStack gap={2} wrap="wrap">
+ <XDSToken label="Button.tsx" />
+ <XDSToken label="Card.tsx" />
+ <XDSToken label="Dialog.tsx" />
+ </XDSHStack>
+ <XDSCodeBlock
+ code={
+ "export * from './Button';\nexport * from './Card';\nexport * from './Dialog';"
+ }
+ language="typescript"
+ />
+ </XDSChatMessageBubble>
<XDSChatMessageBubble>
- Nice, what about system messages?
+ Let me know which one to open — I can walk through the
+ implementation.
</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" />}>
- <XDSMarkdown density="compact">{`Good afternoon! I've been looking at the **NDS gap analysis** and have the priority list ready.`}</XDSMarkdown>
- <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 sender="user">
+ <XDSChatMessageBubble>Open Button.tsx</XDSChatMessageBubble>
</XDSChatMessage>
- <XDSChatMessage
- sender="assistant"
- name="Navi"
- avatar={<XDSAvatar name="Navi" size="small" />}>
- <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>
- <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.
+ <XDSChatSystemMessage>Navi opened Button.tsx</XDSChatSystemMessage>
+
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble variant="ghost">
+ <XDSCodeBlock
+ code={`import * as stylex from '@stylexjs/stylex';
+
+export function XDSButton({ label, variant = 'primary' }) {
+ return (
+ <button {...stylex.props(styles.base, styles[variant])}>
+ {label}
+ </button>
+ );
+}`}
+ language="tsx"
+ />
+ <XDSMarkdown density="compact">{`The Button uses StyleX for styles and reads variant from props.`}</XDSMarkdown>
</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 ChatConversation: StoryObj = {
+ name: 'Chat Conversation',
+ render: () => {
+ const nameStyle = {
+ fontSize: 12,
+ fontWeight: 600,
+ color: '#666',
+ lineHeight: '16px',
+ };
+ return (
+ <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList>
+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble
+ name={<span style={nameStyle}>Navi</span>}
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:30:00" format="time" />}
+ />
+ }>
+ Hey! I looked at the PR and left a few comments on the density
+ styles.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage
+ sender="user"
+ avatar={<XDSAvatar name="Cindy" size="small" />}>
+ <XDSChatMessageBubble
+ group="first"
+ name={<span style={nameStyle}>Cindy</span>}>
+ Thanks! I'll take a look.
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble
+ group="last"
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}
+ status="read"
+ />
+ }>
+ Should be quick to fix.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble
+ name={<span style={nameStyle}>Navi</span>}
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:32:00" format="time" />}
+ />
+ }>
+ Sounds good. The main thing is the compact radius — it should use
+ the container token, not the page token.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage
+ sender="user"
+ avatar={<XDSAvatar name="Cindy" size="small" />}>
+ <XDSChatMessageBubble
+ name={<span style={nameStyle}>Cindy</span>}
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:33:00" format="time" />}
+ status="delivered"
+ />
+ }>
+ Good catch, fixed and pushed.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatSystemMessage>Cindy liked a message</XDSChatSystemMessage>
+ </XDSChatMessageList>
+ </div>
+ );
+ },
};
export const DensityComparison: StoryObj = {
@@ -277,7 +370,6 @@ This is the **${density}** density. ${density === 'compact' ? 'Great for sidebar
);
},
};
-
export const SystemMessages: StoryObj = {
name: 'System Messages',
render: () => (
@@ -301,104 +393,45 @@ export const SystemMessages: StoryObj = {
</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">
- <XDSMarkdown density="compact">{msg.text}</XDSMarkdown>
- </XDSChatMessage>
- ),
- )}
- </XDSChatMessageList>
- </div>
- );
- },
-};
-
-export const EmptyState: StoryObj = {
- name: 'Empty State',
- render: () => (
- <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>
- <XDSChatMessageList
- emptyState={
- <XDSEmptyState
- title="No messages yet"
- description="Start a conversation!"
- />
- }>
- {[]}
- </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" />
+ <XDSChatMessageBubble
+ metadata={<XDSChatMessageMetadata status="sending" />}>
+ Sending...
+ </XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>Sent</XDSChatMessageBubble>
- <XDSChatMessageMetadata status="sent" />
+ <XDSChatMessageBubble
+ metadata={<XDSChatMessageMetadata status="sent" />}>
+ Sent
+ </XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>Delivered</XDSChatMessageBubble>
- <XDSChatMessageMetadata status="delivered" />
+ <XDSChatMessageBubble
+ metadata={<XDSChatMessageMetadata status="delivered" />}>
+ Delivered
+ </XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>Read</XDSChatMessageBubble>
- <XDSChatMessageMetadata status="read" />
+ <XDSChatMessageBubble
+ metadata={<XDSChatMessageMetadata status="read" />}>
+ Read
+ </XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>Failed to send</XDSChatMessageBubble>
- <XDSChatMessageMetadata status="error" />
+ <XDSChatMessageBubble
+ metadata={<XDSChatMessageMetadata status="error" />}>
+ Failed to send
+ </XDSChatMessageBubble>
</XDSChatMessage>
</XDSChatMessageList>
</div>
),
};
-
export const MultiBubble: StoryObj = {
name: 'Multi-Bubble Grouping',
render: () => (
@@ -411,15 +444,18 @@ export const MultiBubble: StoryObj = {
<XDSChatMessageBubble group="middle">
It's the one for the chat components
</XDSChatMessageBubble>
- <XDSChatMessageBubble group="last">
+ <XDSChatMessageBubble
+ group="last"
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
+ status="delivered"
+ />
+ }>
Link: github.com/xds/pull/1180
</XDSChatMessageBubble>
- <XDSChatMessageMetadata
- timestamp={
- <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
- }
- status="delivered"
- />
</XDSChatMessage>
<XDSChatMessage
sender="assistant"
@@ -431,239 +467,32 @@ export const MultiBubble: StoryObj = {
The compound pattern looks solid. A few minor comments on the
density styles.
</XDSChatMessageBubble>
- <XDSChatMessageBubble group="last">
+ <XDSChatMessageBubble
+ group="last"
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:33:00" format="time" />
+ }
+ />
+ }>
I'll leave them as review comments.
</XDSChatMessageBubble>
- <XDSChatMessageMetadata
- timestamp={
- <XDSTimestamp value="2026-03-15T14:33:00" format="time" />
- }
- />
</XDSChatMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:34:00" format="time" />
+ }
+ status="sending"
+ />
+ }>
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"
- isIconOnly
- />
- <XDSButton
- label="Thumbs down"
- icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}
- variant="ghost"
- size="sm"
- isIconOnly
- />
- </>
- }
- />
- </XDSChatMessage>
- <XDSChatMessage
- sender="assistant"
- name="Navi"
- avatar={<XDSAvatar name="Navi" size="small" />}>
- <XDSMarkdown density="compact">
- Avoid global state managers unless you have a genuine need for
- cross-cutting state. Most apps are over-engineered in this area.
- </XDSMarkdown>
- <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"
- isIconOnly
- />
- <XDSButton
- label="Thumbs down"
- icon={<HandThumbDownIcon style={{width: 14, height: 14}} />}
- variant="ghost"
- size="sm"
- isIconOnly
- />
- <XDSButton
- label="Copy"
- icon={
- <ClipboardDocumentIcon style={{width: 14, height: 14}} />
- }
- variant="ghost"
- size="sm"
- isIconOnly
- />
- </>
- }
- />
- </XDSChatMessage>
- </XDSChatMessageList>
- </div>
- ),
-};
-
-export const ScrollToBottom: StoryObj = {
- name: 'Scroll to Bottom',
- render: () => {
- const [messages, setMessages] = useState(
- Array.from({length: 30}, (_, i) => ({
- id: i + 1,
- sender: i % 2 === 0 ? ('user' as const) : ('assistant' as const),
- text:
- i % 2 === 0
- ? `User message #${i + 1}`
- : `This is assistant response #${i + 1}. It has enough content to require scrolling through the message list.`,
- })),
- );
-
- const addNewMessage = useCallback(() => {
- setMessages(prev => [
- ...prev,
- {
- id: prev.length + 1,
- sender: 'assistant' as const,
- text: `New message arrived at ${new Date().toLocaleTimeString()}. Scroll up to see the button expand with a "New messages" label.`,
- },
- ]);
- }, []);
-
- return (
- <div style={{height: 400, display: 'flex', flexDirection: 'column'}}>
- <div
- style={{
- padding: '8px 16px',
- borderBottom: '1px solid var(--color-border)',
- display: 'flex',
- gap: 8,
- alignItems: 'center',
- }}>
- <XDSButton
- label="Add message"
- variant="secondary"
- size="sm"
- onClick={addNewMessage}
- />
- <span style={{fontSize: 12, color: 'var(--color-text-secondary)'}}>
- Scroll up, then click "Add message" to see the button expand
- </span>
- </div>
- <XDSChatMessageList>
- {messages.map(msg => (
- <XDSChatMessage key={msg.id} sender={msg.sender}>
- <XDSChatMessageBubble>{msg.text}</XDSChatMessageBubble>
- </XDSChatMessage>
- ))}
- </XDSChatMessageList>
- </div>
- );
- },
-};
diff --git a/packages/core/src/Chat/XDSChatMessage.test.tsx b/packages/core/src/Chat/XDSChatMessage.test.tsx
index 9aba343c9d..92e64f7e84 100644
--- a/packages/core/src/Chat/XDSChatMessage.test.tsx
+++ b/packages/core/src/Chat/XDSChatMessage.test.tsx
@@ -63,14 +63,16 @@ describe('XDSChatMessage', () => {
expect(el.className).toContain('user');
});
- it('sets accessible aria-label with name', () => {
+ it('sets accessible aria-labelledby 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');
+ const labelId = el.getAttribute('aria-labelledby');
+ expect(labelId).toBeTruthy();
+ expect(el.querySelector(`#${CSS.escape(labelId!)}`)?.textContent).toBe('Navi');
});
it('sets accessible aria-label without name', () => {
diff --git a/packages/core/src/Chat/XDSChatMessage.tsx b/packages/core/src/Chat/XDSChatMessage.tsx
index c1884c00e4..eb56405999 100644
--- a/packages/core/src/Chat/XDSChatMessage.tsx
+++ b/packages/core/src/Chat/XDSChatMessage.tsx
@@ -16,7 +16,7 @@
* - /apps/storybook/stories/Chat.stories.tsx
*/
-import {type ReactNode, useMemo} from 'react';
+import {type ReactNode, useMemo, useId} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {
@@ -38,7 +38,20 @@ export interface XDSChatMessageProps {
sender: XDSChatMessageSender;
children: ReactNode;
avatar?: ReactNode;
- name?: string;
+ /**
+ * Sender name rendered above the message body.
+ * Use when the first child is raw content (not a bubble).
+ * If the first child is a XDSChatMessageBubble, put the name on the
+ * bubble's `name` prop instead — it aligns with the bubble's padding.
+ */
+ name?: ReactNode;
+ /**
+ * Metadata rendered below the message body.
+ * Use when the last child is raw content (not a bubble).
+ * If the last child is a XDSChatMessageBubble, put metadata on the
+ * bubble's `metadata` prop instead — it aligns with the bubble's padding.
+ */
+ metadata?: ReactNode;
density?: XDSChatDensity;
xstyle?: StyleXStyles;
className?: string;
@@ -53,10 +66,10 @@ const styles = stylex.create({
maxWidth: '100%',
},
rootGapCompact: {
- gap: spacingVars['--spacing-2'],
+ gap: spacingVars['--spacing-1-5'],
},
rootGapBalanced: {
- gap: spacingVars['--spacing-3'],
+ gap: spacingVars['--spacing-2'],
},
rootGapSpacious: {
gap: spacingVars['--spacing-3'],
@@ -75,6 +88,9 @@ const styles = stylex.create({
},
avatarWrap: {
flexShrink: 0,
+ ':has(~ * [data-chat-name])': {
+ marginBlockStart: spacingVars['--spacing-5'],
+ },
},
contentColumn: {
display: 'flex',
@@ -102,7 +118,6 @@ const styles = stylex.create({
childrenWrap: {
display: 'flex',
flexDirection: 'column',
- minWidth: 0,
width: '100%',
},
childrenAssistant: {
@@ -144,6 +159,7 @@ export function XDSChatMessage({
children,
avatar,
name,
+ metadata,
density: densityProp,
xstyle,
className,
@@ -193,13 +209,16 @@ export function XDSChatMessage({
const isSystem = sender === 'system';
const hasAvatar = avatar != null && !isSystem;
+ const hasName = name != null && !isSystem;
+ const nameId = useId();
return (
<XDSChatMessageContext.Provider value={contextValue}>
<article
ref={ref}
data-testid={testId}
- aria-label={name ? `Message from ${name}` : `Message from ${sender}`}
+ aria-label={!hasName ? `Message from ${sender}` : undefined}
+ aria-labelledby={hasName ? nameId : undefined}
{...mergeProps(
xdsClassName('chat-message', {sender}),
stylex.props(
@@ -214,8 +233,8 @@ export function XDSChatMessage({
{hasAvatar && <div {...stylex.props(styles.avatarWrap)}>{avatar}</div>}
<div {...stylex.props(styles.contentColumn, columnAlignment)}>
- {name != null && !isSystem && (
- <span {...stylex.props(styles.name)}>{name}</span>
+ {hasName && (
+ <div id={nameId} {...stylex.props(styles.name)}>{name}</div>
)}
<div
@@ -226,6 +245,10 @@ export function XDSChatMessage({
)}>
{children}
</div>
+
+ {metadata != null && !isSystem && (
+ <div>{metadata}</div>
+ )}
</div>
</article>
</XDSChatMessageContext.Provider>
diff --git a/packages/core/src/Chat/XDSChatMessageBubble.tsx b/packages/core/src/Chat/XDSChatMessageBubble.tsx
index d30fe41599..60da6368eb 100644
--- a/packages/core/src/Chat/XDSChatMessageBubble.tsx
+++ b/packages/core/src/Chat/XDSChatMessageBubble.tsx
@@ -9,6 +9,14 @@
* Reads sender from parent XDSChatMessage context to auto-style background.
* Optional — not all message content needs bubble treatment.
*
+ * Usage guidance:
+ * - If you use bubbles on one side (e.g. assistant), use them consistently
+ * for all messages on that side. Use `ghost` variant for content that
+ * needs alignment without a visual boundary.
+ * - Put `name` on the first bubble in a message, `metadata` on the last.
+ * - For unbubbled messages, use XDSChatMessage's `name` and `metadata`
+ * props instead.
+ *
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Chat/index.ts (exports)
* - /apps/storybook/stories/Chat.stories.tsx
@@ -27,7 +35,7 @@ import {
import {useXDSChatMessageContext} from './XDSChatContext';
import {xdsClassName, mergeProps} from '../utils';
-export type XDSChatMessageBubbleVariant = 'filled' | 'transparent';
+export type XDSChatMessageBubbleVariant = 'filled' | 'ghost';
export interface XDSChatMessageBubbleProps {
/** Ref forwarded to the root element */
@@ -41,11 +49,27 @@ export interface XDSChatMessageBubbleProps {
/**
* Visual variant.
* - 'filled': background color based on sender (default)
- * - 'transparent': no background, no padding — just the content
+ * - 'ghost': no background, but keeps padding for consistent alignment
* @default 'filled'
*/
variant?: XDSChatMessageBubbleVariant;
+ /**
+ * Sender name rendered above the bubble, aligned with bubble text padding.
+ * Use when the first content in a message is a bubble.
+ * If the first content is raw (no bubble), use XDSChatMessage's `name`
+ * prop instead.
+ */
+ name?: ReactNode;
+
+ /**
+ * Metadata content rendered below the bubble, aligned with bubble text padding.
+ * Use when the last content in a message is a bubble.
+ * If the last content is raw (no bubble), use XDSChatMessage's `metadata`
+ * prop instead.
+ */
+ metadata?: ReactNode;
+
/**
* Position within a multi-bubble group.
* Controls corner radius reduction on the sender side.
@@ -71,7 +95,7 @@ export interface XDSChatMessageBubbleProps {
// =============================================================================
const styles = stylex.create({
- root: {
+ content: {
display: 'flex',
flexDirection: 'column',
maxWidth: '100%',
@@ -82,6 +106,9 @@ const styles = stylex.create({
overflowWrap: 'break-word',
wordBreak: 'break-word',
},
+ radiusCompact: {
+ borderRadius: radiusVars['--radius-container'],
+ },
paddingCompact: {
paddingBlock: spacingVars['--spacing-2'],
paddingInline: spacingVars['--spacing-3'],
@@ -94,10 +121,35 @@ const styles = stylex.create({
paddingBlock: spacingVars['--spacing-4'],
paddingInline: spacingVars['--spacing-5'],
},
- paddingNone: {
+ paddingBlockNone: {
paddingBlock: 0,
- paddingInline: 0,
},
+ // Slot padding — matches bubble's paddingInline per density
+ metadataPaddingCompact: {
+ paddingInline: spacingVars['--spacing-3'],
+ },
+ metadataPaddingBalanced: {
+ paddingInline: spacingVars['--spacing-4'],
+ },
+ metadataPaddingSpacious: {
+ paddingInline: spacingVars['--spacing-5'],
+ },
+ metadataReducedGap: {
+ marginBlockStart: `calc(-1 * ${spacingVars['--spacing-1']})`,
+ },
+ headerReducedGap: {
+ marginBlockEnd: `calc(-1 * ${spacingVars['--spacing-1']})`,
+ },
+ nameRow: {
+ height: spacingVars['--spacing-5'],
+ display: 'flex',
+ alignItems: 'center',
+ },
+ alignEnd: {
+ textAlign: 'end',
+ },
+ // Sender backgrounds — same default, but separate styles for theme overrides.
+ // Themes can target .xds-chat-message-bubble.user vs .assistant via @scope.
assistant: {
backgroundColor: colorVars['--color-neutral'],
color: colorVars['--color-text-primary'],
@@ -106,11 +158,7 @@ const styles = stylex.create({
backgroundColor: colorVars['--color-neutral'],
color: colorVars['--color-text-primary'],
},
- system: {
- backgroundColor: 'transparent',
- color: colorVars['--color-text-secondary'],
- },
- transparent: {
+ ghost: {
backgroundColor: 'transparent',
color: colorVars['--color-text-primary'],
},
@@ -151,15 +199,19 @@ const styles = stylex.create({
* @example
* ```
* <XDSChatMessage sender="user">
- * <XDSChatMessageBubble group="first">Hey</XDSChatMessageBubble>
- * <XDSChatMessageBubble group="last">What's up?</XDSChatMessageBubble>
- * <XDSChatMessageMetadata timestamp="2:30 PM" status="read" />
+ * <XDSChatMessageBubble
+ * name="Cindy"
+ * metadata={<XDSChatMessageMetadata timestamp="2:30 PM" status="read" />}>
+ * Hey, how's it going?
+ * </XDSChatMessageBubble>
* </XDSChatMessage>
* ```
*/
export function XDSChatMessageBubble({
children,
variant = 'filled',
+ name,
+ metadata,
group,
xstyle,
className,
@@ -172,20 +224,21 @@ export function XDSChatMessageBubble({
const density = msgContext?.density ?? 'balanced';
const paddingStyle =
- variant === 'transparent'
- ? styles.paddingNone
- : density === 'compact'
- ? styles.paddingCompact
- : density === 'spacious'
- ? styles.paddingSpacious
- : styles.paddingBalanced;
+ density === 'compact'
+ ? styles.paddingCompact
+ : density === 'spacious'
+ ? styles.paddingSpacious
+ : styles.paddingBalanced;
+
+ const isUser = sender === 'user';
const senderStyle =
- variant === 'transparent'
- ? styles.transparent
- : (styles[sender] ?? styles.assistant);
+ variant === 'ghost'
+ ? styles.ghost
+ : isUser
+ ? styles.user
+ : styles.assistant;
- const isUser = sender === 'user';
const groupStyle =
group === 'first'
? isUser
@@ -201,24 +254,57 @@ export function XDSChatMessageBubble({
: styles.groupLastAssistant
: null;
+ const metadataPaddingStyle =
+ density === 'compact'
+ ? styles.metadataPaddingCompact
+ : density === 'spacious'
+ ? styles.metadataPaddingSpacious
+ : styles.metadataPaddingBalanced;
+
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>
+ <>
+ {name && (
+ <div
+ data-chat-name
+ {...stylex.props(
+ metadataPaddingStyle,
+ styles.nameRow,
+ styles.headerReducedGap,
+ isUser && styles.alignEnd,
+ )}>
+ {name}
+ </div>
+ )}
+ <div
+ ref={ref}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('chat-message-bubble', {sender, variant}),
+ stylex.props(
+ styles.content,
+ density === 'compact' && styles.radiusCompact,
+ senderStyle,
+ paddingStyle,
+ variant === 'ghost' && styles.paddingBlockNone,
+ groupStyle,
+ xstyle,
+ ),
+ className,
+ styleProp,
+ )}>
+ {children}
+ </div>
+ {metadata && (
+ <div
+ {...stylex.props(
+ metadataPaddingStyle,
+ styles.metadataReducedGap,
+ isUser && styles.alignEnd,
+ )}>
+ {metadata}
+ </div>
+ )}
+ </>
);
}