# Grid

> Lays content out in responsive columns with system gaps.

- **Level**: atom · **Status**: stable · **Role**: surface
- **Import**: `import { Grid, GridItem } from "@rrios-forge/ui/atoms/grid";`
- **Source**: `packages/ui/src/atoms/grid`

Layout primitive that owns the column system. Track mode defines a fixed column count (optionally per breakpoint); fluid mode lets `auto-fit` tracks adapt to the container width using a min-track token.

## Use it for

- Responsive grid / max-width container → `Grid` / `Container`

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `gap` | — | `none` `xs` `sm` `md` `lg` `xl` | `md` | Spacing between grid items. |
| `rowGap` | — | `none` `xs` `sm` `md` `lg` `xl` | `md` | Spacing between grid rows. |
| `alignX` | — | `start` `center` `end` `stretch` | `stretch` | Inline-axis alignment of grid items. |
| `alignY` | — | `start` `center` `end` `stretch` `baseline` | `stretch` | Block-axis alignment of grid items. |
| `dense` | — | `true` `false` | `false` | Grid packs items densely. |

## Stories

- [Playground](/?path=/story/components-atoms-grid--playground) · frame: `/iframe.html?id=components-atoms-grid--playground&viewMode=story`
- [Track — fixed columns](/?path=/story/components-atoms-grid--track) · frame: `/iframe.html?id=components-atoms-grid--track&viewMode=story`
- [Responsive — per-breakpoint columns](/?path=/story/components-atoms-grid--responsive) · frame: `/iframe.html?id=components-atoms-grid--responsive&viewMode=story`
- [Fluid — auto-fit tracks](/?path=/story/components-atoms-grid--fluid) · frame: `/iframe.html?id=components-atoms-grid--fluid&viewMode=story`
- [Independent row + column gap](/?path=/story/components-atoms-grid--row-gap) · frame: `/iframe.html?id=components-atoms-grid--row-gap&viewMode=story`
- [Dense packing](/?path=/story/components-atoms-grid--dense) · frame: `/iframe.html?id=components-atoms-grid--dense&viewMode=story`
- [AlignX — items horizontal](/?path=/story/components-atoms-grid--align-x) · frame: `/iframe.html?id=components-atoms-grid--align-x&viewMode=story`
- [Grid.Item · responsive span](/?path=/story/components-atoms-grid--span-responsive) · frame: `/iframe.html?id=components-atoms-grid--span-responsive&viewMode=story`
- [Dashboard composition](/?path=/story/components-atoms-grid--dashboard-layout) · frame: `/iframe.html?id=components-atoms-grid--dashboard-layout&viewMode=story`
- [Loading skeleton](/?path=/story/components-atoms-grid--loading-state) · frame: `/iframe.html?id=components-atoms-grid--loading-state&viewMode=story`

## Decisions that name it

- ADR-008 — Layout layer: refined `Grid` + new `Container`

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).