Spacing

Spacing tokens define distance, not intent. They are reused for gaps, padding, and margins depending on context. For the full list of spacing token values, see the Tokens page.

The system is built in layers: unit tokens (raw values) → space tokens (semantic aliases) → utility classes (applied in HTML). Always use space tokens or utility classes, never hardcode pixel values.

Space Scale

The space scale provides a visual reference for the spacing tokens used throughout the system.

padding: var(--space-m);
gap: var(--space-xl);
margin-bottom: var(--space-l);

Gap

Gap modifiers control the space between child elements inside a .block. The default gap is var(--space-m).

<div class="block gap-l">
  <div>Item one</div>
  <div>Item two</div>
  <div>Item three</div>
</div>

Padding

Padding utilities apply internal spacing to an element on all sides.

<div class="padding-l">
  <!-- Content with large padding on all sides -->
</div>

Section Spacing

Section spacing controls the vertical rhythm between major page sections. Apply .top-* and .bottom-* classes to <section> elements. These scale responsively between desktop and mobile.

<section class="top-medium bottom-medium">
  <!-- Section content -->
</section>

Interaction Sizing

A control can be smaller than a fingertip; its hit area cannot.
--target-min names the floor: 44px — WCAG 2.5.5 Target Size (Enhanced),
Level AAA, and the Apple HIG target. The AA floor is 2.5.8's 24px (a
WCAG 2.2 criterion), which every control in the system clears. Apply the
token as a min-width / min-height on small standalone controls: the
visual size stays, the hit area pads out. It is an accessibility floor, not
a per-theme override surface — brands never re-point it.

Dense chrome is the deliberate exception. Bordered controls inside a Bar
hold --bar-control-height (36px) and answer 2.5.8 instead — a toolbar and
a form on a phone are not the same problem. The native checkbox and radio
sit at the 24px floor exactly, extended in practice by their labels.

The password toggle is the system's own precedent — a small icon control
whose hit area pads out to the floor while the icon stays its size:

.password-toggle {
  min-width: var(--target-min);
  min-height: var(--target-min);
}

Safe-Area Insets

On an installed or standalone app surface, the device claims parts of the
screen — the notch, the home indicator. The safe-area tokens wrap
env(safe-area-inset-*) with a 0px fallback, so composing them is safe
everywhere: in a normal browser tab they resolve to zero and the layout is
unchanged.

Compose them with spacing tokens rather than replacing them — the inset is
the device's share, the space token is yours:

.app-footer {
  padding-bottom: calc(var(--space-m) + var(--safe-area-bottom));
}

.edge-drawer {
  padding-inline-start: calc(var(--space-l) + var(--safe-area-left));
}

This is interaction sizing as much as visual clearance: a control anchored
to a screen edge that ignores the inset parks its tap target inside the
system gesture zones, where the OS contests the press — the effective
target shrinks below the floor --target-min names.

The insets are only non-zero when the page's viewport meta opts in with
viewport-fit=cover. Without it the browser letterboxes the page clear of
the cutouts and the tokens stay at zero.