;\n\nexport const Playground: Story = {};\n\nexport const ThreeColumns: Story = {\n parameters: {\n docs: { description: { story: 'A denser three-up grid; the same children reflow into three `1fr` tracks.' } },\n },\n args: {\n columns: 3,\n gap: 8,\n children: ['One', 'Two', 'Three', 'Four', 'Five', 'Six'].map(label => (\n \n )),\n },\n};\n\nexport const SeparateAxisGaps: Story = {\n parameters: {\n docs: { description: { story: '`gapX`/`gapY` set column and row spacing independently, overriding `gap`.' } },\n },\n args: {\n columns: 2,\n gapX: 20,\n gapY: 8,\n children: items.map(item => ),\n },\n};\n\nexport const WithPadding: Story = {\n parameters: {\n docs: { description: { story: 'Uniform inner padding around the tracks, on the `--cds-space-*` scale.' } },\n },\n args: {\n columns: 2,\n gap: 12,\n padding: 16,\n children: items.map(item => ),\n },\n};\n\nexport const CenterAligned: Story = {\n parameters: {\n docs: {\n description: {\n story: '`align=\"center\"` vertically centers each cell within its row when cells differ in height.',\n },\n },\n },\n args: {\n columns: 2,\n gap: 12,\n align: 'center',\n children: [\n ,\n \n \n
,\n ],\n },\n};\n\nexport const Justify: Story = {\n parameters: {\n docs: {\n description: {\n story:\n 'Wires up `justify` (justify-content). With `1fr` columns the tracks always fill the ' +\n 'container, so this has no visible effect — `justify` only matters if the tracks are sized ' +\n 'smaller than their container. Use `align` for the common case of aligning uneven cells.',\n },\n },\n },\n args: {\n columns: 2,\n gap: 12,\n justify: 'center',\n children: items.map(item => ),\n },\n};\n\nexport const ColumnMatrix: Story = {\n parameters: {\n docs: { description: { story: 'One to four columns side by side to compare tile density at a glance.' } },\n },\n render: () => (\n \n {[1, 2, 3, 4].map(columns => (\n \n \n {`${columns} column${columns === 1 ? '' : 's'}`}\n \n \n {manyItems.slice(0, columns * 2).map(label => (\n \n ))}\n \n \n ))}\n \n ),\n};\n\nexport const GapMatrix: Story = {\n parameters: {\n docs: { description: { story: 'The same 2-column grid at four `--cds-space-*` gap steps, including `0`.' } },\n },\n render: () => (\n \n {([0, 4, 12, 24] as const).map(gap => (\n \n \n {`gap ${gap}`}\n \n \n {items.map(item => (\n \n ))}\n \n \n ))}\n \n ),\n};\n\nexport const ResponsiveMobileWidth: Story = {\n parameters: {\n docs: { description: { story: 'The grid inside a phone-width container to preview tile sizing on device.' } },\n },\n render: () => (\n \n \n {manyItems.map(label => (\n \n ))}\n \n
\n ),\n};\n"
},
"specification": {
"$schema": "../../../specs/component-spec.schema.json",
"identity": {
"name": "Grid",
"status": "preview",
"version": "1.0.0",
"summary": "An equal-width column grid backed by CSS Grid, column-first with token-scale gaps and cell alignment."
},
"parts": [
{
"id": "root",
"label": "Root",
"description": "CSS Grid container. Structural: it arranges children into equal-width columns and paints no surface.",
"required": true
}
],
"allowedDesignChoices": {
"variants": {
"grid": {
"label": "Grid",
"description": "The single equal-width column grid."
}
},
"sizes": {},
"alignments": {
"start": {
"label": "Start"
},
"center": {
"label": "Center"
},
"end": {
"label": "End"
},
"stretch": {
"label": "Stretch"
},
"baseline": {
"label": "Baseline"
}
},
"justifications": {
"start": {
"label": "Start"
},
"center": {
"label": "Center"
},
"end": {
"label": "End"
},
"between": {
"label": "Between"
},
"around": {
"label": "Around"
},
"evenly": {
"label": "Evenly"
}
}
},
"variants": [
{
"id": "grid",
"label": "Grid",
"description": "Equal-width column grid.",
"platforms": [
"ios",
"android",
"web"
]
}
],
"sizes": [],
"measurements": [
{
"id": "track-gap",
"label": "Track gap",
"kind": "example-only",
"token": "--cds-space-12",
"value": 12,
"unit": "px",
"appliesTo": [
"root"
],
"notes": "Representative value: gap, gapX, and gapY are author-configurable and accept any step on the spacing scale. 12 is the value rendered and verified by the Playground story."
}
],
"layout": {
"alignment": "align sets align-items across rows; justify sets justify-content, usually a no-op while columns are 1fr.",
"flow": "Column-first: set the column count and rows fill implicitly as children flow in.",
"notes": [
"Use VStack/HStack for a single-axis flow and Carousel for one-per-view swiping."
]
},
"typographyAndColor": {
"typography": [
{
"label": "Inherited",
"description": "Grid sets no type; children own their text. Ramp noted for parity.",
"token": "--cds-type-body-size"
}
],
"colors": [
{
"label": "Transparent",
"description": "Grid paints no background; the surface behind shows through.",
"token": "--cds-bg-page"
}
]
},
"states": [
{
"id": "default",
"label": "Default",
"description": "Equal-width tracks with a uniform gap."
},
{
"id": "separate-axis-gaps",
"label": "Separate axis gaps",
"description": "gapX and gapY set column and row spacing independently."
},
{
"id": "aligned",
"label": "Aligned",
"description": "align centers uneven cells within their row."
}
],
"behavior": [
{
"label": "Column-first",
"description": "Specify columns; rows are created implicitly as children fill up."
},
{
"label": "Token gaps",
"description": "gap, gapX, and gapY map to the spacing scale."
}
],
"accessibility": [
{
"label": "Presentational",
"description": "Grid is a layout container and adds no roles; order follows DOM order."
},
{
"label": "Reading order",
"description": "Children read in source order regardless of visual columns."
}
],
"contentAdaptation": [
{
"label": "Tile density",
"description": "Change the column count to trade tile size for density."
},
{
"label": "Uneven cells",
"description": "Use align to line up cells of differing height."
}
],
"motionHaptics": {
"motion": [
{
"label": "None",
"description": "Grid does not animate layout changes on its own."
}
],
"haptics": [
{
"label": "None",
"description": "A layout container requests no haptics."
}
]
},
"platformDifferences": []
},
"specification_source": "packages/design-system/src/components/layout/Grid/Grid.spec.json",
"guidance": {
"summary": "An equal-width column grid backed by CSS Grid, column-first with token-scale gaps and cell alignment.",
"guidance": [
{
"heading": "Overview",
"body": "Equal-width column grid backed by CSS Grid (`repeat(columns, 1fr)`). Set the column count and\nrows fill implicitly as children flow in."
},
{
"heading": "When to use",
"body": "Reach for `Grid` when you want a **two-dimensional** layout of uniform tiles — metric cards, a\ndashboard's widget picker, a stat grid. Every column is `1fr`, so tiles share width evenly and\nwrap into new rows automatically.\n\n- Only laying out **one axis** (a column or a row)? Use `VStack` or `HStack` — they are simpler\n and don't force equal widths.\n- Showing **one item per view with swiping**? Use `Carousel`.\n\nBecause tracks are `1fr` and fill the container, `align` (align-items) controls how uneven-height\ncells line up, while `justify` is usually a no-op."
}
],
"usage": [],
"examples": [],
"source": "packages/design-system/src/components/layout/Grid/Grid.mdx",
"status": "local-preview",
"note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification."
},
"links": {
"human": "/component-grid",
"json": "/data/visual/components/grid.json",
"storybook": "/storybook/?path=/story/cloaked-design-system-layout-grid--playground"
}
}