Cloaked Design SystemLayout

Grid

An equal-width column grid backed by CSS Grid, column-first with token-scale gaps and cell alignment.

Implementation preview

COMPLETE STORYBOOK REFERENCE

Every example. In one place.

Explore every named example, including states, compositions, and theme variants.

9 stories

Playground selectedOpen canvas

Example source

packages/design-system/src/components/layout/Grid/Grid.stories.tsxExport Playground

Implementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.

Stories + source JSON ↗

Local specification source status: preview. Implementation preview pending sign-off.

An equal-width column grid backed by CSS Grid, column-first with token-scale gaps and cell alignment.

Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off

Implementation API 1 entry point · source-derived preview

Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.

import { Grid } from '@cloakedinc/design-system';

GridGridProps

packages/design-system/src/components/layout/Grid/Grid.tsx:60

Prop	Type	Presence	Notes
`columns`	`number`	Required	Number of equal-width columns. Produces `repeat(N, 1fr)`.
`gap`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Uniform gap between columns and rows, in `--cds-space-*` steps.
`gapX`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Horizontal gap between columns, overrides `gap`.
`gapY`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Vertical gap between rows, overrides `gap`.
`align`	`StackAlign \| undefined`	Optional	Vertical alignment of items within their cells (`align-items`).
`justify`	`StackJustify \| undefined`	Optional	Horizontal distribution of the grid tracks (`justify-content`).
`as`	`React.ElementType<any, keyof React.JSX.IntrinsicElements> \| undefined`	Optional	Rendered element. Defaults to `div`.Source default: `'div'`
`className`	`string \| undefined`	Optional
`style`	`React.CSSProperties \| undefined`	Optional
`children`	`React.ReactNode`	Optional
`testId`	`string \| undefined`	Optional	Optional test selector, placed on the `as` element.
`padding`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Padding on all four sides.
`paddingX`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Horizontal padding (left + right). Overrides `padding` on the X axis.
`paddingY`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Vertical padding (top + bottom). Overrides `padding` on the Y axis.
`paddingTop`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Top padding. Overrides `paddingY` and `padding`.
`paddingRight`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Right padding. Overrides `paddingX` and `padding`.
`paddingBottom`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Bottom padding. Overrides `paddingY` and `padding`.
`paddingLeft`	`0 \| 4 \| 8 \| 12 \| 16 \| 20 \| 24 \| 32 \| 40 \| 48 \| 56 \| 64 \| 72 \| 80 \| 96 \| 120 \| 240 \| undefined`	Optional	Left padding. Overrides `paddingX` and `padding`.

Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.

Complete contract · JSON ↗Guidance and source · Markdown ↗

Overview

Equal-width column grid backed by CSS Grid (repeat(columns, 1fr)). Set the column count and rows fill implicitly as children flow in.

When to use

Reach for Grid when you want a two-dimensional layout of uniform tiles — metric cards, a dashboard's widget picker, a stat grid. Every column is 1fr, so tiles share width evenly and wrap into new rows automatically.

Only laying out one axis (a column or a row)? Use VStack or HStack — they are simpler and don't force equal widths.
Showing one item per view with swiping? Use Carousel.

Because tracks are 1fr and fill the container, align (align-items) controls how uneven-height cells line up, while justify is usually a no-op.

Component specification

$schema

../../../specs/component-spec.schema.json

Parts

Id: root
Label: Root
Description: CSS Grid container. Structural: it arranges children into equal-width columns and paints no surface.
Required: true

Allowed Design Choices

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

None specified

Measurements

Id: track-gap
Label: Track gap
Kind: example-only
Token: --cds-space-12
Value: 12
Unit: px
Applies To: 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.

Typography And Color

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.

Content Adaptation

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.

Motion Haptics

Motion

Label: None
Description: Grid does not animate layout changes on its own.

Haptics

Label: None
Description: A layout container requests no haptics.

Platform Differences

None specified

Implementation preview

This design-owned implementation is ready to try and review. It does not establish product approval. Imported specifications retain their original review status.

Inspect version 0.2.0-preview.1