Skip to content

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

TypeScript

Improve ChatLayout docs page and block examples (#1860)

Kenton Quatman48bffbb19db5
diff --git a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutEmptyStateChat.doc.mjs b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutEmptyStateChat.doc.mjs
deleted file mode 100644
index 7a6e56c6e7..0000000000
--- a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutEmptyStateChat.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ChatLayout — Empty State',
- description:
- 'Chat layout showing an empty state placeholder with a docked composer below.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ChatLayout', 'ChatComposer', 'EmptyState'],
-};
diff --git a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutEmptyStateChat.tsx b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutEmptyStateChat.tsx
deleted file mode 100644
index 1d971d8561..0000000000
--- a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutEmptyStateChat.tsx
+++ /dev/null
@@ -1,26 +0,0 @@
-'use client';
-
-import {XDSChatLayout, XDSChatComposer} from '@xds/core/Chat';
-import {XDSEmptyState} from '@xds/core/EmptyState';
-
-export default function ChatLayoutEmptyStateChat() {
- return (
- <div style={{height: '100vh', display: 'flex', flexDirection: 'column'}}>
- <XDSChatLayout
- composer={
- <XDSChatComposer
- onSubmit={() => {}}
- placeholder="Start a conversation\u2026"
- />
- }
- emptyState={
- <XDSEmptyState
- title="No messages yet"
- description="Start a conversation by typing below."
- />
- }>
- {[]}
- </XDSChatLayout>
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutFullAIChat.doc.mjs b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutFullAIChat.doc.mjs
deleted file mode 100644
index e74cc60f96..0000000000
--- a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutFullAIChat.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'ChatLayout — Full AI Chat',
- description:
- 'Full-page AI chat layout with message list, tool call results, code blocks, and a docked composer.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['ChatLayout', 'Chat', 'ChatComposer', 'ChatToolCalls', 'Markdown', 'CodeBlock', 'Timestamp', 'Button'],
-};
diff --git a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutFullAIChat.tsx b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutFullAIChat.tsx
deleted file mode 100644
index 34230519fc..0000000000
--- a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutFullAIChat.tsx
+++ /dev/null
@@ -1,122 +0,0 @@
-'use client';
-
-import {
- XDSChatLayout,
- XDSChatMessageList,
- XDSChatMessage,
- XDSChatMessageBubble,
- XDSChatMessageMetadata,
- XDSChatSystemMessage,
- XDSChatComposer,
- XDSChatToolCalls,
-} from '@xds/core/Chat';
-import {XDSMarkdown} from '@xds/core/Markdown';
-import {XDSTimestamp} from '@xds/core/Timestamp';
-import {XDSButton} from '@xds/core/Button';
-import {XDSCodeBlock} from '@xds/core/CodeBlock';
-
-export default function ChatLayoutFullAIChat() {
- return (
- <div style={{height: '100vh', display: 'flex', flexDirection: 'column'}}>
- <XDSChatLayout
- composer={
- <XDSChatComposer
- onSubmit={() => {}}
- placeholder="Ask about the codebase..."
- footerActions={
- <XDSButton label="Claude Opus" variant="ghost" size="md" />
- }
- />
- }>
- <XDSChatMessageList>
- <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
-
- <XDSChatMessage sender="user">
- <XDSChatMessageBubble
- metadata={
- <XDSChatMessageMetadata
- timestamp={
- <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
- }
- status="read"
- />
- }>
- Can you review the Button component and fix the focus ring?
- </XDSChatMessageBubble>
- </XDSChatMessage>
-
- <XDSChatMessage sender="assistant">
- <XDSMarkdown density="compact">
- I'll read the Button component and check the focus styles.
- </XDSMarkdown>
- <XDSChatToolCalls
- calls={[
- {
- key: '1',
- name: 'read',
- target: 'XDSButton.tsx',
- status: 'complete',
- duration: '45ms',
- node: 'xds',
- },
- {
- key: '2',
- name: 'edit',
- target: 'XDSButton.tsx',
- status: 'complete',
- duration: '120ms',
- node: 'xds',
- additions: 8,
- deletions: 2,
- resultDetail: (
- <XDSCodeBlock
- code={`:focus-visible {\n outline: 2px solid var(--color-ring-focus);\n outline-offset: 2px;\n}`}
- language="css"
- />
- ),
- },
- {
- key: '3',
- name: 'bash',
- target: 'yarn test',
- status: 'complete',
- duration: '6.1s',
- node: 'xds',
- resultDetail: (
- <XDSCodeBlock
- code={`$ yarn test\n✓ 24 tests passed (3 suites)`}
- language="bash"
- />
- ),
- },
- ]}
- />
- <XDSMarkdown density="compact">{`Added a \`:focus-visible\` style with a 2px solid outline and 2px offset. All 24 Button tests pass.
-
-The focus ring meets **WCAG 2.4.7** requirements and uses the theme's focus color token.`}</XDSMarkdown>
- <XDSChatMessageMetadata
- timestamp={
- <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
- }
- footer={<span>Claude Opus 4.6</span>}
- />
- </XDSChatMessage>
-
- <XDSChatMessage sender="user">
- <XDSChatMessageBubble
- metadata={
- <XDSChatMessageMetadata
- timestamp={
- <XDSTimestamp value="2026-03-15T14:35:00" format="time" />
- }
- status="read"
- />
- }>
- Nice, can you also check the Card component?
- </XDSChatMessageBubble>
- </XDSChatMessage>
- </XDSChatMessageList>
- </XDSChatLayout>
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.doc.mjs b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.doc.mjs
index 25c848e858..e071dc50ea 100644
--- a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'ChatLayout — Panel View',
- description:
- 'Narrow sidebar chat layout in a constrained container, suitable for side panels.',
+ description: 'Narrow sidebar chat in a constrained container that triggers compact density. Use for side panels, drawers, or embedded chat widgets where horizontal space is limited.',
isReady: true,
- aspectRatio: 3 / 4,
- componentsUsed: ['ChatLayout', 'Chat', 'ChatComposer', 'Markdown'],
+ aspectRatio: 1,
+ componentsUsed: ['Chat', 'Markdown'],
};
diff --git a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.tsx b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.tsx
index 5de817228d..59d353855d 100644
--- a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.tsx
+++ b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutPanelChat.tsx
@@ -9,23 +9,24 @@ import {
XDSChatComposer,
} from '@xds/core/Chat';
import {XDSMarkdown} from '@xds/core/Markdown';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ panel: {
+ width: 450,
+ height: 600,
+ borderRadius: 8,
+ overflow: 'hidden',
+ border: '1px solid var(--color-border)',
+ },
+});
export default function ChatLayoutPanelChat() {
return (
- <div
- style={{
- width: 400,
- height: 600,
- border: '1px solid #ccc',
- borderRadius: 8,
- overflow: 'hidden',
- }}>
+ <div {...stylex.props(styles.panel)}>
<XDSChatLayout
composer={
- <XDSChatComposer
- onSubmit={() => {}}
- placeholder="Ask something..."
- />
+ <XDSChatComposer onSubmit={() => {}} placeholder="Ask something..." />
}>
<XDSChatMessageList>
<XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
diff --git a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutShowcase.tsx b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutShowcase.tsx
index f165dbeb67..51f974294a 100644
--- a/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ChatLayout/ChatLayoutShowcase.tsx
@@ -6,33 +6,38 @@ import {
XDSChatMessage,
XDSChatMessageBubble,
XDSChatComposer,
+ XDSChatTokenizedText,
} from '@xds/core/Chat';
-import {XDSMarkdown} from '@xds/core/Markdown';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSVStack} from '@xds/core/Stack';
+
+const TOKENS = [{value: '/review', label: '/review', variant: 'blue' as const}];
export default function ChatLayoutShowcase() {
return (
- <div style={{height: 500, display: 'flex', flexDirection: 'column'}}>
+ <XDSVStack width={450}>
<XDSChatLayout
composer={
<XDSChatComposer
onSubmit={() => {}}
- placeholder="Ask about the codebase..."
+ placeholder="Ask something..."
/>
}>
<XDSChatMessageList>
<XDSChatMessage sender="user">
<XDSChatMessageBubble>
- Can you review the Button component?
+ <XDSChatTokenizedText tokens={TOKENS}>
+ /review the changes in this file
+ </XDSChatTokenizedText>
</XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="assistant">
- <XDSMarkdown density="compact">{`The Button component looks solid. A few suggestions:
-
-- Use the **theme token** for border-radius instead of a hardcoded value
-- The focus ring meets **WCAG 2.4.7** requirements`}</XDSMarkdown>
+ <XDSChatMessageBubble variant="ghost">
+ Reading the file now...
+ </XDSChatMessageBubble>
</XDSChatMessage>
</XDSChatMessageList>
</XDSChatLayout>
- </div>
+ </XDSVStack>
);
}
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 54e33e3409..0efa5f061a 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -206,8 +206,17 @@ export const docs = {
{ guidance: true, description: 'Use XDSToken with `onRemove` inside XDSChatComposerDrawer so users can remove attachments individually.' },
{ guidance: false, description: 'Don\'t omit `count` on XDSChatComposerDrawer when there are many items — without it the drawer can\'t collapse and may push the input out of view.' },
{ guidance: false, description: 'Don\'t render XDSChatComposerDrawer outside of XDSChatComposer\'s `drawer` slot — it relies on the composer for border radius and spacing context.' },
+ { guidance: true, description: 'Provide an emptyState prop with an XDSEmptyState so new users see a clear prompt to start a conversation.' },
+ { guidance: true, description: 'Pass a scrollRef when embedding the chat inside a page that already has its own scroll container, so auto-scroll targets the correct element.' },
+ { guidance: false, description: 'Don\'t build your own scroll-to-bottom logic or density breakpoints — XDSChatLayout handles both via container width observation and spring-based auto-scroll.' },
+ { guidance: false, description: 'Don\'t apply a fixed height directly on XDSChatLayout — wrap it in a sized container and let the layout fill with flex: 1.' },
],
anatomy: [
+ { name: 'Message area', required: true, description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.' },
+ { name: 'Frosted glass dock', required: true, description: 'Sticky or fixed container at the bottom with a backdrop-blur layer. Houses the scroll button and composer.' },
+ { name: 'Scroll-to-bottom button', required: false, description: 'Appears when the user scrolls up or new messages arrive. Defaults to XDSChatLayoutScrollButton; pass null to hide or a custom element to override.' },
+ { name: 'Composer', required: true, description: 'The input area for sending messages, typically XDSChatComposer. Docked at the bottom inside the frosted glass layer.' },
+ { name: 'Empty state', required: false, description: 'Centered placeholder shown when no messages exist. Use XDSEmptyState for a consistent look.' },
{ name: 'Avatar', required: false, description: 'A sender avatar rendered beside the message. Typically XDSAvatar with size="small". Hidden for system messages.' },
{ name: 'Name', required: false, description: 'Sender name above the message body. Place on the bubble when using bubbles, or on the message wrapper for raw content.' },
{ name: 'Content', required: true, description: 'The message body — one or more XDSChatMessageBubble elements, or any free-form ReactNode like images or tool calls.' },
@@ -272,7 +281,18 @@ export const docsZh = {
{ guidance: true, description: 'Use XDSToken with `onRemove` inside XDSChatComposerDrawer so users can remove attachments individually.' },
{ guidance: false, description: 'Don\'t omit `count` on XDSChatComposerDrawer when there are many items — without it the drawer can\'t collapse and may push the input out of view.' },
{ guidance: false, description: 'Don\'t render XDSChatComposerDrawer outside of XDSChatComposer\'s `drawer` slot — it relies on the composer for border radius and spacing context.' },
+ { guidance: true, description: 'Provide an emptyState prop with an XDSEmptyState so new users see a clear prompt to start a conversation.' },
+ { guidance: true, description: 'Pass a scrollRef when embedding the chat inside a page that already has its own scroll container, so auto-scroll targets the correct element.' },
+ { guidance: false, description: 'Don\'t build your own scroll-to-bottom logic or density breakpoints — XDSChatLayout handles both via container width observation and spring-based auto-scroll.' },
+ { guidance: false, description: 'Don\'t apply a fixed height directly on XDSChatLayout — wrap it in a sized container and let the layout fill with flex: 1.' },
],
+ anatomy: [
+ { name: 'Message area', required: true, description: 'Scrollable region for messages. Renders children (typically XDSChatMessageList) in a flex column that pushes content to the bottom when the list is short.' },
+ { name: 'Frosted glass dock', required: true, description: 'Sticky or fixed container at the bottom with a backdrop-blur layer. Houses the scroll button and composer.' },
+ { name: 'Scroll-to-bottom button', required: false, description: 'Appears when the user scrolls up or new messages arrive. Defaults to XDSChatLayoutScrollButton; pass null to hide or a custom element to override.' },
+ { name: 'Composer', required: true, description: 'The input area for sending messages, typically XDSChatComposer. Docked at the bottom inside the frosted glass layer.' },
+ { name: 'Empty state', required: false, description: 'Centered placeholder shown when no messages exist. Use XDSEmptyState for a consistent look.' },
+ ],
},
components: [
{
@@ -454,6 +474,10 @@ export const docsDense = {
{ guidance: true, description: 'Use XDSToken with `onRemove` inside XDSChatComposerDrawer for individually removable attachments.' },
{ guidance: false, description: 'Don\'t omit `count` on XDSChatComposerDrawer when there are many items — drawer can\'t collapse without it.' },
{ guidance: false, description: 'Don\'t render XDSChatComposerDrawer outside of XDSChatComposer\'s `drawer` slot.' },
+ { guidance: true, description: 'Provide emptyState prop (XDSEmptyState) for empty conversations.' },
+ { guidance: true, description: 'Pass scrollRef when the chat is inside a parent scroll container.' },
+ { guidance: false, description: 'Custom scroll-to-bottom or density breakpoints — layout handles both.' },
+ { guidance: false, description: 'Fixed height on XDSChatLayout directly — wrap in a sized container, let flex: 1 fill.' },
],
},
components: [