Spacing

Spacing

Standard uses a 4px base unit for all spacing. This isn’t arbitrary — it’s the smallest value that remains visible at 1x density, divides evenly at 2x and 3x screen densities, and aligns to the pixel grid at every common resolution. Every spacing decision in the system is a multiple of 4.

The result: components breathe consistently, layouts feel unified, and the invisible grid that holds everything together stays invisible — which is exactly how you know it’s working.

Why 4px?

Four pixels sits at the intersection of three constraints:

Pixel Grids
4 divides cleanly into every common screen density. At 1x: 4px. At 1.5x: 6px. At 2x: 8px. At 3x: 12px. No sub-pixel rendering, no blurry edges.
Touch Targets
The minimum touch target (44–48px) is exactly 11–12 base units. Comfortable targets build naturally from the scale without awkward math.
Optical Alignment
4px is small enough for fine optical adjustments (icon-to-text gaps) yet large enough that each step creates a visible difference.

The Scale

Token Value Pixels Common Usage
--space-1 0.25rem 4px Icon gaps, tight padding
--space-2 0.5rem 8px Button padding, small gaps
--space-3 0.75rem 12px Input padding, list spacing
--space-4 1rem 16px Card padding, standard gaps
--space-5 1.25rem 20px Section spacing
--space-6 1.5rem 24px Component margins
--space-8 2rem 32px Large gaps, section breaks
--space-12 3rem 48px Page sections, hero spacing
--space-1
4px
--space-2
8px
--space-3
12px
--space-4
16px
--space-5
20px
--space-6
24px
--space-8
32px
--space-12
48px

The Math — Why These Steps?

The scale isn’t a linear progression (1, 2, 3, 4, 5, 6, 7, 8…). It’s curated — some steps are skipped deliberately:

1
2
3
4
5
6
7
8
9
10
11
12

The faded bars are skipped steps (7, 9, 10, 11). Why?

  • Steps 1–6 cover micro to meso spacing. At small sizes, every 4px matters — the difference between 16px and 20px padding is meaningful.
  • Steps 7, 9, 10, 11 are skipped because at larger sizes the perceptual difference between adjacent steps shrinks. 28px vs 32px? Barely noticeable. The eye groups them together.
  • Steps 8 and 12 are kept as landmark values — doubling points that create clear jumps for section-level spacing.

This follows Weber’s Law: the just-noticeable difference in spacing is proportional to the base size. At small sizes you need fine control; at large sizes you need bigger jumps.

Spatial Hierarchy

Spacing isn’t just “how much room” — it communicates relationships. Closer things are related; farther things are separate. Standard’s scale maps to three spatial levels:

Macro · space-8 to space-12
Page Section
Meso · space-4 to space-6
Card Title
Description text with comfortable spacing between elements.
Micro · space-1 to space-3
Icon + text
Another Card
The gap between cards (space-6) is larger than the gap within cards (space-2 to space-4).
Tag Tag
Level Tokens Purpose
Micro space-1, space-2, space-3 Within components: icon gaps, text-to-icon, internal padding
Meso space-4, space-5, space-6 Between components: card padding, form rows, button groups
Macro space-8, space-12 Page structure: section breaks, hero areas, major separations

Anatomy of a Component

Every well-spaced component is built from the same tokens. Here’s a card with its spacing made visible:

Category
space-2
Component Title
space-3
Body text with enough room to breathe. The spacing between title and body is smaller than body to actions.
space-4
Padding: space-5 (20px) · Internal gaps: space-2 to space-4

The principle: proximity encodes relationship. Title-to-body (space-3) is tighter than body-to-actions (space-4), because the title describes the body, while the actions are a separate concern.

Density Modes

The same component structure at different spacing densities. Same tokens, different context.

Compact
Card Title
Dense data UI
Comfortable ✓
Card Title
Default density
Spacious
Card Title
Marketing layout

Compact (space-1 to space-3): Data tables, admin panels, dashboards — where information density matters more than breathing room.

Comfortable (space-3 to space-5): The default. Product UIs, documentation, forms — the right balance of density and clarity.

Spacious (space-5 to space-8): Marketing pages, landing pages, editorial layouts — where every element gets room to be appreciated.

Touch Targets

Mobile interfaces need minimum tap areas of 44×44px (Apple HIG) or 48×48px (Material). Here’s how spacing tokens build compliant touch targets:

44px
Apple minimum
space-2 padding + ~28px content = 44px
48px
Material minimum (space-12)
space-3 padding + ~24px content = 48px
Standard default button
padding: space-2 space-4 → 40×48px ✓

The key insight: you don’t need a special “touch target” token. Standard button padding (space-2 vertical, space-4 horizontal) with 1rem font size naturally produces targets that meet accessibility guidelines.

Usage Guidelines

Component Internal Spacing

Use smaller values (1-4) for padding and gaps within components.

padding: var(--space-2) var(--space-4)
padding: var(--space-1) var(--space-2) 
/* Buttons */
.Button { padding: var(--space-2) var(--space-4); }
.Button--small { padding: var(--space-1) var(--space-2); }
.Button--large { padding: var(--space-3) var(--space-6); }

/* Inputs */
.Input { padding: var(--space-2) var(--space-3); }

/* Cards */
.Card-body { padding: var(--space-4); }

Component Gaps

Use consistent gaps between related elements.

Tight (--space-2)
Tag Tag Tag
Standard (--space-4)
Loose (--space-6)
Card A
Card B
/* Tight - inline elements */
gap: var(--space-2);

/* Standard - buttons, form rows */
gap: var(--space-4);

/* Loose - cards, sections */
gap: var(--space-6);

Layout Spacing

Use larger values (6-12) for page-level spacing.

Header padding: var(--space-6)
Main Content padding: var(--space-8)
Nested section with margin-top: var(--space-6)
Footer padding: var(--space-4) 
/* Page container */
.container { padding: 0 var(--space-6); }

/* Section margins */
.section { margin-bottom: var(--space-12); }

/* Content blocks */
.content > * + * { margin-top: var(--space-6); }

Spacing Patterns

Stack Pattern

Vertical spacing between block elements.

First item
Second item
Third item
.Layout-stack { gap: var(--space-4); }
.Layout-stack--tight { gap: var(--space-2); }
.Layout-stack--loose { gap: var(--space-8); }

Inset Pattern

Equal padding on all sides.

space-2
space-4
space-6

Squish Pattern

Reduced vertical padding (common for buttons and pills).

Squish: 1 × 3
Squish: 2 × 4
Squish: 3 × 6 
/* Squish ratios (vertical × horizontal) */
padding: var(--space-1) var(--space-3); /* 1:3 - pills, small tags */
padding: var(--space-2) var(--space-4); /* 1:2 - buttons */
padding: var(--space-3) var(--space-6); /* 1:2 - large buttons */

Responsive Spacing

Adjust spacing at different breakpoints for optimal density.

/* Base mobile spacing */
.container {
  padding: 0 var(--space-4);
}

/* Tablet and up */
@media (min-width: 768px) {
  .container {
    padding: 0 var(--space-6);
  }
}

/* Desktop */
@media (min-width: 1024px) {
  .container {
    padding: 0 var(--space-8);
  }
}

Spacing Scale by Context

Context Mobile Tablet Desktop
Page padding space-4 space-6 space-8
Section gap space-6 space-8 space-12
Card padding space-3 space-4 space-4
Component gap space-2 space-3 space-4

Best Practices

Do

  • ✓ Use tokens, not arbitrary values — var(--space-4) not 15px
  • ✓ Be consistent — Same spacing for same relationships
  • ✓ Create hierarchy — More space = more separation
  • ✓ Use the scale — Jump by meaningful increments (2→4→6, not 2→3→4)

Don’t

  • ✗ Mix units — Don’t combine px and rem arbitrarily
  • ✗ Invent values — Stick to the scale
  • ✗ Overspace — Dense UIs can feel more professional
  • ✗ Underspace — Cramped layouts hurt readability
❌ Inconsistent
Title
Description text
✓ Consistent
Title
Description text

Quick Reference

/* Micro */
var(--space-1)  /* 4px  - Icon gaps, borders */
var(--space-2)  /* 8px  - Button padding, small gaps */

/* Standard */
var(--space-3)  /* 12px - Input padding */
var(--space-4)  /* 16px - Card padding, default gap */

/* Comfortable */
var(--space-5)  /* 20px - Section spacing */
var(--space-6)  /* 24px - Component margins */

/* Spacious */
var(--space-8)  /* 32px - Section breaks */
var(--space-12) /* 48px - Page sections */