Skip to content

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

TypeScript

fix(Chat): tune compact bubble padding and message gaps (#2321)

Cindy Zhangf1d89034ec6d
diff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsx
index 4528ddf0fd..7efbec68a9 100644
--- a/apps/storybook/stories/Chat.stories.tsx
+++ b/apps/storybook/stories/Chat.stories.tsx
@@ -34,7 +34,9 @@ export const Default: StoryObj = {
<XDSChatMessageBubble
metadata={
<XDSChatMessageMetadata
- timestamp={<XDSTimestamp value="2026-03-15T14:30:00" format="time" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
+ }
status="read"
/>
}>
@@ -52,7 +54,9 @@ For **server state**, use a library like **TanStack Query** or **SWR** — they
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" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:30" format="time" />
+ }
footer={
<>
<span>Claude Opus 4.6</span>
@@ -73,7 +77,9 @@ Avoid global state managers unless you have a genuine need for cross-cutting sta
/>
<XDSButton
label="Copy"
- icon={<ClipboardDocumentIcon style={{width: 14, height: 14}} />}
+ icon={
+ <ClipboardDocumentIcon style={{width: 14, height: 14}} />
+ }
variant="ghost"
size="sm"
isIconOnly
@@ -86,7 +92,9 @@ Avoid global state managers unless you have a genuine need for cross-cutting sta
<XDSChatMessageBubble
metadata={
<XDSChatMessageMetadata
- timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
status="read"
/>
}>
@@ -94,7 +102,9 @@ Avoid global state managers unless you have a genuine need for cross-cutting sta
</XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="assistant">
- <XDSMarkdown density="compact">Here's a common pattern for form state:</XDSMarkdown>
+ <XDSMarkdown density="compact">
+ Here's a common pattern for form state:
+ </XDSMarkdown>
<XDSCodeBlock
code={`const reducer = (state, action) => {
switch (action.type) {
@@ -120,7 +130,9 @@ const [state, dispatch] = useReducer(reducer, initialState);`}
| \`useSyncExternalStore\` | External stores | On snapshot change | High | Redux, Zustand, signals |
| \`useRef\` | Mutable values | Never | Low | DOM refs, timers, previous values |`}</XDSMarkdown>
<XDSChatMessageMetadata
- timestamp={<XDSTimestamp value="2026-03-15T14:31:30" format="time" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:30" format="time" />
+ }
footer={
<>
<span>Claude Opus 4.6</span>
@@ -141,7 +153,9 @@ const [state, dispatch] = useReducer(reducer, initialState);`}
/>
<XDSButton
label="Copy"
- icon={<ClipboardDocumentIcon style={{width: 14, height: 14}} />}
+ icon={
+ <ClipboardDocumentIcon style={{width: 14, height: 14}} />
+ }
variant="ghost"
size="sm"
isIconOnly
@@ -245,7 +259,9 @@ export const ChatConversation: StoryObj = {
name={<span style={nameStyle}>Navi</span>}
metadata={
<XDSChatMessageMetadata
- timestamp={<XDSTimestamp value="2026-03-15T14:30:00" format="time" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
+ }
/>
}>
Hey! I looked at the PR and left a few comments on the density
@@ -265,7 +281,9 @@ export const ChatConversation: StoryObj = {
group="last"
metadata={
<XDSChatMessageMetadata
- timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
status="read"
/>
}>
@@ -280,7 +298,9 @@ export const ChatConversation: StoryObj = {
name={<span style={nameStyle}>Navi</span>}
metadata={
<XDSChatMessageMetadata
- timestamp={<XDSTimestamp value="2026-03-15T14:32:00" format="time" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:32:00" format="time" />
+ }
/>
}>
Sounds good. The main thing is the compact radius — it should use
@@ -295,7 +315,9 @@ export const ChatConversation: StoryObj = {
name={<span style={nameStyle}>Cindy</span>}
metadata={
<XDSChatMessageMetadata
- timestamp={<XDSTimestamp value="2026-03-15T14:33:00" format="time" />}
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:33:00" format="time" />
+ }
status="delivered"
/>
}>
@@ -357,10 +379,12 @@ export const DensityComparison: StoryObj = {
avatar={<XDSAvatar name="Navi" size={avatarSize[density]} />}>
<XDSMarkdown density="compact">{`Density controls **spacing** at every level:
-- **Gap** between messages
+- **Default gap** between messages
- **Padding** inside bubbles
- **Gap** between child elements
+Use messageGap when top-level rows need different spacing from density.
+
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>
</XDSChatMessage>
<XDSChatMessage sender="user">
@@ -380,6 +404,36 @@ This is the **${density}** density. ${density === 'compact' ? 'Great for sidebar
);
},
};
+export const MessageGapOverride: StoryObj = {
+ name: 'Message Gap Override',
+ render: () => (
+ <div style={{height: 420, display: 'flex', flexDirection: 'column'}}>
+ <XDSChatMessageList density="compact" messageGap={5}>
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble name="Clio">
+ Starting the requested change.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble variant="ghost">
+ Reading repository context and relevant files...
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble variant="ghost">
+ Running tests for the updated package.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble
+ metadata={<XDSChatMessageMetadata footer="Done" />}>
+ The patch is ready for review.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </div>
+ ),
+};
export const SystemMessages: StoryObj = {
name: 'System Messages',
render: () => (
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
index 12630014cc..5d91b6434a 100644
--- a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
@@ -5,7 +5,7 @@ export const doc = {
type: 'block',
exampleFor: 'ChatMessageList',
name: 'ChatMessageList — Density',
- description: 'Side-by-side comparison of compact, balanced, and spacious densities. Use compact in sidebars or panels, balanced for most full-page chat, and spacious for long-form reading.',
+ description: 'Side-by-side comparison of compact, balanced, and spacious densities. Use compact in sidebars or panels, balanced for most full-page chat, and spacious for long-form reading. Use messageGap when row spacing needs to differ from density.',
isReady: true,
aspectRatio: 3 / 4,
componentsUsed: ['Chat', 'ChatMessageList', 'Layout', 'Text', 'Avatar'],
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx
index 1d6b0a6554..d70a690b66 100644
--- a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx
@@ -52,9 +52,9 @@ export default function ChatMessageListDensity() {
<XDSAvatar name="Agent" size={AVATAR_SIZE[density]} />
}>
<XDSChatMessageBubble>
- Density controls spacing at every level — gap between
- messages, padding inside bubbles, and gap between child
- elements.
+ Density provides default spacing at every level — message
+ gap, bubble padding, and gap between child elements. Use
+ messageGap to tune row spacing independently.
</XDSChatMessageBubble>
</XDSChatMessage>
</XDSChatMessageList>
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 273cd22087..5fa0469b0f 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -13,7 +13,10 @@ export const docs = {
{className: 'xds-chat-composer-input'},
{className: 'xds-chat-composer-drawer', visualProps: ['collapsed']},
{className: 'xds-chat-message', visualProps: ['sender']},
- {className: 'xds-chat-message-bubble', visualProps: ['sender', 'variant']},
+ {
+ className: 'xds-chat-message-bubble',
+ visualProps: ['sender', 'variant', 'density'],
+ },
{className: 'xds-chat-message-list', visualProps: ['density']},
{className: 'xds-chat-system-message', visualProps: ['variant']},
{className: 'xds-chat-message-metadata'},
@@ -43,6 +46,7 @@ export const docs = {
},
{name: 'scrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.'},
{name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density — flows to child messages via context.', default: "'balanced'"},
+ {name: 'messageGap', type: 'SpacingStep', description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.'},
],
},
{
@@ -216,6 +220,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
{ guidance: true, description: 'Set the density prop to control spacing globally — compact for sidebars, balanced for most views, spacious for long-form reading. Individual messages can override.' },
+ { guidance: true, description: 'Use messageGap when top-level rows are independent (for example, LLM tool events or streamed blocks) and list spacing needs to be tuned separately from density.' },
{ guidance: true, description: 'Use the group prop on bubbles (first, middle, last) when a single sender sends multiple consecutive messages — it tightens corner radius to visually connect them.' },
{ guidance: true, description: 'Use XDSChatSystemMessage with variant="divider" for date separators and default for inline status notices like joins, leaves, or topic changes.' },
{ guidance: true, description: 'Put name on the first bubble and metadata on the last bubble in a message so they align with the bubble\'s inline padding.' },
@@ -307,6 +312,7 @@ export const docsZh = {
emptyState: '列表无消息时显示的内容。',
scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
density: '视觉密度,通过上下文传递给子消息。',
+ messageGap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
},
},
{
@@ -456,6 +462,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'MessageList > Message > Bubble for sender-aware styling.' },
{ guidance: true, description: 'Density prop controls global spacing — compact for sidebars, balanced default, spacious for reading.' },
+ { guidance: true, description: 'messageGap tunes top-level row spacing separately from density for independent LLM/tool-event rows.' },
{ guidance: true, description: 'Group prop on bubbles (first/middle/last) for consecutive same-sender messages — tightens corner radius.' },
{ guidance: true, description: 'SystemMessage: divider variant for date breaks, default for status notices.' },
{ guidance: true, description: 'Name on first bubble, metadata on last — aligns with bubble inline padding.' },
@@ -478,6 +485,7 @@ export const docsDense = {
emptyState: 'content when no msgs',
scrollToTopAction: 'async action at scroll top; load older msgs',
density: 'visual density; flows to children via context',
+ messageGap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
},
},
{
diff --git a/packages/core/src/Chat/XDSChatMessageBubble.test.tsx b/packages/core/src/Chat/XDSChatMessageBubble.test.tsx
index d4d316662d..6f2b3eeb92 100644
--- a/packages/core/src/Chat/XDSChatMessageBubble.test.tsx
+++ b/packages/core/src/Chat/XDSChatMessageBubble.test.tsx
@@ -4,6 +4,7 @@ import {describe, it, expect} from 'vitest';
import {render, screen} from '@testing-library/react';
import {XDSChatMessage} from './XDSChatMessage';
import {XDSChatMessageBubble} from './XDSChatMessageBubble';
+import {XDSChatMessageList} from './XDSChatMessageList';
import {XDSChatMessageMetadata} from './XDSChatMessageMetadata';
describe('XDSChatMessageBubble', () => {
@@ -36,6 +37,20 @@ describe('XDSChatMessageBubble', () => {
expect(el.className).toContain('assistant');
});
+ it('applies inherited compact density class', () => {
+ render(
+ <XDSChatMessageList density="compact">
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble data-testid="bubble">
+ Compact
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>,
+ );
+ const el = screen.getByTestId('bubble');
+ expect(el.className).toContain('compact');
+ });
+
it('applies data-testid', () => {
render(
<XDSChatMessage sender="assistant">
diff --git a/packages/core/src/Chat/XDSChatMessageBubble.tsx b/packages/core/src/Chat/XDSChatMessageBubble.tsx
index 8b5e1ffa4a..7255b25909 100644
--- a/packages/core/src/Chat/XDSChatMessageBubble.tsx
+++ b/packages/core/src/Chat/XDSChatMessageBubble.tsx
@@ -104,8 +104,8 @@ const styles = stylex.create({
borderRadius: radiusVars['--radius-container'],
},
paddingCompact: {
- paddingBlock: spacingVars['--spacing-2'],
- paddingInline: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-4'],
},
paddingBalanced: {
paddingBlock: spacingVars['--spacing-3'],
@@ -120,7 +120,7 @@ const styles = stylex.create({
},
// Slot padding — matches bubble's paddingInline per density
metadataPaddingCompact: {
- paddingInline: spacingVars['--spacing-3'],
+ paddingInline: spacingVars['--spacing-4'],
},
metadataPaddingBalanced: {
paddingInline: spacingVars['--spacing-4'],
@@ -273,7 +273,7 @@ export function XDSChatMessageBubble({
ref={ref}
data-testid={testId}
{...mergeProps(
- xdsClassName('chat-message-bubble', {sender, variant}),
+ xdsClassName('chat-message-bubble', {sender, variant, density}),
stylex.props(
styles.content,
density === 'compact' && styles.radiusCompact,
diff --git a/packages/core/src/Chat/XDSChatMessageList.test.tsx b/packages/core/src/Chat/XDSChatMessageList.test.tsx
index 602e9b5099..0936e2edf0 100644
--- a/packages/core/src/Chat/XDSChatMessageList.test.tsx
+++ b/packages/core/src/Chat/XDSChatMessageList.test.tsx
@@ -47,6 +47,16 @@ describe('XDSChatMessageList', () => {
expect(el.className).toContain('compact');
});
+ it('accepts messageGap independently from density', () => {
+ render(
+ <XDSChatMessageList density="compact" messageGap={6} 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">
@@ -55,5 +65,4 @@ describe('XDSChatMessageList', () => {
);
expect(screen.getByTestId('chat-list')).toBeTruthy();
});
-
});
diff --git a/packages/core/src/Chat/XDSChatMessageList.tsx b/packages/core/src/Chat/XDSChatMessageList.tsx
index e5ec2ffa8f..f1eedf350e 100644
--- a/packages/core/src/Chat/XDSChatMessageList.tsx
+++ b/packages/core/src/Chat/XDSChatMessageList.tsx
@@ -4,13 +4,13 @@
/**
* @file XDSChatMessageList.tsx
- * @input Uses React, StyleX, XDSChatListContext, theme tokens
+ * @input Uses React, StyleX, XDSChatListContext, theme tokens, spacing step utilities
* @output Exports XDSChatMessageList component and XDSChatMessageListProps
* @position Presentational message container — holds XDSChatMessage children
*
* Renders a container with role="log" for chat message histories.
- * Handles density context, empty state, a spacer that pushes messages
- * to the bottom, and an infinite scroll sentinel.
+ * Handles density context, configurable message gap, empty state,
+ * a spacer that pushes messages to the bottom, and an infinite scroll sentinel.
*
* Auto-scroll and the scroll-to-bottom button are owned by
* XDSChatLayout. When used standalone (without a layout), the list
@@ -33,6 +33,7 @@ import {
import {xdsClassName, mergeProps} from '../utils';
import {XDSSpinner} from '../Spinner';
import type {XDSBaseProps} from '../XDSBaseProps';
+import type {SpacingStep} from '../utils/types';
export interface XDSChatMessageListProps extends XDSBaseProps<HTMLDivElement> {
/** Ref forwarded to the root element */
@@ -62,6 +63,14 @@ export interface XDSChatMessageListProps extends XDSBaseProps<HTMLDivElement> {
* @default 'balanced'
*/
density?: XDSChatDensity;
+
+ /**
+ * Gap between top-level message rows, using the spacing scale.
+ * Defaults to the selected density's message gap. Override this when each
+ * row is independent (for example, LLM event streams where messages cannot
+ * be grouped) and row spacing should be tuned separately from density.
+ */
+ messageGap?: SpacingStep;
}
// =============================================================================
@@ -114,6 +123,42 @@ const styles = stylex.create({
},
});
+const messageGapStyles = stylex.create({
+ 0: {
+ gap: spacingVars['--spacing-0'],
+ },
+ 0.5: {
+ gap: spacingVars['--spacing-0-5'],
+ },
+ 1: {
+ gap: spacingVars['--spacing-1'],
+ },
+ 1.5: {
+ gap: spacingVars['--spacing-1-5'],
+ },
+ 2: {
+ gap: spacingVars['--spacing-2'],
+ },
+ 3: {
+ gap: spacingVars['--spacing-3'],
+ },
+ 4: {
+ gap: spacingVars['--spacing-4'],
+ },
+ 5: {
+ gap: spacingVars['--spacing-5'],
+ },
+ 6: {
+ gap: spacingVars['--spacing-6'],
+ },
+ 8: {
+ gap: spacingVars['--spacing-8'],
+ },
+ 10: {
+ gap: spacingVars['--spacing-10'],
+ },
+});
+
// =============================================================================
// Component
// =============================================================================
@@ -122,6 +167,7 @@ const styles = stylex.create({
* Presentational container for chat messages.
*
* Renders messages in a flex column with density-based spacing.
+ * Override messageGap to tune row spacing separately from density.
* A spacer pushes content to the bottom when the list isn't full.
* Supports loading older messages via `scrollToTopAction`.
*
@@ -142,6 +188,7 @@ export function XDSChatMessageList({
emptyState,
scrollToTopAction,
density = 'balanced',
+ messageGap,
xstyle,
className,
style,
@@ -196,6 +243,8 @@ export function XDSChatMessageList({
: density === 'spacious'
? styles.gapSpacious
: styles.gapBalanced;
+ const messageGapStyle =
+ messageGap == null ? null : messageGapStyles[messageGap];
return (
<XDSChatListContext value={contextValue}>
@@ -211,7 +260,9 @@ export function XDSChatMessageList({
className,
style,
)}>
- <div ref={innerRef} {...stylex.props(styles.inner, gapStyle)}>
+ <div
+ ref={innerRef}
+ {...stylex.props(styles.inner, gapStyle, messageGapStyle)}>
{/* Sentinel for infinite scroll */}
{scrollToTopAction && <div ref={sentinelRef} aria-hidden />}