Skip to content

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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.tsx
index 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.mjs
index 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.' },
],
},