Spacing
Closer means more related. Space groups. Air lets the eye scan. Do not invent a gap. Pick a role.
Two layers
Primitives are the raw steps on the ladder. Semantic roles are what you use in views. Raw pixels are an exception or a mistake.
- Primitives. Seven steps: 4, 8, 16, 24, 48, 80, 120. They exist so a value is not written twice.
- Roles.
tight,related,grouped, and the rest. Use these in layout. If you write a rawmarginorpaddingin a view, you are in an exception that needs a note, or you made a mistake.
The ladder
Each role maps to one primitive. The names describe relationship, not decoration.
| Role | px | Use |
|---|---|---|
tight | 4 | Caption under a chip, kicker under a title, tight pairs. |
related | 8 | Heading to lede, list items, labels after chips, table cells. |
grouped | 16 | Paragraphs in a section, swatch rows, pulse plates. |
inset | 24 | Subsection heading top, specimen stack, logo to nav. |
section | 48 | Between doc sections, nav groups, mobile sidebar padding. |
gutter | 80 | Page gutter between sidebar and main. |
canvas | 120 | Top and bottom canvas padding on docs pages. |
Bar specimen
| Role | px | Bar |
|---|---|---|
tight | 4px | |
related | 8px | |
grouped | 16px | |
inset | 24px | |
section | 48px | |
gutter | 80px | |
canvas | 120px |
Composition rules
Spacing is about what belongs together. These rules keep rhythm consistent across pages.
- Heading owns its paragraph. Use
relatedbetween a title and the lede that follows. - Paragraphs in a section. Use
groupedbetween body paragraphs. - Next section. Use
sectionbefore a new h2 block. - Figure owns caption. Use
tightbetween a chip and its caption. - Heavy figure, then next section. A pulse plate or large swatch row already carries weight. The section margin provides the air before the next heading.
What this site uses
Root docs, the letter, and the nav use these seven roles. There is no second set of gaps for chrome versus content.
On the web, roles map to --space-* CSS variables in globals.css. The catalog lives in lib/root-tokens.ts.
iOS
The same seven names exist as points in NTCSpace. Space next to text uses @ScaledMetric so Dynamic Type can scale it. There is no second iOS ladder.
Open questions
Keep the set small. A new gap is either a missing role or a mistake. If you reach for 12, 20, or 32, stop and pick the nearest role.
Source: lib/root-tokens.ts for the catalog; CSS --space-* for web; optional Swift NTCSpace for native.