Page grid
Opt-in shorthand for page-layout grids. Bundles display, outer margin, and gutter so consumers do not wire all three by hand.
Page layouts almost always need the same three things together: display: grid, an outer horizontal margin, and an x/y gutter. Writing that triple by hand is repetitive and easy to get wrong.
The grid-page utility is an opt-in shorthand that bundles those three defaults into a single class. grid-template-columns is intentionally left off so consumers vary it freely (grid-cols-12, grid-cols-6, etc.), and standard Tailwind utilities still override individual properties.
// before
<div className="grid grid-cols-12 mx-scaled-4 gap-x-scaled-3 gap-y-scaled-3">
// after
<div className="grid-page grid-cols-12">
// override (standard Tailwind utilities still win)
<div className="grid-page grid-cols-12 mx-0 gap-x-scaled-6">What it bundles
| property | value | equivalent utility |
|---|---|---|
display | grid | grid |
margin-inline | calc(var(--scale-density, 1) * --spacing(4)) | mx-scaled-4 |
column-gap | calc(var(--scale-density, 1) * --spacing(3)) | gap-x-scaled-3 |
row-gap | calc(var(--scale-density, 1) * --spacing(3)) | gap-y-scaled-3 |
All three spacing properties multiply through --scale-density, so the layout tightens automatically across density modes:
| density mode | margin-inline | column-gap / row-gap |
|---|---|---|
standard | 16px | 12px |
compact | 14px | 10.5px |
ultra-compact | 12px | 9px |
Why opt-in (and not a default on the grid class)
display: grid is used internally by several library components — CardHeader, RadioGroup, Alert, Dialog — none of which set a horizontal margin. Applying these defaults to bare .grid would leak into those components and break their layouts (Dialog already uses -mx-scaled-3 to undo inherited margins).
Putting the defaults on a dedicated grid-page class means the page-layout shorthand exists where you want it and nowhere else.
Overrides
Every Tailwind utility ships at the same (0,1,0) specificity, so source order in the emitted CSS decides — not class-attribute order. grid-page writes longhand margin-inline, column-gap, and row-gap, so single-property utilities replace them cleanly:
// drop the outer margin
<div className="grid-page grid-cols-12 mx-0">
// widen the column gap, keep the row gap
<div className="grid-page grid-cols-12 gap-x-scaled-6">
// fully bespoke gutters
<div className="grid-page grid-cols-12 gap-x-scaled-2 gap-y-scaled-8">When to use it
Use grid-page for the outermost grid containers in page-level layouts: dashboard shells, route-level pages, large form sections. Reach for raw grid grid-cols-* gap-*-scaled-* for component-internal grids and small one-off layouts.