Skip to content

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

TypeScript

Improve Stack docs page and block examples (#1680)

rubyycheung07fb90f00364
diff --git a/packages/cli/templates/blocks/components/Stack/StackSidebarLayout.doc.mjs b/packages/cli/templates/blocks/components/Stack/StackAlignment.doc.mjs
similarity index 52%
rename from packages/cli/templates/blocks/components/Stack/StackSidebarLayout.doc.mjs
rename to packages/cli/templates/blocks/components/Stack/StackAlignment.doc.mjs
index 7558898d09..b61ea4d34a 100644
--- a/packages/cli/templates/blocks/components/Stack/StackSidebarLayout.doc.mjs
+++ b/packages/cli/templates/blocks/components/Stack/StackAlignment.doc.mjs
@@ -1,10 +1,10 @@
/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
export const doc = {
type: 'block',
- name: 'Stack — Sidebar Layout',
+ name: 'Stack — Alignment',
description:
- 'Fixed-width sidebar alongside a flexible main content area.',
+ 'Buttons positioned at the start, center, and end of a row.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Stack', 'StackItem'],
+ componentsUsed: ['Layout', 'Card', 'Button', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Stack/StackAlignment.tsx b/packages/cli/templates/blocks/components/Stack/StackAlignment.tsx
new file mode 100644
index 0000000000..df4f8202a3
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Stack/StackAlignment.tsx
@@ -0,0 +1,46 @@
+'use client';
+
+import {XDSStack} from '@xds/core/Layout';
+import {XDSCard} from '@xds/core/Card';
+import {XDSButton} from '@xds/core/Button';
+import {XDSText} from '@xds/core/Text';
+
+export default function StackAlignment() {
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ <XDSCard padding={4} variant="muted">
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Start (left)
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} hAlign="start">
+ <XDSButton label="Cancel" variant="secondary" size="sm" />
+ <XDSButton label="Save" variant="primary" size="sm" />
+ </XDSStack>
+ </XDSStack>
+ </XDSCard>
+ <XDSCard padding={4} variant="muted">
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ Center
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} hAlign="center">
+ <XDSButton label="Cancel" variant="secondary" size="sm" />
+ <XDSButton label="Save" variant="primary" size="sm" />
+ </XDSStack>
+ </XDSStack>
+ </XDSCard>
+ <XDSCard padding={4} variant="muted">
+ <XDSStack direction="vertical" gap={2}>
+ <XDSText type="supporting" color="secondary">
+ End (right)
+ </XDSText>
+ <XDSStack direction="horizontal" gap={2} hAlign="end">
+ <XDSButton label="Cancel" variant="secondary" size="sm" />
+ <XDSButton label="Save" variant="primary" size="sm" />
+ </XDSStack>
+ </XDSStack>
+ </XDSCard>
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Stack/StackDirections.doc.mjs b/packages/cli/templates/blocks/components/Stack/StackDirections.doc.mjs
index 29d217b180..cd387ec5d0 100644
--- a/packages/cli/templates/blocks/components/Stack/StackDirections.doc.mjs
+++ b/packages/cli/templates/blocks/components/Stack/StackDirections.doc.mjs
@@ -2,8 +2,10 @@
export const doc = {
type: 'block',
name: 'Stack — Directions',
- description: 'Horizontal and vertical stack directions side by side.',
+ description:
+ 'Badges arranged horizontally and vertically in side-by-side cards.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Stack'],
+ isShowcase: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Layout', 'Badge', 'Text'],
};
diff --git a/packages/cli/templates/blocks/components/Stack/StackDirections.tsx b/packages/cli/templates/blocks/components/Stack/StackDirections.tsx
index 2b271f48bd..1773ebf67c 100644
--- a/packages/cli/templates/blocks/components/Stack/StackDirections.tsx
+++ b/packages/cli/templates/blocks/components/Stack/StackDirections.tsx
@@ -1,35 +1,32 @@
'use client';
import {XDSStack} from '@xds/core/Layout';
-
-const boxStyle = {
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#e8f0fe',
- color: '#1a73e8',
- border: '1px solid #c6dafc',
- fontWeight: 500,
-} as const;
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSText} from '@xds/core/Text';
export default function StackDirections() {
return (
- <div style={{display: 'flex', flexDirection: 'column', gap: 24}}>
- <div>
- <h4 style={{margin: '0 0 8px'}}>Horizontal</h4>
+ <XDSStack direction="horizontal" gap={10} hAlign="center">
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Horizontal
+ </XDSText>
<XDSStack direction="horizontal" gap={2}>
- <div style={boxStyle}>Item 1</div>
- <div style={boxStyle}>Item 2</div>
- <div style={boxStyle}>Item 3</div>
+ <XDSBadge label="React" />
+ <XDSBadge label="TypeScript" />
+ <XDSBadge label="Node.js" />
</XDSStack>
- </div>
- <div>
- <h4 style={{margin: '0 0 8px'}}>Vertical</h4>
+ </XDSStack>
+ <XDSStack direction="vertical" gap={3}>
+ <XDSText type="supporting" color="secondary">
+ Vertical
+ </XDSText>
<XDSStack direction="vertical" gap={2}>
- <div style={boxStyle}>Item 1</div>
- <div style={boxStyle}>Item 2</div>
- <div style={boxStyle}>Item 3</div>
+ <XDSBadge label="React" />
+ <XDSBadge label="TypeScript" />
+ <XDSBadge label="Node.js" />
</XDSStack>
- </div>
- </div>
+ </XDSStack>
+ </XDSStack>
);
}
diff --git a/packages/cli/templates/blocks/components/Stack/StackFillItem.doc.mjs b/packages/cli/templates/blocks/components/Stack/StackFillItem.doc.mjs
new file mode 100644
index 0000000000..7de93d8dc7
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Stack/StackFillItem.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'Stack — Fill Item',
+ description:
+ 'An avatar, text, and button in a row — the text stretches to fill the available space.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['Layout', 'Text', 'Button', 'Avatar'],
+};
diff --git a/packages/cli/templates/blocks/components/Stack/StackFillItem.tsx b/packages/cli/templates/blocks/components/Stack/StackFillItem.tsx
new file mode 100644
index 0000000000..005b84a4d1
--- /dev/null
+++ b/packages/cli/templates/blocks/components/Stack/StackFillItem.tsx
@@ -0,0 +1,43 @@
+'use client';
+
+import {XDSStack, XDSStackItem} from '@xds/core/Layout';
+import {XDSText} from '@xds/core/Text';
+import {XDSButton} from '@xds/core/Button';
+import {XDSAvatar} from '@xds/core/Avatar';
+
+const USERS = [
+ {name: 'Olivia Chen', role: 'Engineering Lead'},
+ {name: 'Marcus Rivera', role: 'Product Designer'},
+ {name: 'Aisha Patel', role: 'Marketing Manager'},
+];
+
+export default function StackFillItem() {
+ return (
+ <XDSStack direction="vertical" gap={3}>
+ {USERS.map(user => (
+ <XDSStack
+ key={user.name}
+ direction="horizontal"
+ gap={3}
+ vAlign="center">
+ <XDSStackItem size="static">
+ <XDSAvatar name={user.name} size="small" />
+ </XDSStackItem>
+ <XDSStackItem size="fill">
+ <XDSStack direction="vertical" gap={0}>
+ <XDSText type="body" weight="bold">
+ {user.name}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {user.role}
+ </XDSText>
+ </XDSStack>
+ </XDSStackItem>
+ <XDSStackItem size="static">
+ <XDSButton label="View" variant="secondary" size="sm" />
+ </XDSStackItem>
+ </XDSStack>
+ ))}
+ </XDSStack>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/Stack/StackHeaderLayout.doc.mjs b/packages/cli/templates/blocks/components/Stack/StackHeaderLayout.doc.mjs
deleted file mode 100644
index 805e9f424f..0000000000
--- a/packages/cli/templates/blocks/components/Stack/StackHeaderLayout.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Stack — Header Layout',
- description:
- 'Common header pattern with logo, flexible navigation, and action areas.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Stack', 'StackItem'],
-};
diff --git a/packages/cli/templates/blocks/components/Stack/StackHeaderLayout.tsx b/packages/cli/templates/blocks/components/Stack/StackHeaderLayout.tsx
deleted file mode 100644
index ca5fc89578..0000000000
--- a/packages/cli/templates/blocks/components/Stack/StackHeaderLayout.tsx
+++ /dev/null
@@ -1,37 +0,0 @@
-'use client';
-
-import {XDSStack, XDSStackItem} from '@xds/core/Layout';
-
-const sideStyle = {
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#f3f4f6',
- color: '#4b5563',
- border: '1px solid #d1d5db',
- fontWeight: 500,
-} as const;
-
-const mainStyle = {
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#e8f0fe',
- color: '#1a73e8',
- border: '1px solid #c6dafc',
- fontWeight: 500,
-} as const;
-
-export default function StackHeaderLayout() {
- return (
- <XDSStack direction="horizontal" gap={2}>
- <XDSStackItem size="static">
- <div style={sideStyle}>Logo</div>
- </XDSStackItem>
- <XDSStackItem size="fill">
- <div style={mainStyle}>Navigation</div>
- </XDSStackItem>
- <XDSStackItem size="static">
- <div style={sideStyle}>Actions</div>
- </XDSStackItem>
- </XDSStack>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Stack/StackItemFill.doc.mjs b/packages/cli/templates/blocks/components/Stack/StackItemFill.doc.mjs
deleted file mode 100644
index f5e3448f96..0000000000
--- a/packages/cli/templates/blocks/components/Stack/StackItemFill.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Stack — Fill Item',
- description:
- 'Static items on the edges with a fill item that grows to take remaining space.',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['Stack', 'StackItem'],
-};
diff --git a/packages/cli/templates/blocks/components/Stack/StackItemFill.tsx b/packages/cli/templates/blocks/components/Stack/StackItemFill.tsx
deleted file mode 100644
index 2ea9f335f1..0000000000
--- a/packages/cli/templates/blocks/components/Stack/StackItemFill.tsx
+++ /dev/null
@@ -1,37 +0,0 @@
-'use client';
-
-import {XDSStack, XDSStackItem} from '@xds/core/Layout';
-
-const staticStyle = {
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#f3f4f6',
- color: '#4b5563',
- border: '1px solid #d1d5db',
- fontWeight: 500,
-} as const;
-
-const fillStyle = {
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#e8f0fe',
- color: '#1a73e8',
- border: '1px solid #c6dafc',
- fontWeight: 500,
-} as const;
-
-export default function StackItemFill() {
- return (
- <XDSStack direction="horizontal" gap={2}>
- <XDSStackItem size="static">
- <div style={staticStyle}>Static</div>
- </XDSStackItem>
- <XDSStackItem size="fill">
- <div style={fillStyle}>Fill (grows to remaining space)</div>
- </XDSStackItem>
- <XDSStackItem size="static">
- <div style={staticStyle}>Static</div>
- </XDSStackItem>
- </XDSStack>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Stack/StackShowcase.doc.mjs b/packages/cli/templates/blocks/components/Stack/StackShowcase.doc.mjs
deleted file mode 100644
index 4a0867a551..0000000000
--- a/packages/cli/templates/blocks/components/Stack/StackShowcase.doc.mjs
+++ /dev/null
@@ -1,8 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'Stack',
- isReady: true,
- aspectRatio: 1,
- isShowcase: true,
-};
diff --git a/packages/cli/templates/blocks/components/Stack/StackShowcase.tsx b/packages/cli/templates/blocks/components/Stack/StackShowcase.tsx
deleted file mode 100644
index b45a3ed815..0000000000
--- a/packages/cli/templates/blocks/components/Stack/StackShowcase.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-'use client';
-
-import {XDSStack} from '@xds/core/Layout';
-
-export default function StackShowcase() {
- return (
- <XDSStack direction="vertical" gap={2}>
- <div
- style={{
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#e8f0fe',
- color: '#1a73e8',
- border: '1px solid #c6dafc',
- }}>
- Item 1
- </div>
- <div
- style={{
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#e8f0fe',
- color: '#1a73e8',
- border: '1px solid #c6dafc',
- }}>
- Item 2
- </div>
- <div
- style={{
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#e8f0fe',
- color: '#1a73e8',
- border: '1px solid #c6dafc',
- }}>
- Item 3
- </div>
- </XDSStack>
- );
-}
diff --git a/packages/cli/templates/blocks/components/Stack/StackSidebarLayout.tsx b/packages/cli/templates/blocks/components/Stack/StackSidebarLayout.tsx
deleted file mode 100644
index 9ad9e0a24f..0000000000
--- a/packages/cli/templates/blocks/components/Stack/StackSidebarLayout.tsx
+++ /dev/null
@@ -1,40 +0,0 @@
-'use client';
-
-import {XDSStack, XDSStackItem} from '@xds/core/Layout';
-
-const sidebarStyle = {
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#f3f4f6',
- color: '#4b5563',
- border: '1px solid #d1d5db',
- fontWeight: 500,
- height: '100%',
- boxSizing: 'border-box',
-} as const;
-
-const contentStyle = {
- padding: '8px 16px',
- borderRadius: 6,
- backgroundColor: '#e8f0fe',
- color: '#1a73e8',
- border: '1px solid #c6dafc',
- fontWeight: 500,
- height: '100%',
- boxSizing: 'border-box',
-} as const;
-
-export default function StackSidebarLayout() {
- return (
- <div style={{height: 200}}>
- <XDSStack direction="horizontal" gap={2}>
- <XDSStackItem size="static">
- <div style={{...sidebarStyle, width: 150}}>Sidebar</div>
- </XDSStackItem>
- <XDSStackItem size="fill">
- <div style={contentStyle}>Main Content</div>
- </XDSStackItem>
- </XDSStack>
- </div>
- );
-}
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index 7bdb4180ad..0190955f1b 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -172,12 +172,11 @@ export const docs = {
],
usage: {
description:
- 'Stack provides layout primitives for arranging items in horizontal or vertical sequences with consistent spacing. Use XDSHStack for row layouts and XDSVStack for column layouts when distributing child elements with uniform gaps from the design system spacing scale.',
+ 'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
bestPractices: [
- { guidance: true, description: 'Use the gap prop with design system spacing tokens to maintain consistent spacing between stack children.' },
- { guidance: true, description: 'Wrap individual items in XDSStackItem with size="fill" when an item should expand to consume remaining space.' },
- { guidance: false, description: 'Apply custom margins between stack children — use the gap prop instead for uniform spacing.' },
- { guidance: false, description: 'Nest stacks deeply when a single stack with wrap enabled could achieve the same layout.' },
+ { guidance: true, description: 'Use the gap prop for spacing between items — don\'t add margins manually.' },
+ { guidance: true, description: 'Use XDSStackItem with size="fill" to make one item stretch and fill the leftover space.' },
+ { guidance: false, description: 'Nest stacks inside stacks — try wrap="wrap" first to let items flow to the next line.' },
],
},
};
@@ -355,12 +354,11 @@ export const docsZh = {
],
usage: {
description:
- 'Stack provides layout primitives for arranging items in horizontal or vertical sequences with consistent spacing. Use XDSHStack for row layouts and XDSVStack for column layouts when distributing child elements with uniform gaps from the design system spacing scale.',
+ 'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
bestPractices: [
- { guidance: true, description: 'Use the gap prop with design system spacing tokens to maintain consistent spacing between stack children.' },
- { guidance: true, description: 'Wrap individual items in XDSStackItem with size="fill" when an item should expand to consume remaining space.' },
- { guidance: false, description: 'Apply custom margins between stack children — use the gap prop instead for uniform spacing.' },
- { guidance: false, description: 'Nest stacks deeply when a single stack with wrap enabled could achieve the same layout.' },
+ { guidance: true, description: 'Use the gap prop for spacing between items — don\'t add margins manually.' },
+ { guidance: true, description: 'Use XDSStackItem with size="fill" to make one item stretch and fill the leftover space.' },
+ { guidance: false, description: 'Nest stacks inside stacks — try wrap="wrap" first to let items flow to the next line.' },
],
},
};
@@ -370,12 +368,11 @@ export const docsDense = {
description: 'Stack layout primitives for horizontal/vertical sequences using flexbox w/ themed spacing tokens.',
usage: {
description:
- 'Stack provides layout primitives for arranging items in horizontal or vertical sequences with consistent spacing. Use XDSHStack for row layouts and XDSVStack for column layouts when distributing child elements with uniform gaps from the design system spacing scale.',
+ 'Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.',
bestPractices: [
- { guidance: true, description: 'Use the gap prop with design system spacing tokens to maintain consistent spacing between stack children.' },
- { guidance: true, description: 'Wrap individual items in XDSStackItem with size="fill" when an item should expand to consume remaining space.' },
- { guidance: false, description: 'Apply custom margins between stack children — use the gap prop instead for uniform spacing.' },
- { guidance: false, description: 'Nest stacks deeply when a single stack with wrap enabled could achieve the same layout.' },
+ { guidance: true, description: 'Use the gap prop for spacing between items — don\'t add margins manually.' },
+ { guidance: true, description: 'Use XDSStackItem with size="fill" to make one item stretch and fill the leftover space.' },
+ { guidance: false, description: 'Nest stacks inside stacks — try wrap="wrap" first to let items flow to the next line.' },
],
},
components: [