Skip to content

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

TypeScript

feat(templates): add showcase blocks for chat, command palette, and misc sub-components (#1742)

Cindy Zhangef88d08a0afc
diff --git a/packages/cli/templates/blocks/components/Chat/ChatComposerAttachments.doc.mjs b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.doc.mjs
similarity index 59%
rename from packages/cli/templates/blocks/components/Chat/ChatComposerAttachments.doc.mjs
rename to packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.doc.mjs
index 7f0715a9c8..85f0bd028a 100644
--- a/packages/cli/templates/blocks/components/Chat/ChatComposerAttachments.doc.mjs
+++ b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.doc.mjs
@@ -1,8 +1,8 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Chat — Composer Attachments',
- description: 'Composer with removable file tokens and a collapsible attachment drawer. Use a context progress bar to show how much of the context window is used, and the collapse toggle when many files are attached.',
+ name: 'Chat — Composer Drawer',
+ description: 'Composer with removable file tokens and a collapsible drawer. Use a context progress bar to show how much of the context window is used, and the collapse toggle when many files are attached.',
isReady: true,
aspectRatio: 16 / 9,
componentsUsed: ['Chat', 'Token', 'ProgressBar', 'Layout', 'Text'],
diff --git a/packages/cli/templates/blocks/components/Chat/ChatComposerAttachments.tsx b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.tsx
similarity index 96%
rename from packages/cli/templates/blocks/components/Chat/ChatComposerAttachments.tsx
rename to packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.tsx
index f24ec5abcf..ff891bc273 100644
--- a/packages/cli/templates/blocks/components/Chat/ChatComposerAttachments.tsx
+++ b/packages/cli/templates/blocks/components/Chat/ChatComposerDrawer.tsx
@@ -9,7 +9,7 @@ import {XDSButton} from '@xds/core/Button';
import {XDSIcon} from '@xds/core/Icon';
import {PaperClipIcon, AtSymbolIcon} from '@heroicons/react/24/outline';
-export default function ChatComposerAttachments() {
+export default function ChatComposerDrawer() {
return (
<XDSStack direction="vertical" gap={4} width={450}>
<XDSChatComposer
diff --git a/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithAttachments.doc.mjs b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithDrawer.doc.mjs
similarity index 63%
rename from packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithAttachments.doc.mjs
rename to packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithDrawer.doc.mjs
index ec2fad29c7..93e211fffd 100644
--- a/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithAttachments.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithDrawer.doc.mjs
@@ -1,9 +1,9 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'ChatComposer — With Attachments',
+ name: 'ChatComposer — With Drawer',
description:
- 'Chat composer with removable file attachment tokens and a context progress bar.',
+ 'Chat composer with removable file tokens in a drawer and a context progress bar.',
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['ChatComposer', 'Token', 'ProgressBar'],
diff --git a/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithAttachments.tsx b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithDrawer.tsx
similarity index 89%
rename from packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithAttachments.tsx
rename to packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithDrawer.tsx
index 11c59325a9..2e4732c978 100644
--- a/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithAttachments.tsx
+++ b/packages/cli/templates/blocks/components/ChatComposer/ChatComposerComposerWithDrawer.tsx
@@ -4,7 +4,7 @@ import {XDSChatComposer, XDSChatComposerDrawer} from '@xds/core/Chat';
import {XDSToken} from '@xds/core/Token';
import {XDSProgressBar} from '@xds/core/ProgressBar';
-export default function ChatComposerComposerWithAttachments() {
+export default function ChatComposerComposerWithDrawer() {
return (
<XDSChatComposer
onSubmit={() => {}}
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.doc.mjs
new file mode 100644
index 0000000000..971e739696
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatComposerDrawer',
+ description: 'Composer drawer area with file tokens and collapsible overflow.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatComposerDrawer', 'Token'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.tsx b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.tsx
new file mode 100644
index 0000000000..bb1ba8e17b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatComposerDrawer/ChatComposerDrawerShowcase.tsx
@@ -0,0 +1,24 @@
+'use client';
+
+import {
+ XDSChatComposer,
+ XDSChatComposerDrawer,
+} from '@xds/core/Chat';
+import {XDSToken} from '@xds/core/Token';
+
+export default function ChatComposerDrawerShowcase() {
+ return (
+ <XDSChatComposer
+ onSubmit={() => {}}
+ drawer={
+ <XDSChatComposerDrawer count={5}>
+ <XDSToken label="design-spec.pdf" onRemove={() => {}} />
+ <XDSToken label="api-schema.json" onRemove={() => {}} />
+ <XDSToken label="screenshot.png" onRemove={() => {}} />
+ <XDSToken label="meeting-notes.md" onRemove={() => {}} />
+ <XDSToken label="test-results.csv" onRemove={() => {}} />
+ </XDSChatComposerDrawer>
+ }
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjs b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjs
index bc4005b313..e84f5b4846 100644
--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'ChatDictation — In Composer',
- description:
- 'Dictation button placed in the sendActions slot of a chat composer.',
+ description: 'Interactive dictation button placed in the sendActions slot of a chat composer.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['ChatDictation', 'ChatComposer'],
+ componentsUsed: ['Chat', 'ChatDictation', 'ChatComposer', 'ChatComposerInput'],
};
diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsx b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsx
index e34b3ee004..0576d95356 100644
--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsx
+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationInComposer.tsx
@@ -1,33 +1,28 @@
'use client';
+import {useRef} from 'react';
import {
XDSChatDictationButton,
XDSChatComposer,
+ XDSChatComposerInput,
+ useXDSChatDictation,
} from '@xds/core/Chat';
-import type {UseSpeechRecognitionReturn} from '@xds/core/Chat';
+import type {XDSChatComposerInputHandle} from '@xds/core/Chat';
-const noop = () => {};
+export default function ChatDictationDictationInComposer() {
+ const inputRef = useRef<XDSChatComposerInputHandle>(null);
-const idleDictation: UseSpeechRecognitionReturn = {
- volume: 0,
- rawBands: [0, 0, 0, 0, 0],
- bands: [0, 0, 0, 0, 0],
- isSupported: true,
- isListening: false,
- isSpeaking: false,
- interimTranscript: '',
- start: noop,
- stop: noop,
- abort: noop,
- toggle: noop,
-};
+ const dictation = useXDSChatDictation({
+ inputRef,
+ hasSounds: true,
+ });
-export default function ChatDictationDictationInComposer() {
return (
<XDSChatComposer
onSubmit={() => {}}
placeholder="Type or tap the mic to dictate..."
- sendActions={<XDSChatDictationButton dictation={idleDictation} />}
+ input={<XDSChatComposerInput ref={inputRef} />}
+ sendActions={<XDSChatDictationButton dictation={dictation} />}
/>
);
}
diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjs b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjs
index bcd547e1df..d8f4355c0e 100644
--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.doc.mjs
@@ -2,9 +2,8 @@
export const doc = {
type: 'block',
name: 'ChatDictation — States',
- description:
- 'Dictation button in idle, listening, and speaking states side by side.',
+ description: 'Dictation button in idle, listening, and speaking states side by side.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['ChatDictation'],
+ componentsUsed: ['Chat', 'ChatDictation'],
};
diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsx b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsx
index 64bd858f69..6354913801 100644
--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsx
+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationDictationStates.tsx
@@ -2,10 +2,12 @@
import {XDSChatDictationButton} from '@xds/core/Chat';
import type {UseSpeechRecognitionReturn} from '@xds/core/Chat';
+import {XDSHStack, XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
const noop = () => {};
-const idle: UseSpeechRecognitionReturn = {
+const base: UseSpeechRecognitionReturn = {
volume: 0,
rawBands: [0, 0, 0, 0, 0],
bands: [0, 0, 0, 0, 0],
@@ -19,49 +21,41 @@ const idle: UseSpeechRecognitionReturn = {
toggle: noop,
};
+const idle: UseSpeechRecognitionReturn = {...base};
+
const listening: UseSpeechRecognitionReturn = {
+ ...base,
volume: 0.05,
rawBands: [0.08, 0.06, 0.04, 0.02, 0.01],
bands: [0.08, 0.06, 0.04, 0.02, 0.01],
- isSupported: true,
isListening: true,
- isSpeaking: false,
- interimTranscript: '',
- start: noop,
- stop: noop,
- abort: noop,
- toggle: noop,
};
const speaking: UseSpeechRecognitionReturn = {
+ ...base,
volume: 0.12,
rawBands: [0.15, 0.12, 0.08, 0.05, 0.02],
bands: [0.15, 0.12, 0.08, 0.05, 0.02],
- isSupported: true,
isListening: true,
isSpeaking: true,
interimTranscript: 'hello world',
- start: noop,
- stop: noop,
- abort: noop,
- toggle: noop,
};
export default function ChatDictationDictationStates() {
return (
- <div style={{display: 'flex', gap: 24, alignItems: 'center'}}>
- <div style={{display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 8}}>
+ <XDSHStack gap={6} vAlign="center">
+ <XDSVStack gap={2} hAlign="center">
<XDSChatDictationButton dictation={idle} />
- <span style={{fontSize: 12, color: '#888'}}>Idle</span>
- </div>
- <div style={{display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 8}}>
+ <XDSText type="supporting" color="secondary">Idle</XDSText>
+ </XDSVStack>
+ <XDSVStack gap={2} hAlign="center">
<XDSChatDictationButton dictation={listening} />
- <span style={{fontSize: 12, color: '#888'}}>Listening</span>
- </div>
- <div style={{display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 8}}>
+ <XDSText type="supporting" color="secondary">Listening</XDSText>
+ </XDSVStack>
+ <XDSVStack gap={2} hAlign="center">
<XDSChatDictationButton dictation={speaking} />
- <span style={{fontSize: 12, color: '#888'}}>Speaking</span>
- </div>
- </div>
+ <XDSText type="supporting" color="secondary">Speaking</XDSText>
+ </XDSVStack>
+ </XDSHStack>
);
}
diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.doc.mjs
index 1f5de201c9..b9cad52377 100644
--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.doc.mjs
@@ -2,7 +2,9 @@
export const doc = {
type: 'block',
name: 'ChatDictation',
+ description: 'Interactive dictation in a composer — connected to the SpeechRecognition API via useXDSChatDictation.',
isReady: true,
- aspectRatio: 4 / 3,
isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Chat', 'ChatDictation', 'ChatComposer', 'ChatComposerInput'],
};
diff --git a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.tsx b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.tsx
index 1fdcf0590c..a3ca57f1af 100644
--- a/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.tsx
+++ b/packages/cli/templates/blocks/components/ChatDictation/ChatDictationShowcase.tsx
@@ -1,26 +1,30 @@
'use client';
-import {XDSChatDictationButton, XDSChatComposer} from '@xds/core/Chat';
-
-const idleDictation = {
- volume: 0,
- rawBands: [0, 0, 0, 0, 0],
- bands: [0, 0, 0, 0, 0],
- isSupported: true,
- isListening: false,
- isSpeaking: false,
- interimTranscript: '',
- start: () => {},
- stop: () => {},
- abort: () => {},
- toggle: () => {},
-};
+import {useRef} from 'react';
+import {
+ XDSChatDictationButton,
+ XDSChatComposer,
+ XDSChatComposerInput,
+ useXDSChatDictation,
+} from '@xds/core/Chat';
+import type {XDSChatComposerInputHandle} from '@xds/core/Chat';
export default function ChatDictationShowcase() {
+ const inputRef = useRef<XDSChatComposerInputHandle>(null);
+
+ const dictation = useXDSChatDictation({
+ inputRef,
+ hasSounds: true,
+ onResult: (text) => {
+ console.log('Dictation result:', text);
+ },
+ });
+
return (
<XDSChatComposer
- onSubmit={() => {}}
- sendActions={<XDSChatDictationButton dictation={idleDictation} />}
+ onSubmit={(v) => console.log('Submit:', v)}
+ input={<XDSChatComposerInput ref={inputRef} />}
+ sendActions={<XDSChatDictationButton dictation={dictation} />}
/>
);
}
diff --git a/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonShowcase.doc.mjs
new file mode 100644
index 0000000000..c1c1c852c8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatDictationButton',
+ description: 'Interactive dictation button connected to the SpeechRecognition API via useXDSChatDictation. Click the mic to dictate into the composer.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatDictationButton', 'ChatComposer', 'ChatComposerInput'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonShowcase.tsx b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonShowcase.tsx
new file mode 100644
index 0000000000..d8826d66c7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatDictationButton/ChatDictationButtonShowcase.tsx
@@ -0,0 +1,73 @@
+'use client';
+
+import {useRef} from 'react';
+import {
+ XDSChatDictationButton,
+ XDSChatComposer,
+ XDSChatComposerInput,
+ useXDSChatDictation,
+} from '@xds/core/Chat';
+import type {XDSChatComposerInputHandle} from '@xds/core/Chat';
+import {XDSHStack, XDSVStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ChatDictationButtonShowcase() {
+ const inputRef = useRef<XDSChatComposerInputHandle>(null);
+
+ const dictation = useXDSChatDictation({
+ inputRef,
+ hasSounds: true,
+ onResult: (text) => {
+ console.log('Dictation result:', text);
+ },
+ });
+
+ return (
+ <XDSVStack gap={4}>
+ <XDSText type="supporting" color="secondary">
+ Click the microphone to start dictating. Speech is transcribed into the
+ input.
+ </XDSText>
+
+ <XDSChatComposer
+ onSubmit={(v) => console.log('Submit:', v)}
+ input={<XDSChatComposerInput ref={inputRef} />}
+ sendActions={<XDSChatDictationButton dictation={dictation} />}
+ />
+
+ {dictation.isListening && (
+ <XDSHStack gap={2} vAlign="center">
+ <XDSText type="supporting" color="secondary">
+ {dictation.isSpeaking ? 'Speaking detected' : 'Listening...'}
+ </XDSText>
+ <div
+ style={{
+ width: 80,
+ height: 6,
+ backgroundColor: 'var(--color-surface-secondary)',
+ borderRadius: 3,
+ overflow: 'hidden',
+ }}>
+ <div
+ style={{
+ height: '100%',
+ backgroundColor: dictation.isSpeaking
+ ? 'var(--color-accent)'
+ : 'var(--color-text-secondary)',
+ borderRadius: 3,
+ transition: 'width 0.08s ease-out',
+ width: `${Math.min(dictation.volume * 200, 100)}%`,
+ }}
+ />
+ </div>
+ </XDSHStack>
+ )}
+
+ {!dictation.isSupported && (
+ <XDSText type="supporting" color="active">
+ SpeechRecognition is not supported in this browser.
+ </XDSText>
+ )}
+ </XDSVStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatMessage/ChatMessageShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatMessage/ChatMessageShowcase.doc.mjs
new file mode 100644
index 0000000000..cfbf35fee7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessage/ChatMessageShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatMessage',
+ description: 'Chat messages demonstrating full prop variance: avatar, name, timestamp, metadata with action buttons, multi-bubble groups, delivery status, ghost variant (without visible bubbles), and system messages.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Chat', 'ChatMessage', 'ChatMessageBubble', 'ChatMessageMetadata', 'ChatSystemMessage', 'Avatar', 'Timestamp', 'Button', 'Icon', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatMessage/ChatMessageShowcase.tsx b/packages/cli/templates/blocks/components/ChatMessage/ChatMessageShowcase.tsx
new file mode 100644
index 0000000000..16903a55fd
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessage/ChatMessageShowcase.tsx
@@ -0,0 +1,124 @@
+'use client';
+
+import {
+ XDSChatMessageList,
+ XDSChatMessage,
+ XDSChatMessageBubble,
+ XDSChatMessageMetadata,
+ XDSChatSystemMessage,
+} from '@xds/core/Chat';
+import {XDSAvatar} from '@xds/core/Avatar';
+import {XDSText} from '@xds/core/Text';
+import {XDSTimestamp} from '@xds/core/Timestamp';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSHStack, XDSVStack} from '@xds/core/Layout';
+
+export default function ChatMessageShowcase() {
+ return (
+ <XDSVStack gap={4}>
+ <XDSText type="supporting" color="secondary">
+ With message bubbles
+ </XDSText>
+ <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 my pull request?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ {/* Full props: avatar, name, bubble, multi-bubble group, metadata with actions */}
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Navi" size="small" />}>
+ <XDSChatMessageBubble
+ group="first"
+ name={
+ <XDSText type="supporting" weight="semibold" color="secondary">
+ Navi
+ </XDSText>
+ }>
+ Sure! I took a look at PR #1742.
+ </XDSChatMessageBubble>
+ <XDSChatMessageBubble
+ group="last"
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}
+ footer={
+ <XDSHStack gap={1}>
+ <XDSButton
+ label="Copy"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon="copy" size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ <XDSText type="supporting" color="secondary">
+ Claude Opus 4.6
+ </XDSText>
+ </XDSHStack>
+ }
+ />
+ }>
+ The changes look great — clean code, good test coverage. Ship it!
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:32:00" format="time" />}
+ status="delivered"
+ />
+ }>
+ Thanks, shipping now!
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+
+ <XDSText type="supporting" color="secondary">
+ Without message bubbles (ghost variant)
+ </XDSText>
+ <XDSChatMessageList>
+ <XDSChatMessage
+ sender="assistant"
+ avatar={<XDSAvatar name="Navi" size="small" />}
+ name={
+ <XDSText type="supporting" weight="semibold" color="secondary">
+ Navi
+ </XDSText>
+ }
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={<XDSTimestamp value="2026-03-15T14:31:00" format="time" />}
+ footer={<XDSText type="supporting" color="secondary">Claude Opus 4.6</XDSText>}
+ />
+ }>
+ <XDSChatMessageBubble variant="ghost">
+ Here is a response without a visible bubble boundary. The ghost
+ variant keeps padding for alignment but renders transparent.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble variant="ghost">
+ User messages can also use the ghost variant for a minimal look.
+ </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
new file mode 100644
index 0000000000..7639c5f0ca
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatMessageList',
+ description: 'Scrollable message list with density context and system message dividers.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Chat', 'ChatMessageList'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.tsx b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.tsx
new file mode 100644
index 0000000000..75147b6bf5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListShowcase.tsx
@@ -0,0 +1,54 @@
+'use client';
+
+import {
+ XDSChatMessageList,
+ XDSChatMessage,
+ XDSChatMessageBubble,
+ XDSChatSystemMessage,
+} from '@xds/core/Chat';
+import {XDSVStack} from '@xds/core/Layout';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ container: {
+ height: 400,
+ },
+});
+
+export default function ChatMessageListShowcase() {
+ return (
+ <XDSVStack xstyle={styles.container}>
+ <XDSChatMessageList density="balanced">
+ <XDSChatSystemMessage variant="divider">
+ March 15, 2026
+ </XDSChatSystemMessage>
+
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble>
+ What's the best way to 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>
+ </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>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ </XDSVStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatMessageMetadata/ChatMessageMetadataShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatMessageMetadata/ChatMessageMetadataShowcase.doc.mjs
new file mode 100644
index 0000000000..d738e8aaa3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageMetadata/ChatMessageMetadataShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatMessageMetadata',
+ description: 'Message metadata showing timestamps, delivery status, model info, and action buttons (copy, retry, approve) in the footer area.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Chat', 'ChatMessageMetadata', 'Timestamp', 'Button', 'Icon', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatMessageMetadata/ChatMessageMetadataShowcase.tsx b/packages/cli/templates/blocks/components/ChatMessageMetadata/ChatMessageMetadataShowcase.tsx
new file mode 100644
index 0000000000..243bab8afc
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatMessageMetadata/ChatMessageMetadataShowcase.tsx
@@ -0,0 +1,118 @@
+'use client';
+
+import {
+ XDSChatMessageList,
+ XDSChatMessage,
+ XDSChatMessageBubble,
+ XDSChatMessageMetadata,
+} from '@xds/core/Chat';
+import {XDSTimestamp} from '@xds/core/Timestamp';
+import {XDSText} from '@xds/core/Text';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSHStack} from '@xds/core/Layout';
+
+export default function ChatMessageMetadataShowcase() {
+ return (
+ <XDSChatMessageList>
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:30:00" format="time" />
+ }
+ status="read"
+ />
+ }>
+ Did you see the latest deployment?
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:31:00" format="time" />
+ }
+ footer={
+ <XDSHStack gap={1}>
+ <XDSButton
+ label="Copy"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon="copy" size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ <XDSButton
+ label="Retry"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon="wrench" size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ <XDSButton
+ label="Good"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon="check" size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ <XDSText type="supporting" color="secondary">
+ Claude Opus 4.6
+ </XDSText>
+ </XDSHStack>
+ }
+ />
+ }>
+ Yes, everything looks good! The build passed all checks and
+ performance metrics are within target.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage sender="user">
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:32:00" format="time" />
+ }
+ status="delivered"
+ />
+ }>
+ Great, shipping it now.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+
+ <XDSChatMessage sender="assistant">
+ <XDSChatMessageBubble
+ metadata={
+ <XDSChatMessageMetadata
+ timestamp={
+ <XDSTimestamp value="2026-03-15T14:33:00" format="time" />
+ }
+ status="error"
+ footer={
+ <XDSHStack gap={1}>
+ <XDSButton
+ label="Retry"
+ variant="ghost"
+ size="sm"
+ icon={<XDSIcon icon="wrench" size="sm" />}
+ isIconOnly
+ onClick={() => {}}
+ />
+ </XDSHStack>
+ }
+ />
+ }>
+ Metadata can also show error status with a retry action.
+ </XDSChatMessageBubble>
+ </XDSChatMessage>
+ </XDSChatMessageList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs
new file mode 100644
index 0000000000..6213bf49a6
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatSendButton',
+ description: 'Send button in default, active, streaming, custom icon, small size, and standalone states.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatSendButton', 'Icon', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx
new file mode 100644
index 0000000000..3c7463afc3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSendButton/ChatSendButtonShowcase.tsx
@@ -0,0 +1,103 @@
+'use client';
+
+import {XDSChatComposer, XDSChatSendButton} from '@xds/core/Chat';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function ChatSendButtonShowcase() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Default (empty input — disabled)
+ </XDSText>
+ <XDSChatComposer onSubmit={() => {}} />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ With content (enabled)
+ </XDSText>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ value="Ready to send"
+ onChange={() => {}}
+ />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Streaming (shows stop button)
+ </XDSText>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ onStop={() => {}}
+ isStreaming
+ />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Custom send icon
+ </XDSText>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ value="Custom icon"
+ onChange={() => {}}
+ sendButton={
+ <XDSChatSendButton
+ sendIcon={<XDSIcon icon="check" size="sm" />}
+ onSend={() => {}}
+ isDisabled={false}
+ />
+ }
+ />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Small size
+ </XDSText>
+ <XDSChatComposer
+ onSubmit={() => {}}
+ value="Small send button"
+ onChange={() => {}}
+ density="compact"
+ sendButton={
+ <XDSChatSendButton
+ size="sm"
+ onSend={() => {}}
+ isDisabled={false}
+ />
+ }
+ />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Standalone (outside composer context)
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} vAlign="center">
+ <XDSChatSendButton
+ isDisabled={true}
+ onSend={() => {}}
+ />
+ <XDSChatSendButton
+ isDisabled={false}
+ onSend={() => {}}
+ />
+ <XDSChatSendButton
+ isStreaming={true}
+ onStop={() => {}}
+ />
+ <XDSChatSendButton
+ size="sm"
+ isDisabled={false}
+ onSend={() => {}}
+ />
+ </XDSStack>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/ChatSystemMessage/ChatSystemMessageShowcase.doc.mjs b/packages/cli/templates/blocks/components/ChatSystemMessage/ChatSystemMessageShowcase.doc.mjs
new file mode 100644
index 0000000000..88bc9947b2
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSystemMessage/ChatSystemMessageShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'ChatSystemMessage',
+ description: 'System messages for date dividers, status updates, and informational notices.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Chat', 'ChatSystemMessage'],
+};
diff --git a/packages/cli/templates/blocks/components/ChatSystemMessage/ChatSystemMessageShowcase.tsx b/packages/cli/templates/blocks/components/ChatSystemMessage/ChatSystemMessageShowcase.tsx
new file mode 100644
index 0000000000..1cd1696a9b
--- /dev/null
+++ b/packages/cli/templates/blocks/components/ChatSystemMessage/ChatSystemMessageShowcase.tsx
@@ -0,0 +1,32 @@
+'use client';
+
+import {
+ XDSChatMessageList,
+ XDSChatSystemMessage,
+} from '@xds/core/Chat';
+
+export default function ChatSystemMessageShowcase() {
+ return (
+ <XDSChatMessageList>
+ <XDSChatSystemMessage variant="divider">
+ March 15, 2026
+ </XDSChatSystemMessage>
+
+ <XDSChatSystemMessage>
+ Alex joined the conversation
+ </XDSChatSystemMessage>
+
+ <XDSChatSystemMessage>
+ Navi is thinking…
+ </XDSChatSystemMessage>
+
+ <XDSChatSystemMessage variant="divider">
+ Today
+ </XDSChatSystemMessage>
+
+ <XDSChatSystemMessage>
+ Conversation marked as resolved
+ </XDSChatSystemMessage>
+ </XDSChatMessageList>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterShowcase.doc.mjs b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterShowcase.doc.mjs
new file mode 100644
index 0000000000..35f3cdcd62
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'CommandPaletteFooter',
+ description: 'Command palette footer with custom tip content.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['CommandPalette', 'CommandPaletteFooter', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterShowcase.tsx b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterShowcase.tsx
new file mode 100644
index 0000000000..fa47a2acd0
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteFooter/CommandPaletteFooterShowcase.tsx
@@ -0,0 +1,37 @@
+'use client';
+
+import {useMemo} from 'react';
+import {
+ XDSCommandPalette,
+ XDSCommandPaletteFooter,
+} from '@xds/core/CommandPalette';
+import {XDSText} from '@xds/core/Text';
+import {createStaticSource} from '@xds/core/Typeahead';
+
+export default function CommandPaletteFooterShowcase() {
+ const source = useMemo(
+ () =>
+ createStaticSource([
+ {id: 'new-file', label: 'New File'},
+ {id: 'open-recent', label: 'Open Recent'},
+ {id: 'save-all', label: 'Save All'},
+ ]),
+ [],
+ );
+
+ return (
+ <XDSCommandPalette
+ isOpen
+ isInline
+ onOpenChange={() => {}}
+ searchSource={source}
+ footer={
+ <XDSCommandPaletteFooter>
+ <XDSText type="supporting" color="secondary">
+ Tip: Press ⌘K anywhere to open the command palette
+ </XDSText>
+ </XDSCommandPaletteFooter>
+ }
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupShowcase.doc.mjs b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupShowcase.doc.mjs
new file mode 100644
index 0000000000..f1d2192f70
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'CommandPaletteGroup',
+ description: 'Command palette groups in both data-driven (auxiliaryData.group) and composed (XDSCommandPaletteGroup + XDSCommandPaletteItem) forms.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['CommandPalette', 'CommandPaletteGroup', 'CommandPaletteItem', 'CommandPaletteList', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupShowcase.tsx b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupShowcase.tsx
new file mode 100644
index 0000000000..049db7c3c7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteGroup/CommandPaletteGroupShowcase.tsx
@@ -0,0 +1,67 @@
+'use client';
+
+import {useMemo} from 'react';
+import {
+ XDSCommandPalette,
+ XDSCommandPaletteList,
+ XDSCommandPaletteGroup,
+ XDSCommandPaletteItem,
+} from '@xds/core/CommandPalette';
+import {createStaticSource} from '@xds/core/Typeahead';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+export default function CommandPaletteGroupShowcase() {
+ const source = useMemo(
+ () =>
+ createStaticSource([
+ {id: 'index', label: 'index.tsx', auxiliaryData: {group: 'Recent Files'}},
+ {id: 'app', label: 'App.tsx', auxiliaryData: {group: 'Recent Files'}},
+ {id: 'settings', label: 'Open Settings', auxiliaryData: {group: 'Commands'}},
+ {id: 'terminal', label: 'Toggle Terminal', auxiliaryData: {group: 'Commands'}},
+ {id: 'theme', label: 'Color Theme', auxiliaryData: {group: 'Preferences'}},
+ {id: 'font', label: 'Font Size', auxiliaryData: {group: 'Preferences'}},
+ ]),
+ [],
+ );
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Data-driven grouping (auxiliaryData.group)
+ </XDSText>
+ <XDSCommandPalette
+ isOpen
+ isInline
+ onOpenChange={() => {}}
+ searchSource={source}
+ />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Composed form (XDSCommandPaletteGroup + XDSCommandPaletteItem)
+ </XDSText>
+ <XDSCommandPaletteList>
+ <XDSCommandPaletteGroup heading="Navigation">
+ <XDSCommandPaletteItem value="home" onSelect={() => {}}>
+ Home
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="dashboard" onSelect={() => {}}>
+ Dashboard
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteGroup>
+ <XDSCommandPaletteGroup heading="Actions">
+ <XDSCommandPaletteItem value="new-file" onSelect={() => {}}>
+ New File
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="save" onSelect={() => {}}>
+ Save All
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteGroup>
+ </XDSCommandPaletteList>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemShowcase.doc.mjs
new file mode 100644
index 0000000000..8d028e85e9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'CommandPaletteItem',
+ description: 'Command palette items with custom content via renderItem and as composed XDSCommandPaletteItem with icons, highlighted, selected, and disabled states.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['CommandPalette', 'CommandPaletteItem', 'CommandPaletteList', 'Kbd', 'Icon', 'Text', 'Layout'],
+};
diff --git a/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemShowcase.tsx b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemShowcase.tsx
new file mode 100644
index 0000000000..74614034dc
--- /dev/null
+++ b/packages/cli/templates/blocks/components/CommandPaletteItem/CommandPaletteItemShowcase.tsx
@@ -0,0 +1,84 @@
+'use client';
+
+import {useMemo} from 'react';
+import {
+ XDSCommandPalette,
+ XDSCommandPaletteList,
+ XDSCommandPaletteItem,
+} from '@xds/core/CommandPalette';
+import {XDSText} from '@xds/core/Text';
+import {XDSKbd} from '@xds/core/Kbd';
+import {XDSIcon} from '@xds/core/Icon';
+import {createStaticSource} from '@xds/core/Typeahead';
+import {XDSStack} from '@xds/core/Layout';
+import type {XDSSearchableItem} from '@xds/core/Typeahead';
+import * as stylex from '@stylexjs/stylex';
+
+const styles = stylex.create({
+ itemLabel: {
+ flexGrow: 1,
+ },
+});
+
+type CommandItem = XDSSearchableItem<{shortcut?: string}>;
+
+const commands: CommandItem[] = [
+ {id: 'save', label: 'Save File', auxiliaryData: {shortcut: 'mod+s'}},
+ {id: 'find', label: 'Find in Files', auxiliaryData: {shortcut: 'mod+shift+f'}},
+ {id: 'palette', label: 'Command Palette', auxiliaryData: {shortcut: 'mod+shift+p'}},
+ {id: 'terminal', label: 'Toggle Terminal', auxiliaryData: {shortcut: 'ctrl+`'}},
+ {id: 'sidebar', label: 'Toggle Sidebar', auxiliaryData: {shortcut: 'mod+b'}},
+];
+
+export default function CommandPaletteItemShowcase() {
+ const source = useMemo(() => createStaticSource(commands), []);
+
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Custom renderItem with keyboard shortcuts
+ </XDSText>
+ <XDSCommandPalette
+ isOpen
+ isInline
+ onOpenChange={() => {}}
+ searchSource={source}
+ renderItem={(item: CommandItem) => (
+ <>
+ <XDSText type="body" xstyle={styles.itemLabel}>
+ {item.label}
+ </XDSText>
+ {item.auxiliaryData?.shortcut && (
+ <XDSKbd keys={item.auxiliaryData.shortcut} />
+ )}
+ </>
+ )}
+ />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Composed items with icons and states
+ </XDSText>
+ <XDSCommandPaletteList>
+ <XDSCommandPaletteItem value="home" onSelect={() => {}}>
+ <XDSIcon icon="externalLink" size="sm" />
+ <XDSText type="body" xstyle={styles.itemLabel}>Home</XDSText>
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="search" isHighlighted onSelect={() => {}}>
+ <XDSIcon icon="search" size="sm" />
+ <XDSText type="body" xstyle={styles.itemLabel}>Search (highlighted)</XDSText>
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="selected" isSelected onSelect={() => {}}>
+ <XDSIcon icon="check" size="sm" />
+ <XDSText type="body" xstyle={styles.itemLabel}>Selected item</XDSText>
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="disabled" isDisabled>
+ <XDSText type="body" xstyle={styles.itemLabel}>Disabled item</XDSText>
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteList>
+ </XDSStack>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.doc.mjs b/packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.doc.mjs
new file mode 100644
index 0000000000..dd44beb9fe
--- /dev/null
+++ b/packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'NavIcon',
+ description: 'Circular icon containers for navigation headers with accent backgrounds.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['NavIcon', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.tsx b/packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.tsx
new file mode 100644
index 0000000000..63cc547feb
--- /dev/null
+++ b/packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.tsx
@@ -0,0 +1,15 @@
+'use client';
+
+import {XDSNavIcon} from '@xds/core/NavIcon';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSHStack} from '@xds/core/Layout';
+
+export default function NavIconShowcase() {
+ return (
+ <XDSHStack gap={4} vAlign="center">
+ <XDSNavIcon icon={<XDSIcon icon="search" />} />
+ <XDSNavIcon icon={<XDSIcon icon="calendar" />} />
+ <XDSNavIcon icon={<XDSIcon icon="wrench" />} />
+ </XDSHStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.doc.mjs b/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.doc.mjs
new file mode 100644
index 0000000000..65fa9c35a1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TreeListBranches',
+ description: 'Tree with expandable branches at multiple nesting levels.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['TreeList'],
+};
diff --git a/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.tsx b/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.tsx
new file mode 100644
index 0000000000..2831eb3005
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TreeListBranches/TreeListBranchesShowcase.tsx
@@ -0,0 +1,62 @@
+'use client';
+
+import {XDSTreeList} from '@xds/core/TreeList';
+
+const noop = () => {};
+
+export default function TreeListBranchesShowcase() {
+ return (
+ <XDSTreeList
+ items={[
+ {
+ id: 'design-system',
+ label: 'Design System',
+ isExpanded: true,
+ children: [
+ {
+ id: 'components',
+ label: 'Components',
+ isExpanded: true,
+ children: [
+ {
+ id: 'inputs',
+ label: 'Inputs',
+ children: [
+ {id: 'text-input', label: 'TextInput', onClick: noop},
+ {id: 'checkbox', label: 'Checkbox', onClick: noop},
+ {id: 'selector', label: 'Selector', onClick: noop},
+ ],
+ },
+ {
+ id: 'layout',
+ label: 'Layout',
+ children: [
+ {id: 'stack', label: 'Stack', onClick: noop},
+ {id: 'grid', label: 'Grid', onClick: noop},
+ ],
+ },
+ ],
+ },
+ {
+ id: 'tokens',
+ label: 'Tokens',
+ children: [
+ {id: 'colors', label: 'Colors', onClick: noop},
+ {id: 'spacing', label: 'Spacing', onClick: noop},
+ {id: 'typography', label: 'Typography', onClick: noop},
+ ],
+ },
+ ],
+ },
+ {
+ id: 'utilities',
+ label: 'Utilities',
+ children: [
+ {id: 'hooks', label: 'Hooks', onClick: noop},
+ {id: 'helpers', label: 'Helpers', onClick: noop},
+ ],
+ },
+ ]}
+ />
+ );
+}
diff --git a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs
new file mode 100644
index 0000000000..a0e32026f9
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'TreeListItem',
+ description: 'Tree items with descriptions, icons, badges, selection, disabled state, and nested expand/collapse. TreeList is data-driven — no composed children API.',
+ isReady: true,
+ isShowcase: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['TreeList', 'Badge', 'Icon', 'Layout', 'Text'],
+};
diff --git a/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.tsx b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.tsx
new file mode 100644
index 0000000000..9e37423ec1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/TreeListItem/TreeListItemShowcase.tsx
@@ -0,0 +1,99 @@
+'use client';
+
+import {XDSTreeList} from '@xds/core/TreeList';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSStack} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+
+const noop = () => {};
+
+export default function TreeListItemShowcase() {
+ return (
+ <XDSStack direction="vertical" gap={4}>
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Items with descriptions, icons, badges, and states
+ </XDSText>
+ <XDSTreeList
+ items={[
+ {
+ id: 'inbox',
+ label: 'Inbox',
+ description: '12 unread messages',
+ startContent: <XDSIcon icon="info" size="sm" />,
+ endContent: <XDSBadge label="12" variant="info" />,
+ onClick: noop,
+ },
+ {
+ id: 'drafts',
+ label: 'Drafts',
+ description: '3 draft messages',
+ startContent: <XDSIcon icon="clock" size="sm" />,
+ onClick: noop,
+ },
+ {
+ id: 'sent',
+ label: 'Sent',
+ isSelected: true,
+ startContent: <XDSIcon icon="check" size="sm" />,
+ onClick: noop,
+ },
+ {
+ id: 'archive',
+ label: 'Archive',
+ onClick: noop,
+ },
+ {
+ id: 'spam',
+ label: 'Spam',
+ isDisabled: true,
+ startContent: <XDSIcon icon="warning" size="sm" />,
+ },
+ ]}
+ />
+ </XDSStack>
+
+ <XDSStack direction="vertical" gap={1}>
+ <XDSText type="supporting" color="secondary">
+ Nested items with expand/collapse
+ </XDSText>
+ <XDSTreeList
+ items={[
+ {
+ id: 'src',
+ label: 'src',
+ isExpanded: true,
+ children: [
+ {
+ id: 'components',
+ label: 'components',
+ isExpanded: true,
+ children: [
+ {id: 'button', label: 'Button.tsx', onClick: noop},
+ {id: 'input', label: 'Input.tsx', onClick: noop},
+ ],
+ },
+ {id: 'app', label: 'App.tsx', onClick: noop},
+ {id: 'index', label: 'index.tsx', onClick: noop},
+ ],
+ },
+ {
+ id: 'tests',
+ label: 'tests',
+ children: [
+ {id: 'button-test', label: 'Button.test.tsx'},
+ ],
+ },
+ {id: 'pkg', label: 'package.json', onClick: noop},
+ ]}
+ />
+ </XDSStack>
+
+ <XDSText type="supporting" color="secondary">
+ Note: TreeList is data-driven — items are configured via the items prop.
+ There is no composed children API; XDSTreeListItem is an internal rendering detail.
+ </XDSText>
+ </XDSStack>
+ );
+}
diff --git a/packages/core/src/NavIcon/XDSNavIcon.tsx b/packages/core/src/NavIcon/XDSNavIcon.tsx
index bccea8b41e..07b60fc6fb 100644
--- a/packages/core/src/NavIcon/XDSNavIcon.tsx
+++ b/packages/core/src/NavIcon/XDSNavIcon.tsx
@@ -9,6 +9,7 @@
* - /packages/core/src/NavIcon/XDSNavIcon.test.tsx
* - /packages/core/src/NavIcon/index.ts
* - /apps/storybook/stories/TopNav.stories.tsx
+ * - /packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.tsx
*/
import {type ReactNode} from 'react';