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.mjssimilarity index 52%rename from packages/cli/templates/blocks/components/Stack/StackSidebarLayout.doc.mjsrename to packages/cli/templates/blocks/components/Stack/StackAlignment.doc.mjsindex 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.tsxnew file mode 100644index 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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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: [