Managing Outer Spacing

Managing outer spacing in components with a clean approach that separates layout concerns from component design

TL;DR

• Outer spacing is a layout concern, not a component one.

• Base components export zero external margins.

• Use padding tokens inside components and gap tokens in layout primitives.

• Provide margin utilities only as controlled exceptions, outside base components.

• Migrate by auditing margins on roots, refactoring to layout primitives, and tokenizing values.

Code examples and Implementation details are for paid subscribers only 🔒

Upgrade to access the full guide

What is outer spacing

Outer spacing is the external space separating a component from neighboring elements. It shouldn’t be part of the component but a layout decision.

Baseline rule: the component does not carry external margins. The layout decides distances between components.

Why avoid external margins on components

1. Ambiguous responsibility

The component does not know the context in which it will be used, making it impossible to predict the appropriate external spacing needed. When designed for one context, it often fails in others, leading to layout inconsistencies.

2. Margin stacking

Placing two components with margins doubles the space between them, creating visual imbalance. This leads to either too much whitespace or requires developers to manually adjust and override the default spacing, defeating the purpose of having consistent components.

3. Edge cases and overrides

You need exceptions, utilities, and hacks to handle edge cases when the predefined margins don’t suit the layout requirements. This creates a maintenance burden, increases CSS specificity battles, and complicates the codebase with one-off overrides that are difficult to track and document.

4. Separating roles

Though it may seem redundant, separating space management by specific roles is essential: margin, padding, grid gap, and global layout space. Each needs its own specific or semantic tokens, all derived from the same global spacing scale.

Usage rules

1. No margins on base components: cards, buttons, tags, alerts (and so on) do not define external space.

2. Padding only inside: components use {component}-padding-* or spacing-* tokens, depending on your needs.

3. Space between components via layout: stacks, grids, lists use semantic (or alias) tokens.

4. Margin utilities as a controlled exception: enabled but outside base components, for edge cases. Avoid baking them into the component.

Let’s see in action

Let’s now examine how to implement these principles in practice.

The following code examples demonstrate:

1. How to set spacing scale in tokens definitions (JSON); ****

2. How to map tokens to CSS Custom Properties;

3. How to separate responsibilites in CSS.