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.tsxindex 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 = {<XDSChatMessageBubblemetadata={<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** — theyAvoid 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/><XDSButtonlabel="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<XDSChatMessageBubblemetadata={<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><XDSCodeBlockcode={`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);`}/><XDSButtonlabel="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.mjsindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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 densitymetadataPaddingCompact: {- 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.tsxindex 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.tsxindex 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 />}