Foundations

Spacing

One ladder for margin, padding and gap, named by value — --space-16 is always 16px. The step size changes once:

20px and below — 2px steps. Small spacing does optical work (icon gaps, label offsets, control padding) where 4px is too coarse and 2px is the real resolution.
Above 20px — 4px steps. Nothing at this scale needs that fineness, so the grid doubles and the ladder stays short.

The ladder. Derived from the codebase rather than imposed on it — 726 of 727 spacing uses across both projects already obeyed the rule. Every step is in use; legal-but-unused values (52, 68, 76, 84 …) get added on demand. Emitted in rem, and the px column is measured off each rendered bar rather than restated.

TokenRenderedScaleUsage

2 px steps — optical range

--space-0

Reset.

--space-2

Hairline nudge, icon offset.

--space-4

Tightest gap.

--space-6

Icon / label gap.

--space-8

Inline gap.

--space-10

Control padding.

--space-12

List-item rhythm.

--space-14

Control padding, meta rhythm.

--space-16

Default block gap — the workhorse.

--space-18

Rare — list indent.

--space-20

Paragraph rhythm, card padding.

4 px steps — structural range

--space-24

Block gap, card padding.

--space-28

Block gap.

--space-32

Group gap.

--space-36

Group gap.

--space-40

Group gap, page gutter max.

--space-44

Footer padding.

--space-48

Group gap.

--space-56

Block separation.

--space-60

Hero page bottom.

--space-64

Block separation.

--space-72

Section gap.

--space-80

Section gap, page bottom.

--space-88

Page top — standard, mobile.

--space-96

Section gap, page top — index, mobile.

--space-104

Page top — hero, mobile.

--space-112

Section gap.

--space-120

Section gap, page top — standard, desktop.

--space-128

Section gap.

--space-140

Page top — index, desktop.

--space-156

Page top — hero, desktop.

--space-160

Widest section gap.

Three families, grouped by what the space DOES: inset inside a container, stack between vertical siblings, inline between horizontal ones. Each is an intent-grouped pass-through to the ladder, so components never bind to a raw value. Derived, not imposed — the steps are the values the designs already used; legal ladder values that no family needs are deliberately absent.

TokenRenderedScaleUsage

Inset — space inside a container, between its boundary and its contents

--spacing-inset-3xs

Tabs track.

--spacing-inset-2xs

Badge block.

--spacing-inset-xs

Control block. Also the surround.

--spacing-inset-sm

Control inline, badge inline, table row.

--spacing-inset-md

Frame.

--spacing-inset-lg

Large control inline — the pill link.

--spacing-inset-xl

Medium container.

--spacing-inset-2xl

Panel — canvas and the documentation cards. Also the band.

--spacing-inset-3xl

Card — work-card, work-stack, variant-card.

Stack — vertical space between sibling elements

--spacing-stack-3xs

Tightest pairing — table row internals.

--spacing-stack-2xs

A label above its value.

--spacing-stack-xs

Coupled siblings — items in a list.

--spacing-stack-sm

Default rhythm, and the figure→caption gap. 64 uses — the most common vertical value in either project.

--spacing-stack-md

Between content blocks. 59 uses.

--spacing-stack-lg

Group separation. 35 uses.

--spacing-stack-xl

Major group separation. 45 uses.

--spacing-stack-2xl

Subsection break. 37 uses. Above this is section rhythm, which belongs to the semantic tier.

Inline — horizontal space between sibling elements

--spacing-inline-3xs

Tightest horizontal cluster.

--spacing-inline-2xs

Items inside a pill track.

--spacing-inline-xs

Small cluster.

--spacing-inline-sm

An icon and the label it belongs to.

--spacing-inline-md

General small gap.

--spacing-inline-lg

Carousel items.

--spacing-inline-xl

Table columns.

--spacing-inline-2xl

Page columns.

A family says how much, not which way. A CSS variable holds one value and cannot enforce an axis — --spacing-stack-md will happily generate px-stack-md. That is why direction lives one tier down, on the component tokens, mirroring Figma’s padding.inline / padding.block. The three families here are vocabulary for size; the component tier is where an axis gets chosen.

Where direction is chosen and where a relationship gets a name. Each of these binds to an alias step above — nothing here invents a value. Two kinds live side by side: a component’s own padding, and the gap between two things that belong together, which is a judgement about coupling rather than a size.

TokenRenderedScaleUsage

Controls — a label with room around it

--spacing-control-inline

A label's breathing room, left and right. Nav link, tab.

--spacing-control-block

The same, top and bottom.

--spacing-control-lg-inline

Pill link and case-study navigation, left and right.

--spacing-control-lg-block

The same, top and bottom.

--spacing-badge-inline

Frame badge, left and right.

--spacing-badge-block

Tighter than a control's — an uppercase micro-label has no descender room to protect.

Surrounds and bands

--spacing-surround

What a container shows AROUND a child that has its own inset — the nav pill, the tabs track. Even on all four sides: this is how much chrome you see, not how much room a label gets.

--spacing-band

Content inset from its own border-y, rather than from a surface. Meta and stat-row.

Tables and containers

--spacing-table-row-inline

Documentation table rows.

--spacing-table-row-block

The same, top and bottom.

--spacing-table-column

Between table columns. All four tables already agreed on this.

--spacing-frame

Frame.

--spacing-panel

Canvas and the documentation cards.

--spacing-card

Work-card, work-stack, variant-card.

Named relationships — how tightly two things belong together

--spacing-figure-caption

A figure and its caption. Lands on default rhythm: a figure sits 120px from the next content, so the caption stays unambiguously grouped with its image.

--spacing-list-item

Items in a vertical list — sticky-toc links, work-stack cards.

--spacing-label-value

A label and the value it introduces.

--spacing-icon-label

An icon and its label. The most consistent gap in either project — written the same way eight times, never otherwise.

--spacing-track-item

Siblings inside a pill track — nav links, tabs.

Navigation column — measurements the scale has no opinion about

--spacing-sidebar-rail

The navigation column's width, and the offset the page beside it carries. Written once so the two cannot drift.

--spacing-sidebar-sheet

The same tree as a drawer over the page, below lg.

--spacing-sidebar-bar

The phone bar that opens the drawer.

On the px-control-inline stutter. Tailwind’s axis prefix plus the token’s own axis name reads twice, the same way text-text-primary does. It is kept on purpose: it leaves the CSS variable readable on its own and keeps the Figma names exact.