Spacing

Principles

Adapted from Fluent 2's spacing and proximity guidance. Proximity is the headline idea — see the demo below.

1. 01

   Proximity signals relationship

   Elements placed close together read as related. Elements separated by more space read as distinct. Use spacing — not borders or boxes — as the first tool to group content.

2. 02

   Hierarchy comes from spacing before size

   Generous space around an element promotes it; tight space embeds it. Reach for spacing before increasing font size or weight to signal importance.

3. 03

   Whitespace is content

   Density makes scanning hard and signals "everything is equally important," which is rarely true. Default to more whitespace; reduce only when there is a specific reason.

4. 04

   Consistency creates rhythm

   Use the same value for the same purpose every time. Two cards in a row should have identical inset padding; two paragraphs in a sequence should have identical stack gap.

Proximity in action

The same content, at three different stack values. As the gap grows, the items stop reading as a related group.

The ramp

Base unit: 4px. Eleven steps. Token names use the multiplier (e.g., spacing.4 = 4 × 4px = 16px). Click any row to copy its CSS variable.

Semantic categories

Five purpose-driven groups alias the global ramp. Use semantic tokens in components and pages whenever a purpose-fit alias exists. Drop to global spacing.N only when no alias matches.

inset — padding inside a component

Roughly maps to Fluent's “Component spacing.”

inline — horizontal gap between siblings

stack — vertical gap between siblings

With inline, this covers what Fluent calls “Pattern spacing.”

content.gap & section.gap — layout rhythm

These cover what Fluent calls “Layout spacing.”

Which token do I reach for?

A four-step flow for picking a value. Most of the time the answer falls out at step 1 or 2.

1. 1
   Is there a semantic alias? Use it. spacing.inset.md over spacing.4.
2. 2
   Is the relationship tight, normal, or loose? Pick the corresponding xs / sm / md / lg.
3. 3
   Is the value ≥ 32px? It is probably a layout concern — use content.gap or section.gap, not inset or stack.
4. 4
   None of the above fits? Drop to the global ramp (spacing.N). If the value isn't in the ramp, the design probably needs another look.

Worked example: a card

• Padding inside the card → spacing.inset.md (16px).
• Gap between card title and body → spacing.stack.xs (4px) — tight, they're closely related.
• Gap between body and the action row → spacing.stack.md (16px) — the action is distinct.
• Gap between cards in a grid → spacing.content.gap (16px).
• Gap between a card row and the next section heading → spacing.section.gap (48px).

Touch targets

Spacing on its own can produce interactive elements that are too small to tap reliably on touch devices. Independent of token values, every interactive element must hit the platform minimums.

Usage guidelines

Using the system

Card with inset padding and internal stack

.card {
  padding: var(--spacing-inset-md);
  display: flex;
  flex-direction: column;
  gap: var(--spacing-stack-md);
}

.cardTitle { /* tight to the body */ margin-bottom: var(--spacing-stack-xs); }

Form with vertical rhythm

.formField {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-stack-xs); /* label tight to input */
}

.form {
  display: flex;
  flex-direction: column;
  gap: var(--spacing-stack-md); /* fields stacked normally */
}

Page-level rhythm

.section {
  margin-bottom: var(--spacing-section-gap); /* 48px between H2s */
}

.sectionContent {
  display: grid;
  gap: var(--spacing-content-gap); /* 16px between blocks */
}