Layout primitives
Seven small classes that lay out everything between components: stack, cluster, auto-grid, split-2, center, measure and sr-only. Reach for them before writing display: flex or grid by hand.
Usage
Use it when
- You need to place components next to or under each other: a column of cards (
stack), a row of buttons or badges that may wrap (cluster), a grid of tiles that reflows by width (auto-grid). - A page has a narrow side column and a main column that should collapse to one column on tablets and phones (
split-2). - Text or a single block must sit in the middle of its area (
center) or long text must keep a readable line length (measure). - Something must be read by screen readers but not shown (
sr-only): a table behind a chart, "opens in a new tab" after an external link.
Use something else when
- Fields, field pairs and the buttons that end a form: use Form layout.
form,form__rowandform__actionsalready carry the right spacing and the phone behavior. - A page made of titled sections with dividers between them: use Sections.
- The app frame: sidebar, top bar, scrolling main area: use App shell.
- A row of attached buttons acting on one object: use Button group.
clusteronly spaces things; it does not join them. - A horizontally scrolling row of cards: use Carousel.
- Two panes the reader resizes by dragging: use Resizable split.
Where it goes. Anywhere inside a page, nested as deep as needed: a stack of sections, each holding a cluster of actions and an auto-grid of cards. They carry no color, padding or radius, so they never compete with the components inside them. split-2 collapses to one column below 860 px; auto-grid drops columns on its own as the width shrinks.
Examples
--gap, never from margins on the children.Linear Algebra, week 6
Eigenvalues and diagonalization. 4 lessons, 1 quiz.
<div class="stack" style="--gap: 16px; max-width: 520px;">
<div class="stack" style="--gap: 4px;">
<h3 class="section__title-sm">Linear Algebra, week 6</h3>
<p class="card__sub">Eigenvalues and diagonalization. 4 lessons, 1 quiz.</p>
</div>
<div class="cluster">
<span class="badge badge--accent">In progress</span>
<span class="badge">4 of 6 lessons</span>
<span class="badge badge--warning">Quiz due Friday</span>
</div>
<div class="cluster" style="--gap: 10px;">
<button class="btn btn--primary">Continue lesson 5</button>
<button class="btn btn--secondary">Open notes</button>
</div>
</div><div class="auto-grid" style="--min: 200px;"> <div class="card"><div class="card__title">Database Systems</div><div class="card__sub">CS 2104 · 3 credits</div></div> <div class="card"><div class="card__title">Computer Networks</div><div class="card__sub">CS 3102 · 3 credits</div></div> <div class="card"><div class="card__title">Operating Systems</div><div class="card__sub">CS 3001 · 4 credits</div></div> <div class="card"><div class="card__title">Linear Algebra</div><div class="card__sub">MA 2201 · 3 credits</div></div> </div>
Lesson 13: Normal forms
Why splitting a table removes update anomalies, and how to tell when a schema is in third normal form.
<div class="split-2" style="--side: 240px;">
<div class="card card--fill stack" style="--gap: 6px;">
<div class="card__title">Your progress</div>
<div class="card__sub">12 of 20 lessons done</div>
<div class="progress"><span class="progress__fill" style="transform: scaleX(0.6);"></span></div>
</div>
<div class="stack measure">
<h3 class="section__title-sm">Lesson 13: Normal forms</h3>
<p class="card__sub">Why splitting a table removes update anomalies, and how to tell when a schema is in third normal form.</p>
</div>
</div>center puts one block in the middle of its area. sr-only adds words only screen readers hear.You finished every lesson this week
See next week's plan (opens in a new tab)<div class="center" style="min-height: 180px;">
<div class="stack" style="--gap: 8px; align-items: center;">
<span class="ic ic--lg" aria-hidden="true">school</span>
<p class="card__title">You finished every lesson this week</p>
<a class="link link--external" href="https://example.com" target="_blank" rel="noreferrer">See next week's plan<span class="sr-only"> (opens in a new tab)</span></a>
</div>
</div>Anatomy
| Part | What it is |
|---|---|
.stack | Vertical flow. gap defaults to 12 px; set --gap inline (style="--gap: 20px") for groups (20 to 28) or sections (48). |
.cluster | Horizontal row that wraps, items centered on the cross axis. --gap defaults to 8 px. |
.auto-grid | As many equal columns as fit, each at least --min wide (default 240 px), never wider than the container. --gap defaults to 12 px. |
.split-2 | Two columns: a side column --side wide (default 320 px) and a main column that takes the rest. --gap defaults to 28 px. One column below 860 px. |
.center | Grid that centers its child on both axes and centers text. |
.measure | Caps width at --size-measure (680 px), about 70 characters of body text. |
.sr-only | Visually hidden, still in the accessibility tree. |
Variants and sizes
| Class or attribute | When |
|---|---|
--gap | Spacing on stack, cluster, auto-grid, split-2. Stay on the 4 px grid: 8 to 12 for related items, 20 to 28 for groups, 48 for sections. |
--min | auto-grid only: the narrowest a column may get before the grid drops a column. 160 for small tiles, 240 for cards, 320 for wide cards. |
--side | split-2 only: the side column width. |
Motion and microinteractions
- None. Layout primitives never animate. When the children change, use list stagger for arrivals or height expand for growth inside them.
- Reflow on resize is instant by design; do not add
transitionongrid-template-columns.
Accessibility
- They change only visual placement. Keep the DOM order the reading order:
split-2puts the side column first in the source, so put the content that should be read first there, or swap the columns. - Never use
orderorflex-direction: row-reverseto rearrange content inside them; keyboard focus follows the source, not the screen. sr-onlycontent is announced and is part of the accessible name of its parent link or button. Do not put focusable elements inside it.- Use headings and landmarks (
<main>,<nav>,<section aria-labelledby>) for structure; astackis just a<div>.
Do and don't
Do
- Set spacing with
--gapon the parent instead of margins on the children. - Nest primitives: a
stackofclusters, anauto-gridinside asplit-2main column. - Put
min-width: 0on custom children of your own grids; the primitives already do it for theirs.
Don't
- Write a new
.my-row { display: flex; gap: 12px }class whenclusterdoes the job. - Use
auto-gridfor a form; fields need form layout so labels and errors line up. - Add backgrounds, padding or radius to a primitive. Wrap the content in a card instead.