Spacing system

Spacing in a token-driven design system is a two-unit primitive problem, not a one-number guess. A token-driven system declares a minor unit (the smallest legal increment) and a major unit (the dominant rhythm), with the constraint that the major divides cleanly by the minor. Everything downstream — padding, gap, icon size, component height, border radius — derives from those two numbers.

When to use

• Designing a new spacing scale from a density brief.
• Auditing an existing scale with one-off off-grid values.
• Picking unit primitives for a density mode (dense / balanced / spacious).
• Code review: flag raw px values for padding / gap / margin outside the system's declared scale.

When NOT to use

• No token layer on disk — no unit primitives declared anywhere, so there is no grid to be off of. A marketing surface built inside a system that has declared primitives is still in scope.
• Print-design contexts where the grid math is pt-based and a different system applies.

The two-unit primitive model

A token-driven system declares two unit primitives per foundation theme:

Constraint: major mod minor == 0. Both default to 4 when not split (single-unit systems collapse to minor == major).

Different density briefs pick different unit pairs — a dense data tool wants a smaller minor unit than a spacious marketing surface, so the same derivation rule yields a 2/4, 4/8, or 4/16 pairing depending on the brief. One system's concrete density-mode unit choices live in udts-spacing-defaults (an incubating L2 stub).

What derives from the unit primitives

Every secondary scale derives from the two units. Designers and developers don't invent these — the system generates them.

Padding ladder

Generated from the major unit, with minor steps for tight cases:

padding-0       = 0
padding-2xs     = minor                  (e.g. 4)
padding-xs      = major                  (e.g. 8)
padding-sm      = 1.5 × major            (e.g. 12)
padding-md      = 2 × major              (e.g. 16)
padding-lg      = 3 × major              (e.g. 24)
padding-xl      = 4 × major              (e.g. 32)
padding-2xl     = 6 × major              (e.g. 48)
padding-3xl     = 8 × major              (e.g. 64)

Gap ladder

Same ladder as padding, separately labeled (gap-*) because horizontal and vertical gaps may diverge in some themes. The major-unit base ensures stacked rhythm preserves baselines.

Icon-size ladder

Curated, not derived — component-sizing-principles owns the curated set, the reasoning, and the rule that pairs an icon size with a control height.

Component-height ladder

Curated per density mode, with the 24 CSS px WCAG 2.5.8 AA Pointer Target floor for interactive controls (anything clickable / tappable / focusable). See component-sizing-principles for the per-density ladder.

Border-radius ladder

Radius snaps to the minor unit like every other ladder here, but how many rungs and how fast they grow is the system's own personality call, not a universal formula — a sharp-cornered enterprise tool and a soft-cornered consumer app can share the same unit primitives and still diverge completely on radius. Two endpoints are universal regardless of personality: radius-pill (9999, fully-rounded) and radius-circle (50%, relative, for circular elements). One worked ladder between 0 and those endpoints lands in udts-spacing-defaults once that stub stabilizes.

Naming: T-shirt OR numeric

Emit both sets of names and let consumers pick the family that fits their codebase convention:

Emit both in DTCG with cross-aliases. Pick the family that fits your codebase, not "the correct one" — there isn't one.

The WCAG 2.5.8 AA Pointer Target floor

Any interactive control's minimum height is 24 CSS px for AA conformance. The smallest rung in the component-height ladder is reserved for non-interactive elements (badges, read-only chips, density tags); interactive controls start at the first rung that clears the 24 px floor.

Failing this is one of the most common WCAG 2.2 misses in design systems. The skill exists partly to make the rule load-bearing.

Verification

After picking unit primitives + emitting ladders:

1. Divisibility: major mod minor == 0. If not, the system is malformed.
2. Grid alignment: every padding, gap, and component-height token is a multiple of the minor unit.
3. Pointer target: every interactive component-height rung is ≥ 24 CSS px.
4. Naming sync: if both T-shirt and numeric families are emitted, every value has a matching pair in both. No orphans.
5. Icon-size curation: icon sizes match component-sizing-principles's curated set, not a formula output.

Cross-references

• Routed here by: designing-a-design-system — the L1 dispatcher for building or extending a system.
• REQUIRED BACKGROUND for height + font + icon pairing: component-sizing-principles — the curated per-density component-height ladder + font-pairing + icon-size pairing.
• For the typography scale that pairs with spacing: type-scale and line-height-grid — line-heights snap to the minor unit declared here.
• For one system's concrete density-mode unit choices (worked example): udts-spacing-defaults — an incubating L2 stub that instantiates this model.

Sources

• WCAG 2.5.8 — Target Size (AA, added in 2.2) — the 24 CSS px floor.
• One system's concrete density-mode unit choices: udts-spacing-defaults (incubating).