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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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.tsxindex 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)}><XDSChatLayoutcomposer={- <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.tsxindex 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}><XDSChatLayoutcomposer={<XDSChatComposeronSubmit={() => {}}- 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.mjsindex 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: [