Every page is built from the same small set of layers, each owning exactly one decision. Sections own vertical rhythm, the gutter owns horizontal inset, containers own width, and blocks own the rhythm inside a stack. Keeping those separate is what makes a layout predictable; the Spacing page covers the scale they apply.
The hierarchy
body
└── section vertical rhythm — .top-* / .bottom-*
└── padding-global the horizontal gutter
└── container width and centring
└── block the content stack
Not every layer carries CSS, and it is worth knowing which do. There is no class at all — the element section carries only display: block, and the .top-* and .bottom-* utilities are what put space on it. Bare has no rule either; only the sized variants do. and are real declarations.
and appear in this site's markup but belong to the docs chrome in assets/docs-kit/docs.css, not to the design system. A page built outside the docs kit does not need them.
Sections
A section is a band of the page. It sets vertical space and nothing else — no padding, no width, no background positioning.
<section class="top-large bottom-large">
<div class="padding-global">
<div class="container-m">
<div class="block gap-l">…</div>
</div>
</div>
</section>
Containers and max-widths
Both cap width. A container also centres itself; a max-width leaves the element where it sits. That is the whole difference, and it is the reason to pick one over the other.
| Container | Max-width | Width | Suits |
|---|---|---|---|
| 480px | A form, or a single column of controls | ||
| 640px | Running text at a comfortable measure | ||
| 960px | The default for an article page | ||
| 1200px | Wide editorial layouts and grids | ||
| 1440px | Full-bleed sections that still need a ceiling |
releases a constraint inherited from above.
Blocks
A block is a flex column with a 12px gap. It is the most-used class in the system, and its job is to stack content at an even rhythm.
Default — gap-m
Horizontal — .row
Every direct child of a block has its block margins zeroed, so gap is the only thing setting vertical space inside one. The Spacing page covers what goes wrong if a margin is used instead.
Alignment
| Class | Effect |
|---|---|
| · · | Cross-axis alignment of the block's children |
| Children fill the cross axis — the default for a column | |
| · | Main-axis distribution |
[data-align="center"] |
Centres the block itself, rather than its contents |
An element being centred by [data-align="center"] needs a width to centre within, so pair it with or a max-width.
Grid
Two columns — the default
Three columns
Four columns, small gap
<div class="grid cols-3 gap-m">…</div>
is two columns unless or says otherwise, and it collapses to a single column at 768px and below — which overrides the column count, so a four-column grid becomes one column rather than two. Note this is not the 959px breakpoint the type scale steps at; the two do not move together.
Rules
- Never mix responsibilities across layers. A section that sets width, or a container that sets padding, has taken a job that belongs to the layer above or below it — and the next person to change either will get a surprise.
- Never bypass a primitive. If a layout needs a stack, it needs a block; hand-rolled flex on a one-off div is how a page stops matching the rest of the site.
- Never use a spacer div. The gap and section utilities exist so that empty elements never have to.
- Do not reach for . It ships as
display: blockand applies no padding despite the name; vertical space comes from.top-*and.bottom-*. - Keep off the section itself. It belongs on a wrapper inside, or the gutter and the section's own vertical padding start fighting.