Visual guide

Smaller gaps imply a stronger relationship. Keep the relative hierarchy when you nest: set a local --gap on the inner rhythm rather than letting one inherited value flatten every level.

Before adding a divider, check whether more space already draws the boundary. Chrome is what you add when spacing genuinely cannot carry the meaning — not the first move.

The rules on the left are plain <hr> elements inside a .stack, and their spacing comes from the stack's --gap, not from their own margin: a layout primitive owns the distance between its children. Outside a layout, an hr keeps its own block rhythm and --hr-space tunes it.

Components own their internal rhythm; layout owns the relationships between components. This is why the layout primitives reset the block margins of their direct children — the distance between two siblings belongs to their parent.

--gap is inherited. A region that composes several primitives sets its own rhythm on the gap property, because setting the token would re-space every nested stack, cluster and grid at any depth.

The cluster is the row: actions, tags, a row of links. On a ul, ol or menu it removes the markers and the indent and keeps the list for assistive technology, so no separate "actions" or "nav" class is needed.

Alignment is a utility on that one row — .justify-content-space-between for a split, .items-baseline when a price and its period should share a text line rather than a box center. The hooks (--cluster-justify, --cluster-align, --cluster-wrap) belong to the row they are set on and stop at every nested cluster: set one on a recipe class composed onto that row.

Use .grid for collections where an incomplete final row is fine: cards, products, results, galleries. Use .switcher for peer regions that only make sense side by side or not at all.

The chain is 6 → 3 → 2 → 1: six columns again at 64rem, and one column below 28rem. .grid-4 goes 4 → 2 → 1, .grid-3 goes 3 → 1. Do not fill in the missing integers: they are exactly the states that produce a 5 + 1 row.

Subdivision is keyed on an ancestor named actual-container — the .container-query wrapper around each grid above, sized so the query measures exactly the width its label claims. Without such an ancestor the responsive baseline still applies; the container only adds precision.

.center is content-box sized, so --center-pad adds gutters outside the measure instead of eating into it. Put .measure on the prose, not on the page wrapper — a dashboard column and a paragraph do not want the same limit.

The card keeps its padding and pins its footer to the bottom; the header becomes a .media row and the footer a .cluster pushed to the end. A bare <header> or <footer> still gets a split row by default — it yields to whatever you put on it.

.form-actions is a role, not a layout: the cluster owns the row, the role adds the form's alignment policy and its sticky variant. The distance to the fields comes from the form's .stack, never from a margin on the row.

.tight and .loose set --gap and nothing else. The token is inherited, so the nested cluster closes up too — the whole fragment keeps one rhythm. Put one rhythm class on an element; a nested one wins, exactly like density.

Controls consume --control-size and --control-pad-x, so a compact button is shorter and narrower; the spacing helpers and .choice-card consume --density-space; layout primitives consume --gap. Nothing consumes a fifth thing, which is why density stays predictable.

.tight and .loose write the first row of this table and leave the others alone. That is the entire difference between rhythm and density.

Both rows sit on the same gap. Only the right one also shrinks its controls, because density is a statement about the whole region, not about the space between its items.

Ask what the design changed. Items closer together, everything else as drawn: .tight. A denser workspace — toolbar, table filters, an admin side panel: .compact. Reaching for .compact to fix a gap is how buttons end up smaller than anyone asked for.

A density context is about how much room a region has. A .sm or .lg is about what one component is for: a small button is a smaller thing, label included.

Geometry and rhythm — controls, spacing helpers, layout primitives.

Rhythm only — content rows such as .list: the size holds, the inner gap follows. For these, .compact and .tight look the same.

No effect — badge, alert, card, dialog, table, accordion, navbar. Inline choices (.check, .radio, .switch) are a no-op too, and deliberately: they sit on a line of text, so shrinking the box without the label would break the alignment density was never asked to change.

No !important, no specificity trick: the size class is declared on the sized element, the density on an ancestor, and the nearer declaration is the one that resolves.

The left column has three measurements and no relationships: 7, 13 and 19 all mean "a bit of space", and none of them will ever line up with anything else on the page. The right column has two, and the fact that the third gap is the larger one is the whole message. Those two steps have names: .tight and .loose.

Tune a dimension where it is consumed — a rhythm class or --gap on the layout instance, --density-space on the spacing helper — rather than writing a raw value or adding one more family of utility classes for everyone else to learn.