Spacing

Spacing is one scale applied at three layers, and most layout problems come from applying it at the wrong one. Sections set the distance between major bands of a page, blocks set the rhythm inside a stack, and containers set width. The utility class names are indexed on the Classes page; this page is the scale itself and the rule about who applies it.

The scale

--space-* tokens alias the unit scale, so re-stepping the units moves every spacing decision on the site at once.

Only eight of these have gap utilities and six have padding utilities. The rest exist for component CSS, which reaches for the token directly.

Section spacing

Sections take their vertical space from a separate set of tokens, deliberately coarser than the block scale so the gap between bands never lands near the gap inside one.

<section class="top-large bottom-large">
  <div class="padding-global">…</div>
</section>

Gap

Inside a block, gap is the only source of vertical spacing. .block > * has its block margins zeroed for exactly this reason: flex gap does not collapse with margins the way margins collapse with each other — it adds to them, so leaving both in place doubles the space.

<div class="block gap-l">
  <h2>Heart Health</h2>
  <p>Medically reviewed</p>
</div>

Padding

.padding-global is the page gutter — 24px on the left and right — and it is what keeps every section's content aligned to the same edge. It belongs on a wrapper inside the section, never on the section itself.

Interaction sizing

var(--target-min) is 44px, and it is a floor rather than a preference. Anything a reader taps — a button, a close control, a chip — must clear it in both dimensions, including when the visible artwork is smaller than the hit area.

• Never shrink a control below 44px to make a layout fit. If the space is too tight, the layout is wrong, not the target.

Safe areas

Four tokens wrap the browser's env() insets so a docked element can clear a notch or a home indicator: --safe-area-top, --safe-area-right, --safe-area-bottom and --safe-area-left. Each falls back to 0px.

padding-bottom: calc(var(--space-m) + var(--safe-area-bottom));

They report a real value only when the document opts in with viewport-fit=cover. This site does not set it, so all four resolve to zero here — the pattern is documented because it costs nothing now and becomes correct the moment the flag is added.

Rules

• Sections control macro spacing, blocks control micro spacing. Mixing them is what produces layouts where two bands are closer together than the lines inside one of them.
• Never apply spacing to a container. Its job is width and centring; padding on a container fights the gutter that .padding-global already sets.
• Never use a spacer div. An empty element to create space is a gap or a section utility that was not reached for.
• Never hardcode a pixel gap. Every step on the scale exists so that a later re-step moves the whole site together.