Skip to content

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

TypeScript

Improve ChatMessageList docs page and block examples (#1885)

Kenton Quatman6e30fcfd11c6
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
new file mode 100644
index 0000000000..43b7a240ca
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ 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.',
+ 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
new file mode 100644
index 0000000000..b5998bb4d3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx
@@ -0,0 +1,58 @@
+'use client';
+
+import {
+ XDSChatMessageList,
+ XDSChatMessage,
+ XDSChatMessageBubble,
+} from '@xds/core/Chat';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSAvatar} from '@xds/core/Avatar';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ section: {
+ flex: 1,
+ minHeight: 0,
+ },
+});
+
+const DENSITIES = ['compact', 'balanced', 'spacious'] as const;
+
+const AVATAR_SIZE = {
+ compact: 'xsmall' as const,
+ balanced: 'small' as const,
+ spacious: 'small' as const,
+};
+
+export default function ChatMessageListDensity() {
+ return (
+ <XDSVStack gap={4}>
+ {DENSITIES.map(density => (
+ <XDSVStack key={density} gap={2}>
+ <XDSText type="supporting" color="secondary">
+ {density.charAt(0).toUpperCase() + density.slice(1)}
+ </XDSText>
+ <XDSVStack xstyle={styles.section}>
+ <XDSChatMessageList density={density}>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>
+ How does density work?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<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.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </XDSVStack>
+ </XDSVStack>
+ ))}
+ </XDSVStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListFullFeatured.doc.mjs b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListFullFeatured.doc.mjs
new file mode 100644
index 0000000000..caffff080b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListFullFeatured.doc.mjs
@@ -0,0 +1,9 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatMessageList — Full Featured',
+ description: 'Conversation showcasing system messages, multi-bubble grouping, markdown, code blocks, and metadata. Combines date dividers, ghost bubbles, grouped messages, and rich content in a single example.',
+ isReady: true,
+ aspectRatio: 3 / 4,
+ componentsUsed: ['Chat', 'ChatMessageList', 'Layout', 'Markdown', 'CodeBlock', 'Avatar', 'Timestamp', 'Token'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListFullFeatured.tsx b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListFullFeatured.tsx
new file mode 100644
index 0000000000..5922012c2f
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListFullFeatured.tsx
@@ -0,0 +1,102 @@
+'use client';
+
+import {
+ XDSChatMessageList,
+ XDSChatMessage,
+ XDSChatMessageBubble,
+ XDSChatMessageMetadata,
+ XDSChatSystemMessage,
+} from '@xds/core/Chat';
+import {XDSVStack, XDSHStack} from '@xds/core/Layout';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSMarkdown} from '@xds/core/Markdown';
+import {XDSCodeBlock} from '@xds/core/CodeBlock';
+import {XDSTimestamp} from '@xds/core/Timestamp';
+import {XDSToken} from '@xds/core/Token';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ container: {
+ maxWidth: 600,
+ justifyContent: 'center',
+ },
+});
+
+export default function ChatMessageListFullFeatured() {
+ return (
+ <XDSVStack xstyle={styles.container}>
+ <XDSChatMessageList>
+ <XDSChatSystemMessage variant="divider">Today</XDSChatSystemMessage>
+
+ <XDSChatMessage sender="user">
+ <XDSHStack gap={2} wrap="wrap">
+ <XDSToken label="useReducer.ts" />
+ <XDSToken label="formState.ts" />
+ </XDSHStack>
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
+ }
+ status="read"
+ />
+ }>
+ Can you review these files?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Agent" size="small" />}>
+ <XDSChatMessageBubble group="first">
+ <XDSMarkdown density="compact">
+ {`Sure! Here's the key pattern from **useReducer.ts**:`}
+ </XDSMarkdown>
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble variant="ghost" group="middle">
+ <XDSCodeBlock
+ code={`const [state, dispatch] = useReducer(
+ (state, action) => ({
+ ...state,
+ [action.field]: action.value,
+ }),
+ { name: '', email: '' }
+);`}
+ language="tsx"
+ />
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble
+ group="last"
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:30" format="time" />
+ }
+ />
+ }>
+ <XDSMarkdown density="compact">
+ {`The reducer is **pure and easy to test** — pass in state and action, assert on the output.`}
+ </XDSMarkdown>
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatSystemMessage>Agent shared a code snippet</XDSChatSystemMessage>
+
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
+ status="delivered"
+ />
+ }>
+ That's clean, thanks!
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </XDSVStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.doc.mjs
index 7639c5f0ca..1c4c38ef3c 100644
--- a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.doc.mjs
@@ -2,9 +2,9 @@
export const doc = {
type: 'block',
name: 'ChatMessageList',
- description: 'Scrollable message list with density context and system message dividers.',
+ description: 'Basic AI chat conversation with user and assistant messages. The simplest way to render a message list with alternating sender bubbles, metadata, and a date divider.',
isReady: true,
isShowcase: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Chat', 'ChatMessageList'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatMessageList', 'Layout', 'Timestamp'],
};
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.tsx b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.tsx
index 75147b6bf5..44210c9f03 100644
--- a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.tsx
@@ -4,14 +4,17 @@ import {
XDSChatMessageList,
XDSChatMessage,
XDSChatMessageBubble,
+ XDSChatMessageMetadata,
XDSChatSystemMessage,
} from '@xds/core/Chat';
import {XDSVStack} from '@xds/core/Layout';
+import {XDSTimestamp} from '@xds/core/Timestamp';
import * as stylex from '@stylexjs/stylex';
const styles = stylex.create({
container: {
- height: 400,
+ maxWidth: 600,
+ height: '100%',
},
});
@@ -24,28 +27,44 @@ export default function ChatMessageListShowcase() {
</XDSChatSystemMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>
- What's the best way to structure a monorepo?
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
+ }
+ status="read"
+ />
+ }>
+ How should I structure a monorepo?
</XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="assistant">
- <XDSChatMessageBubble>
- I'd recommend using workspaces with a shared packages directory.
- Keep each package focused on a single concern.
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:15" format="time" />
+ }
+ />
+ }>
+ Use workspaces with a shared packages directory. Keep each package
+ focused on a single concern.
</XDSChatMessageBubble>
</XDSChatMessage>
<XDSChatMessage sender="user">
- <XDSChatMessageBubble>
- Should I use Yarn or pnpm workspaces?
- </XDSChatMessageBubble>
- </XDSChatMessage>
-
- <XDSChatMessage sender="assistant">
- <XDSChatMessageBubble>
- Both work well. Yarn is more mature, pnpm is faster with better
- disk efficiency. Pick whichever your team is comfortable with.
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
+ status="delivered"
+ />
+ }>
+ Should I use Yarn or pnpm for that?
</XDSChatMessageBubble>
</XDSChatMessage>
</XDSChatMessageList>
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 314a1fe802..c2f7bb14ed 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -178,43 +178,21 @@ export const docs = {
},
],
usage: {
- description: 'Chat components provide layout primitives and a message composer for building AI chat interfaces. XDSChatComposer is the input shell — compose it using named slots (drawer, headerActions, footerActions, sendActions) to assemble features like file attachments, model selectors, and context indicators without building custom layout. Use XDSChatComposerInput inside XDSChatComposer for rich text entry with trigger menus, inline tokens, and message history.',
+ description: 'XDSChatMessageList is the scrollable container for chat messages. It renders children in a flex column with role="log" for accessibility, provides density context to child messages, and supports infinite scroll for loading older messages. Use it inside XDSChatLayout for full-page chat with auto-scroll and composer docking, or standalone for embedded message panels.',
bestPractices: [
{ guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
- { guidance: true, description: 'Use the named slots on XDSChatComposer (drawer, headerActions, footerActions, sendActions) to keep the input layout structured. Each slot has a specific position and purpose.' },
- { guidance: true, description: 'Show the streaming state with isStreaming and provide an onStop handler so users can cancel long-running responses.' },
- { 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. Use the message wrapper\'s name/metadata props when the content is raw (no bubble).' },
- { guidance: true, description: 'Use XDSChatComposerTokenElement to display token chips outside the contentEditable \u2014 in message previews, read-only views, or anywhere tokens need to render without the full composer.' },
- { guidance: true, description: 'Prefer the badge config form ({ value, label, variant }) for XDSChatComposerTokenElement tokens. Reserve the custom render escape hatch for rich content like avatar initials or interactive elements.' },
- { guidance: true, description: 'Use XDSChatLayout for full-page chat — it handles auto-scroll, density adaptation, and composer docking automatically.' },
- { guidance: true, description: 'Use XDSChatSystemMessage with variant="divider" for date separators and default for status notices like joins, leaves, or topic changes.' },
- { guidance: true, description: 'Add an icon to system messages when the type is not obvious from the text alone — membership changes, encryption notices, or AI activity benefit from visual reinforcement.' },
+ { 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 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 the ghost bubble variant for AI-style responses that need alignment without a visual boundary.' },
- { guidance: false, description: 'Don\'t build custom input containers or composer chrome — XDSChatComposer handles the border radius, shadows, focus ring, and slot layout. Customise through slots, not wrapping.' },
- { guidance: false, description: 'Don\'t place metadata or names on both the bubble and the message wrapper — pick one based on whether the content has a bubble boundary.' },
- { guidance: false, description: 'Don\'t use the status prop for transient success messages — it\'s for errors and warnings that need the user\'s attention before they send another message.' },
+ { 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.' },
+ { guidance: true, description: 'Provide an emptyState prop so new users see a clear prompt to start a conversation instead of a blank screen.' },
+ { guidance: true, description: 'Use the ghost bubble variant for AI-style responses that show rich content like code blocks or markdown without a visible boundary.' },
{ guidance: false, description: 'Don\'t use XDSChatSystemMessage for sender content — it has no avatar, alignment, or bubble. Use XDSChatMessage with a sender role instead.' },
{ guidance: false, description: 'Don\'t put long or multi-line content in a system message — keep it to a single short sentence. If you need more, use a bubble or a card.' },
{ guidance: false, description: 'Don\'t nest XDSChatMessage inside another XDSChatMessage — each message is a standalone article element with its own sender context.' },
- { guidance: true, description: 'Pass XDSChatComposerInput to the composer\'s input slot when you need trigger menus, inline tokens, or file paste handling \u2014 the default textarea does not support these.' },
- { guidance: true, description: 'Give each trigger character a distinct token color (e.g. blue for @mentions, yellow for /commands) so users can distinguish trigger types at a glance.' },
- { guidance: false, description: 'Don\'t build a custom contenteditable input for mentions or commands \u2014 XDSChatComposerInput handles cursor management, serialization, and token rendering.' },
-
+ { guidance: false, description: 'Don\'t apply a fixed height directly on the message list — wrap it in a sized container and let the list fill with flex: 1.' },
{ guidance: false, description: 'Don\'t mix filled and ghost bubble variants within the same sender\'s messages — pick one style per side and use it consistently.' },
- { guidance: true, description: 'Provide a `count` on XDSChatComposerDrawer that matches the number of children, and set a descriptive `label` like "Attachments" instead of the default "Items".' },
- { 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.' },
- { guidance: true, description: 'Show a label on XDSChatLayoutScrollButton (e.g. "New messages") when unread content arrives below the fold so the user knows there is something to see.' },
- { guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button from scratch — use XDSChatLayoutScrollButton or pass a custom element to XDSChatLayout\'s scrollButton prop.' },
- { guidance: true, description: 'Let XDSChatSendButton read state from XDSChatComposerContext by default — it handles disabled, send, and stop states automatically. Only override via props when using the button standalone or replacing the default icon.' },
- { guidance: false, description: 'Don\'t manually wire isDisabled on XDSChatSendButton inside a composer — the context already tracks whether the input has content. Override only for custom validation logic.' },
- { guidance: false, description: 'Don\'t use XDSChatSendButton for non-chat submit actions — use XDSButton instead. The send button is purpose-built for the chat composer flow.' },
+ { guidance: false, description: 'Don\'t place metadata or names on both the bubble and the message wrapper — pick one based on whether the content has a bubble boundary.' },
],
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.' },
@@ -258,44 +236,22 @@ docs.components.push(chatLayoutScrollButtonComponent);
/** @type {import('../docs-types').TranslationDoc} */
export const docsZh = {
usage: {
- description: 'Chat components provide layout primitives and a message composer for building AI chat interfaces. XDSChatComposer is the input shell — compose it using named slots (drawer, headerActions, footerActions, sendActions) to assemble features like file attachments, model selectors, and context indicators without building custom layout. Use XDSChatComposerInput inside XDSChatComposer for rich text entry with trigger menus, inline tokens, and message history.',
+ description: 'XDSChatMessageList 是聊天消息的可滚动容器。它以 flex 列的形式渲染子元素,使用 role="log" 确保无障碍性,通过上下文向子消息提供密度设置,并支持无限滚动以加载更早的消息。在 XDSChatLayout 内使用它可获得全页聊天体验(自动滚动和编辑器停靠),也可独立用于嵌入式消息面板。',
bestPractices: [
- { guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
- { guidance: true, description: 'Use the named slots on XDSChatComposer (drawer, headerActions, footerActions, sendActions) to keep the input layout structured. Each slot has a specific position and purpose.' },
- { guidance: true, description: 'Show the streaming state with isStreaming and provide an onStop handler so users can cancel long-running responses.' },
- { 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. Use the message wrapper\'s name/metadata props when the content is raw (no bubble).' },
- { guidance: true, description: 'Use XDSChatComposerTokenElement to display token chips outside the contentEditable \u2014 in message previews, read-only views, or anywhere tokens need to render without the full composer.' },
- { guidance: true, description: 'Prefer the badge config form ({ value, label, variant }) for XDSChatComposerTokenElement tokens. Reserve the custom render escape hatch for rich content like avatar initials or interactive elements.' },
- { guidance: true, description: 'Use XDSChatLayout for full-page chat — it handles auto-scroll, density adaptation, and composer docking automatically.' },
- { guidance: true, description: 'Use XDSChatSystemMessage with variant="divider" for date separators and default for status notices like joins, leaves, or topic changes.' },
- { guidance: true, description: 'Add an icon to system messages when the type is not obvious from the text alone — membership changes, encryption notices, or AI activity benefit from visual reinforcement.' },
- { 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 the ghost bubble variant for AI-style responses that need alignment without a visual boundary.' },
- { guidance: false, description: 'Don\'t build custom input containers or composer chrome — XDSChatComposer handles the border radius, shadows, focus ring, and slot layout. Customise through slots, not wrapping.' },
- { guidance: false, description: 'Don\'t place metadata or names on both the bubble and the message wrapper — pick one based on whether the content has a bubble boundary.' },
- { guidance: false, description: 'Don\'t use the status prop for transient success messages — it\'s for errors and warnings that need the user\'s attention before they send another message.' },
- { guidance: false, description: 'Don\'t use XDSChatSystemMessage for sender content — it has no avatar, alignment, or bubble. Use XDSChatMessage with a sender role instead.' },
- { guidance: false, description: 'Don\'t put long or multi-line content in a system message — keep it to a single short sentence. If you need more, use a bubble or a card.' },
- { guidance: false, description: 'Don\'t nest XDSChatMessage inside another XDSChatMessage — each message is a standalone article element with its own sender context.' },
- { guidance: true, description: 'Pass XDSChatComposerInput to the composer\'s input slot when you need trigger menus, inline tokens, or file paste handling \u2014 the default textarea does not support these.' },
- { guidance: true, description: 'Give each trigger character a distinct token color (e.g. blue for @mentions, yellow for /commands) so users can distinguish trigger types at a glance.' },
- { guidance: false, description: 'Don\'t build a custom contenteditable input for mentions or commands \u2014 XDSChatComposerInput handles cursor management, serialization, and token rendering.' },
-
- { guidance: false, description: 'Don\'t mix filled and ghost bubble variants within the same sender\'s messages — pick one style per side and use it consistently.' },
- { guidance: true, description: 'Provide a `count` on XDSChatComposerDrawer that matches the number of children, and set a descriptive `label` like "Attachments" instead of the default "Items".' },
- { 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.' },
- { guidance: true, description: 'Show a label on XDSChatLayoutScrollButton (e.g. "New messages") when unread content arrives below the fold so the user knows there is something to see.' },
- { guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button from scratch — use XDSChatLayoutScrollButton or pass a custom element to XDSChatLayout\'s scrollButton prop.' },
- { guidance: true, description: 'Let XDSChatSendButton read state from XDSChatComposerContext by default — it handles disabled, send, and stop states automatically. Only override via props when using the button standalone or replacing the default icon.' },
- { guidance: false, description: 'Don\'t manually wire isDisabled on XDSChatSendButton inside a composer — the context already tracks whether the input has content. Override only for custom validation logic.' },
- { guidance: false, description: 'Don\'t use XDSChatSendButton for non-chat submit actions — use XDSButton instead. The send button is purpose-built for the chat composer flow.' },
-],
+ { guidance: true, description: '使用 MessageList > Message > Bubble 组合来获得一致的发送者感知样式和密度。' },
+ { guidance: true, description: '设置 density 属性来全局控制间距 — compact 用于侧边栏,balanced 用于大多数视图,spacious 用于长篇阅读。' },
+ { guidance: true, description: '当同一发送者发送多条连续消息时,使用气泡的 group 属性(first、middle、last)来视觉上连接相关消息。' },
+ { guidance: true, description: '使用 XDSChatSystemMessage 的 variant="divider" 作为日期分隔线,使用 default 作为内联状态通知。' },
+ { guidance: true, description: '将 name 放在第一个气泡上,metadata 放在最后一个气泡上,使其与气泡的内边距对齐。' },
+ { guidance: true, description: '提供 emptyState 属性,让新用户看到开始对话的提示,而不是空白屏幕。' },
+ { guidance: true, description: '使用 ghost 气泡变体显示代码块或 Markdown 等富内容,无需可见边界。' },
+ { guidance: false, description: '不要将 XDSChatSystemMessage 用于发送者内容 — 它没有头像、对齐或气泡。请使用带有发送者角色的 XDSChatMessage。' },
+ { guidance: false, description: '不要在系统消息中放置冗长或多行内容 — 保持一句简短的话。如需更多内容,请使用气泡或卡片。' },
+ { guidance: false, description: '不要将 XDSChatMessage 嵌套在另一个 XDSChatMessage 内 — 每条消息都是独立的 article 元素。' },
+ { guidance: false, description: '不要直接在消息列表上应用固定高度 — 将其包裹在有尺寸的容器中,让列表以 flex: 1 填充。' },
+ { guidance: false, description: '不要在同一发送者的消息中混用 filled 和 ghost 气泡变体 — 每一侧选择一种样式并保持一致。' },
+ { guidance: false, description: '不要同时在气泡和消息包装器上放置 metadata 或 name — 根据内容是否有气泡边界来选择。' },
+ ],
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.' },
@@ -458,41 +414,21 @@ export const docsZh = {
export const docsDense = {
description: 'AI chat components. Layout (MessageList>Message>Bubble+SystemMessage) + Composer (shell w/ slots, ContentEditable input w/ trigger menus, tokens, msg history, attachments)',
usage: {
- description: 'Chat layout primitives + composer for AI chat UIs. Composer is a slot-based shell — drawer, headerActions, footerActions, sendActions. XDSChatComposerInput for trigger menus, inline tokens, and message history.',
+ description: 'XDSChatMessageList: scrollable msg container w/ role="log", density context, infinite scroll. Use inside XDSChatLayout for full-page chat or standalone for embedded panels.',
bestPractices: [
{ guidance: true, description: 'MessageList > Message > Bubble for sender-aware styling.' },
- { guidance: true, description: 'Named slots on Composer (drawer, headerActions, footerActions, sendActions) — each has a specific position.' },
- { guidance: true, description: 'isStreaming + onStop for cancelable long-running responses.' },
- { guidance: true, description: 'Name on first bubble, metadata on last — aligns with bubble inline padding. Message wrapper props for raw content.' },
- { guidance: true, description: 'XDSChatLayout for full-page — auto-scroll, density adaptation, composer docking.' },
- { guidance: true, description: 'Group prop (first/middle/last) on consecutive bubbles for continuous visual flow.' },
- { guidance: true, description: 'SystemMessage: divider variant for date breaks, default for status notices. Add icon for membership/encryption/AI messages.' },
+ { guidance: true, description: 'Density prop controls global spacing — compact for sidebars, balanced default, spacious for reading.' },
{ guidance: true, description: 'Group prop on bubbles (first/middle/last) for consecutive same-sender messages — tightens corner radius.' },
- { guidance: true, description: 'Ghost bubble variant for AI-style responses without a visual boundary.' },
- { guidance: false, description: 'Custom composer chrome — Composer handles radius, shadows, focus ring. Use slots.' },
- { guidance: false, description: 'Metadata/names on both bubble and wrapper — pick one.' },
- { guidance: false, description: 'Status for success toasts — it\'s for errors/warnings before next send.' },
+ { 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.' },
+ { guidance: true, description: 'Provide emptyState so new users see a prompt, not a blank screen.' },
+ { guidance: true, description: 'Ghost bubble variant for rich AI content like code/markdown without visible boundary.' },
{ guidance: false, description: 'SystemMessage for sender content — no avatar/alignment/bubble. Use ChatMessage instead.' },
{ guidance: false, description: 'Long/multi-line system messages — keep to a single short sentence.' },
- { guidance: true, description: 'XDSChatComposerInput in input slot for trigger menus, tokens, file paste.' },
- { guidance: true, description: 'Distinct token colors per trigger type \u2014 blue @mentions, yellow /commands.' },
- { guidance: false, description: 'Custom contenteditable for mentions/commands \u2014 XDSChatComposerInput handles it.' },
{ guidance: false, description: 'Nesting XDSChatMessage inside another — each is a standalone article.' },
-
+ { guidance: false, description: 'Fixed height on message list directly — wrap in a sized container, let flex: 1 fill.' },
{ guidance: false, description: 'Mix filled and ghost variants in same sender\'s messages — pick one style per side.' },
- { guidance: true, description: 'Match `count` to children on XDSChatComposerDrawer; set a descriptive `label` like "Attachments".' },
- { 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.' },
- { guidance: true, description: 'Show a label on XDSChatLayoutScrollButton when unread content arrives below the fold.' },
- { guidance: false, description: 'Don\'t rebuild the scroll-to-bottom button — use XDSChatLayoutScrollButton or pass a custom element to scrollButton.' },
- { guidance: true, description: 'Let ChatSendButton read context by default. Override only for standalone use or custom icons.' },
- { guidance: false, description: 'Don\'t manually wire isDisabled on ChatSendButton inside a composer — context already tracks it.' },
- { guidance: false, description: 'Don\'t use ChatSendButton for non-chat actions — use XDSButton instead.' },
+ { guidance: false, description: 'Metadata/names on both bubble and wrapper — pick one.' },
],
},
components: [