One Spacing Scale

Pick a fixed set of values. Stop improvising each one on the spot.

Every spacing value on the page comes from a single fixed set. Once it's set, spacing is no longer a decision you make each time.

What you'll run into:

• You can't say what's wrong with the page, but it just looks messy
• Two modules have inner padding 2px apart, and it bugs you without a clear reason
• You ask the AI to change one spacing value and it quietly changes others to values of its own

Eyeballed spacing produces a pile of near-but-not-equal values: 11, 13, 14, 15. The differences are too small to look deliberate but large enough to be felt — the result is a vague sense of "a bit messy" that no one can pin down. With a fixed set, spacing differences become meaningful signals: 8 means tightly related, 24 means a different group. This is the law of proximity from Gestalt grouping principles, landed in numbers — things that are close together get perceived as one group, and spacing is its quantifiable form. grouping

Spacing answers one question: are these pieces of content the same thing? The gap between 8 and 24 is quieter than any divider line; once you remove the dividers, this set is what expresses grouping in their place. It's also why visual hierarchy and whitespace-first approaches all assume a spacing scale first — without fixed values, layering has nothing to stand on.

How to pick the set

Five to six values is enough. More is the same as none, because you can always find a "roughly right" one; fewer and you run short, forced to break the rule. A common starting set:

Base 4 or 8 both work; what matters is that the site has exactly one set. Multiples of 4 are more flexible, multiples of 8 look neater; on mobile you usually start at 4 because the screen is small.

How to use it

• Spacing differences should signal relationships. Adjacent levels should differ by at least 1.5x. The gap between 8 and 24 is obvious at a glance; 8 and 12 is ambiguous.
• Vertical spacing matters more than horizontal. People scan pages vertically, so a broken vertical rhythm is what gets noticed first.
• Use variables, don't hardcode. Define them as CSS variables or design tokens — change once, applies everywhere.
• Have a reason for breaking the rule. When you genuinely need a value outside the set, first ask whether the hierarchy itself is unclear.

Verification is simple: shrink a screenshot of the page to 50% and squint. Scaling down strips text detail and leaves the rhythm of the spacing — related elements should cluster, and different groups should stand apart. If it still looks messy at 50%, someone improvised a value. Spacing is one of the easiest things for the AI to generate at random, which is exactly why the set belongs in a constraints file instead of a reminder you give each time.

A note for the AI

Put the spacing spec into the project's constraints file so the AI follows it on every generated screen.

CLAUDE.md · spacing spec

## Spacing

All site spacing must come from this set only; no other numbers are allowed:
4 / 8 / 16 / 24 / 40 / 64 (px)

Usage:
- 4   inside an element, e.g. between an icon and its text
- 8   two tightly related items, e.g. a heading and its body
- 16  items within one group, card inner padding
- 24  between groups, between cards
- 40 / 64  large blocks, page top and bottom margins

Requirements:
- Define as CSS variables (--sp-1 through --sp-6) and reference
  the variables in components; never write raw numbers.
- If a spot seems to need a value not in the set, tell me why
  first; do not invent a middle value on your own.
- Point out any existing code that uses spacing values outside
  the set.

The last line is genuinely useful. Having the AI run a quick health check is much faster than inspecting every value yourself. Spacing and the type scale are two halves of the same idea: once both converge to fixed sets, the page starts to feel ordered.