Grid

Two-dimensional layouts with Tailwind CSS grid utilities and the 'grid-page' shorthand wrapper component for page layouts.

Installation

Grid layouts use utilities from the @by/experience-system theme (Tailwind) and the cn helper from the same package. Add the package with your package manager:

pnpm add @by/experience-system

Composition

Use the following composition for a typical page or region grid:

Grid region (div)
├── Optional: grid-page (page-level outer margin + default gutters)
├── grid + grid-cols-* + gap-*  (component-level or bespoke layouts)
└── Direct children (col-span-* and responsive col-span utilities)

grid-page bundles display: grid, outer horizontal margin, and default x/y gutters for route-level and dashboard shells. grid with gap-scaled-* is appropriate inside cards, dialogs, and other components. Column templates are always explicit (grid-cols-12, grid-cols-6, and so on). Behavior follows CSS Grid layout and your Tailwind configuration.

Usage

import { cn } from '@by/experience-system';

export function Example() {
  return (
    <div className="grid-page grid-cols-12">
      <section className="col-span-12 md:col-span-8">Main</section>
      <aside className="col-span-12 md:col-span-4">Aside</aside>
    </div>
  );
}

No 'use client' directive is required unless the surrounding module is already a client boundary.

When to use flex vs grid

Use flex for one-dimensional rows or columns (toolbars, button groups, chip lists). Use grid for two-dimensional layouts and anything that relies on column spans (pages, dashboards, form sections).

When to use 'grid-page'

Use the dedicated “grid-page” component from the registry to define a page layout. It contains predefined margins and gutters that are aligned with the experience system page-layout specifications.

MUI Grid migration

MUI Grid (v3)	Tailwind (experience system)
`<Grid container spacing={2}>`	`<div className="grid-page grid-cols-12">`
`<Grid item xs={12} md={6}>`	`<div className="col-span-12 md:col-span-6">`
`<Grid item xs={12} sm={6} md={4} lg={3}>`	`<div className="col-span-12 sm:col-span-6 md:col-span-4 lg:col-span-3">`

For grid-page defaults, overrides, and density tables, see Page grid.

Examples

Basic grid layout

A twelve-column grid with a 3 / 9 split using gap-scaled-3 for gutters.

col-span-3

col-span-9

Sixty forty grid layout

Seven and five columns add to twelve for a 60 / 40 style split.

col-span-7

col-span-5

Quarters layout

Four equal columns (col-span-3 each).

col-span-3

Thirds layout

Three equal columns (col-span-4 each).

col-span-4

Responsive grid layout

Column spans change by breakpoint (sm, md, lg) while the container stays grid-cols-12.

API Reference

This page documents layout utilities, not a React component. grid-page is defined in the Experience System theme; column tracks, spans, and gaps use Tailwind CSS utilities. Full grid property reference lives in the MDN CSS Grid documentation and Tailwind CSS grid.

grid-page

Design-system @utility that bundles page-layout defaults. grid-template-columns is not set; add grid-cols-* on the same element.

CSS property	Default value
display	grid
margin-inline	scaled outer margin (density-aware; equivalent theme spacing to mx-scaled-4)
column-gap	scaled gutter (equivalent to gap-x-scaled-3)
row-gap	scaled gutter (equivalent to gap-y-scaled-3)

Override any single axis with utilities such as mx-0, gap-x-scaled-6, or gap-y-scaled-8 (same specificity; see Page grid).

Tailwind primitives used in examples

Utility / pattern	Role
grid	`display: grid` without page-level grid-page defaults
grid-cols-12	Twelve-column explicit grid
gap-scaled-4	Density-aware gutter between tracks
col-span-*	Track span for a child
sm: / md: / lg:	Responsive prefixes for spans and layout

Accessibility

Structure content with meaningful elements (main, nav, section, headings) inside grid children so the document outline stays clear. Grid is visual layout only; it does not imply roles. Avoid reordering that breaks a logical reading sequence relative to the DOM. See Grid layout and accessibility on MDN.

Source in the repo: packages/experience-system/src/theme/scaled-utilities.css (grid-page). Agent-oriented contracts: packages/experience-system/src/components/Grid/Grid.instructions.md.

On this page