An open source design system that's fully customizable and agent ready
TypeScript
Improve Grid docs page and block examples (#1674)
Ted McDonaldf5cf69d883b9
diff --git a/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.doc.mjs b/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.doc.mjsindex bb6845dd4f..52eb14dd48 100644--- a/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.doc.mjs+++ b/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.doc.mjs@@ -2,8 +2,7 @@export const doc = {type: 'block',name: 'Grid — Dashboard Layout',- description:- 'Dashboard-style grid with a featured chart spanning 2x2, metric cards, and a full-width section',+ description: 'Dashboard layout with mixed-size widgets and a full-width summary row',isReady: true,aspectRatio: 4 / 3,componentsUsed: ['Grid', 'GridSpan', 'Card', 'Text'],diff --git a/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.tsx b/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.tsxindex 8e190ceeac..08507ba506 100644--- a/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.tsx+++ b/packages/cli/templates/blocks/components/Grid/GridDashboardLayout.tsx@@ -5,10 +5,10 @@ import {XDSCard} from '@xds/core/Card';import {XDSText} from '@xds/core/Text';const metrics = [- {label: 'Metric 1', description: 'Quick stat'},- {label: 'Metric 2', description: 'Quick stat'},- {label: 'Metric 3', description: 'Quick stat'},- {label: 'Metric 4', description: 'Quick stat'},+ {label: 'Revenue', value: '$48,290'},+ {label: 'Active Users', value: '12,841'},+ {label: 'Conversion', value: '3.2%'},+ {label: 'Avg Response', value: '245ms'},];export default function GridDashboardLayout() {@@ -17,30 +17,30 @@ export default function GridDashboardLayout() {<XDSGridSpan columns={2} rows={2}><XDSCard><XDSText type="label" display="block">- Main Chart+ Weekly Traffic</XDSText><XDSText type="supporting" display="block">- Large visualization widget+ Page views and unique visitors over the last 7 days</XDSText></XDSCard></XDSGridSpan>{metrics.map(m => (<XDSCard key={m.label}>- <XDSText type="label" display="block">+ <XDSText type="supporting" display="block">{m.label}</XDSText>- <XDSText type="supporting" display="block">- {m.description}+ <XDSText type="label" display="block">+ {m.value}</XDSText></XDSCard>))}<XDSGridSpan columns="full"><XDSCard><XDSText type="label" display="block">- Full-width Section+ Recent Activity</XDSText><XDSText type="supporting" display="block">- This section spans the entire width of the grid+ Latest events across all projects</XDSText></XDSCard></XDSGridSpan>diff --git a/packages/cli/templates/blocks/components/Grid/GridGalleryExample.doc.mjs b/packages/cli/templates/blocks/components/Grid/GridGalleryExample.doc.mjsindex 409964cba4..7522da8bb0 100644--- a/packages/cli/templates/blocks/components/Grid/GridGalleryExample.doc.mjs+++ b/packages/cli/templates/blocks/components/Grid/GridGalleryExample.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'Grid — Card Gallery',- description:- 'Responsive card gallery using auto-fill columns with image placeholders',+ description: 'Card gallery with responsive columns that maintain consistent widths',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['Grid', 'Card', 'Text'],+ componentsUsed: ['Grid', 'Card', 'VStack', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Grid/GridGalleryExample.tsx b/packages/cli/templates/blocks/components/Grid/GridGalleryExample.tsxindex e400071c76..9180ab5c3c 100644--- a/packages/cli/templates/blocks/components/Grid/GridGalleryExample.tsx+++ b/packages/cli/templates/blocks/components/Grid/GridGalleryExample.tsx@@ -2,6 +2,7 @@import {XDSGrid} from '@xds/core/Grid';import {XDSCard} from '@xds/core/Card';+import {XDSVStack} from '@xds/core/Stack';import {XDSText} from '@xds/core/Text';const cards = [@@ -20,20 +21,14 @@ export default function GridGalleryExample() {<XDSGrid columns={{minWidth: 280}} gap={5}>{cards.map(card => (<XDSCard key={card.title}>- <div- style={{- height: 120,- backgroundColor: 'var(--color-background-body)',- borderRadius: 'var(--radius-element, 8px)',- marginBottom: 12,- }}- />- <XDSText type="label" display="block">- {card.title}- </XDSText>- <XDSText type="supporting" display="block">- {card.description}- </XDSText>+ <XDSVStack gap={1}>+ <XDSText type="label" display="block">+ {card.title}+ </XDSText>+ <XDSText type="supporting" display="block">+ {card.description}+ </XDSText>+ </XDSVStack></XDSCard>))}</XDSGrid>diff --git a/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.doc.mjs b/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.doc.mjsindex d6a2f813d0..51eb3b4fe5 100644--- a/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.doc.mjs+++ b/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'Grid — Responsive Auto-Fit',- description:- 'Responsive grid using minChildWidth so items stretch to fill available space',+ description: 'Responsive grid where cards stretch to fill remaining space',isReady: true,- aspectRatio: 4 / 3,- componentsUsed: ['Grid'],+ aspectRatio: 3 / 4,+ componentsUsed: ['Grid', 'Card', 'VStack', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.tsx b/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.tsxindex b533f45ed4..527fe6222e 100644--- a/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.tsx+++ b/packages/cli/templates/blocks/components/Grid/GridResponsiveAutoFit.tsx@@ -1,49 +1,34 @@'use client';import {XDSGrid} from '@xds/core/Grid';+import {XDSCard} from '@xds/core/Card';+import {XDSVStack} from '@xds/core/Stack';+import {XDSText} from '@xds/core/Text';-const itemStyle = {- padding: 16,- backgroundColor: 'var(--color-background-body)',- borderRadius: 'var(--radius-element, 8px)',- textAlign: 'center' as const,-};+const teams = [+ {name: 'Design Systems', members: 8},+ {name: 'Frontend Platform', members: 12},+ {name: 'Developer Experience', members: 6},+ {name: 'Accessibility', members: 4},+ {name: 'Performance', members: 7},+ {name: 'Mobile Infrastructure', members: 9},+];export default function GridResponsiveAutoFit() {return (- <div style={{display: 'flex', flexDirection: 'column', gap: 24}}>- <div>- <p- style={{- fontSize: 12,- color: 'var(--color-text-secondary)',- marginBottom: 8,- }}>- 2 items — cards stretch to fill available space- </p>- <XDSGrid minChildWidth={200} gap={4}>- <div style={itemStyle}>Item 1</div>- <div style={itemStyle}>Item 2</div>- </XDSGrid>- </div>- <div>- <p- style={{- fontSize: 12,- color: 'var(--color-text-secondary)',- marginBottom: 8,- }}>- 6 items — columns wrap responsively- </p>- <XDSGrid minChildWidth={200} gap={4}>- <div style={itemStyle}>Item 1</div>- <div style={itemStyle}>Item 2</div>- <div style={itemStyle}>Item 3</div>- <div style={itemStyle}>Item 4</div>- <div style={itemStyle}>Item 5</div>- <div style={itemStyle}>Item 6</div>- </XDSGrid>- </div>- </div>+ <XDSGrid columns={{minWidth: 200, repeat: 'fit'}} gap={4}>+ {teams.map(team => (+ <XDSCard key={team.name}>+ <XDSVStack gap={1}>+ <XDSText type="label" display="block">+ {team.name}+ </XDSText>+ <XDSText type="supporting" display="block">+ {team.members} members+ </XDSText>+ </XDSVStack>+ </XDSCard>+ ))}+ </XDSGrid>);}diff --git a/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.doc.mjs b/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.doc.mjsindex 2847425490..17e2f527de 100644--- a/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.doc.mjs+++ b/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.doc.mjs@@ -2,9 +2,8 @@export const doc = {type: 'block',name: 'Grid — Column Spanning',- description:- 'Grid items spanning multiple columns using XDSGridSpan for featured content',+ description: 'Grid with featured items spanning two, three, and all columns',isReady: true,aspectRatio: 4 / 3,- componentsUsed: ['Grid', 'GridSpan'],+ componentsUsed: ['Grid', 'GridSpan', 'Card', 'VStack', 'Text'],};diff --git a/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.tsx b/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.tsxindex 5bb7ec0960..618b70548a 100644--- a/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.tsx+++ b/packages/cli/templates/blocks/components/Grid/GridWithGridSpan.tsx@@ -1,37 +1,72 @@'use client';import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';--const itemStyle = {- padding: 16,- backgroundColor: 'var(--color-background-body)',- borderRadius: 'var(--radius-element, 8px)',- textAlign: 'center' as const,-};--const featuredStyle = {- padding: 24,- backgroundColor: 'var(--color-accent-muted)',- borderRadius: 'var(--radius-element, 8px)',- textAlign: 'center' as const,- height: '100%',- boxSizing: 'border-box' as const,-};+import {XDSCard} from '@xds/core/Card';+import {XDSVStack} from '@xds/core/Stack';+import {XDSText} from '@xds/core/Text';export default function GridWithGridSpan() {return (<XDSGrid columns={4} gap={4}><XDSGridSpan columns={2}>- <div style={featuredStyle}>Spans 2 columns</div>+ <XDSCard variant="cyan">+ <XDSVStack gap={1}>+ <XDSText type="label" display="block">+ Featured Release+ </XDSText>+ <XDSText type="supporting" display="block">+ XDS 4.0 is now available with new layout primitives+ </XDSText>+ </XDSVStack>+ </XDSCard></XDSGridSpan>- <div style={itemStyle}>Normal</div>- <div style={itemStyle}>Normal</div>- <div style={itemStyle}>Normal</div>+ <XDSCard>+ <XDSText type="label" display="block">+ Components+ </XDSText>+ <XDSText type="supporting" display="block">+ 54 available+ </XDSText>+ </XDSCard>+ <XDSCard>+ <XDSText type="label" display="block">+ Templates+ </XDSText>+ <XDSText type="supporting" display="block">+ 28 available+ </XDSText>+ </XDSCard>+ <XDSCard>+ <XDSText type="label" display="block">+ Tokens+ </XDSText>+ <XDSText type="supporting" display="block">+ 120 defined+ </XDSText>+ </XDSCard><XDSGridSpan columns={3}>- <div style={featuredStyle}>Spans 3 columns</div>+ <XDSCard variant="cyan">+ <XDSVStack gap={1}>+ <XDSText type="label" display="block">+ Migration Guide+ </XDSText>+ <XDSText type="supporting" display="block">+ Step-by-step instructions for upgrading from v3 to v4+ </XDSText>+ </XDSVStack>+ </XDSCard></XDSGridSpan><XDSGridSpan columns="full">- <div style={featuredStyle}>Full width (spans all columns)</div>+ <XDSCard variant="cyan">+ <XDSVStack gap={1}>+ <XDSText type="label" display="block">+ Community Showcase+ </XDSText>+ <XDSText type="supporting" display="block">+ See how teams are building with XDS across the organization+ </XDSText>+ </XDSVStack>+ </XDSCard></XDSGridSpan></XDSGrid>);diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjsindex 9782a7ea14..896a1971e3 100644--- a/packages/core/src/Grid/Grid.doc.mjs+++ b/packages/core/src/Grid/Grid.doc.mjs@@ -6,11 +6,13 @@ export const docs = {keywords: ["grid","columns","responsive","auto-fill","auto-fit","masonry","tiles","row","col","simplegrid","responsive grid","card grid"],usage: {description:- 'CSS Grid-based layout with responsive column support. Use for any grid layout instead of manual CSS grid — it handles gap tokens and responsive behavior automatically.',+ 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',bestPractices: [- { guidance: true, description: 'Use `columns={{minWidth: 280}}` for responsive layouts that adapt to container size with consistent item widths.' },- { guidance: true, description: 'Use `columns={{minWidth: 280, max: 4}}` to set a maximum column count while still allowing responsive wrapping.' },- { guidance: false, description: 'Write manual CSS grid styles when Grid already supports your layout — it ensures consistent spacing through design tokens.' },+ { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size — `columns={{minWidth: 280}}`.' },+ { guidance: true, description: 'Cap the column count with `max` to prevent rows from getting too wide on large screens.' },+ { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },+ { guidance: false, description: 'Write manual CSS grid — Grid handles spacing and responsive behavior for you.' },+ { guidance: false, description: 'Use `XDSHStack` with wrapping for grids — use Grid instead.' },],},theming: {@@ -209,11 +211,14 @@ export const docsZh = {},],usage: {- description: '基于 CSS Grid 的布局组件,支持响应式列。',+ description:+ 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',bestPractices: [- { guidance: true, description: '使用 \`columns={{minWidth: 280}}\` 实现自适应容器宽度的响应式布局。' },- { guidance: true, description: '使用 \`columns={{minWidth: 280, max: 4}}\` 限制最大列数。' },- { guidance: false, description: '当 Grid 已支持你的布局时,不要编写手动 CSS grid 样式。' },+ { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size — `columns={{minWidth: 280}}`.' },+ { guidance: true, description: 'Cap the column count with `max` to prevent rows from getting too wide on large screens.' },+ { guidance: true, description: 'Use `repeat: \'fill\'` (the default) for consistent item widths. Use `\'fit\'` when items should stretch to fill leftover space.' },+ { guidance: false, description: 'Write manual CSS grid — Grid handles spacing and responsive behavior for you.' },+ { guidance: false, description: 'Use `XDSHStack` with wrapping for grids — use Grid instead.' },],},};@@ -222,11 +227,13 @@ export const docsZh = {export const docsDense = {description: 'CSS Grid-based layout w/ responsive column support.',usage: {- description: 'CSS Grid-based layout with responsive column support. Use for any grid layout instead of manual CSS grid.',+ description: 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',bestPractices: [- { guidance: true, description: 'Use columns={{minWidth: 280}} for responsive layouts with consistent widths.' },- { guidance: true, description: 'Use columns={{minWidth: 280, max: 4}} to cap columns while keeping responsive wrapping.' },- { guidance: false, description: 'Write manual CSS grid when Grid supports your layout.' },+ { guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size — columns={{minWidth: 280}}.' },+ { guidance: true, description: 'Cap the column count with max to prevent rows from getting too wide on large screens.' },+ { guidance: true, description: 'Use repeat: \'fill\' (the default) for consistent item widths. Use \'fit\' when items should stretch to fill leftover space.' },+ { guidance: false, description: 'Write manual CSS grid — Grid handles spacing and responsive behavior for you.' },+ { guidance: false, description: 'Use XDSHStack with wrapping for grids — use Grid instead.' },],},