oborchers/whitespace-density

Start with Too Much Whitespace, Then Remove Until It Feels Right

Whitespace is not empty space -- it is active structure. Research by Wichita State University found that increased whitespace between paragraphs and around margins improved comprehension by 20%. The Refactoring UI principle is clear: start with too much whitespace, then remove until it feels right. Never start tight and try to add space later.

Macro vs Micro Whitespace

Macro whitespace is the space between major sections, around the content frame, and between layout regions. It establishes page-level breathing room and visual grouping.

Micro whitespace is the space within components -- between a label and its input, between list items, between an icon and its text. It determines readability and component density.

Both must be intentional. Macro whitespace without micro whitespace produces elegant-looking layouts with unreadable components. Micro whitespace without macro whitespace produces readable components floating in a cramped sea.

The 4px/8px Spacing Scale

Define a constrained spacing scale using a 4px base unit. Every spacing value in the system must come from this scale.

:root {
  --space-1:   4px;    /* micro: icon-text gap */
  --space-2:   8px;    /* micro: inline element gap */
  --space-3:  12px;    /* micro: related element gap */
  --space-4:  16px;    /* standard component padding */
  --space-5:  20px;    /* component internal sections */
  --space-6:  24px;    /* between related components */
  --space-8:  32px;    /* between distinct components */
  --space-10: 40px;    /* compact section gap */
  --space-12: 48px;    /* standard section gap */
  --space-16: 64px;    /* generous section gap */
  --space-24: 96px;    /* premium section gap */
  --space-32: 128px;   /* hero/premium section gap */
}

Whitespace Ratio Benchmarks

| Context | Whitespace % | Example | |---------|-------------|---------| | News sites | 20--30% | CNN, Reuters | | SaaS dashboards | 25--35% | Datadog, Grafana | | Corporate / SaaS marketing | 35--45% | Stripe docs, GitHub | | Premium / luxury | 50--65% | Apple product pages | | Apple homepage hero | 60--70% | apple.com |

Separation Hierarchy

Use the lightest-weight separation technique that works. Heavier separators add visual noise.

Prefer in this order:

1. Whitespace alone -- group by proximity, no visual artifact
2. Background color shift -- subtle tonal difference (e.g., --color-bg-subtle)
3. Borders -- last resort, only when whitespace and background shifts fail

Borders are visual clutter. Every border competes for attention. Use them only when spacing alone cannot communicate grouping.

Gestalt Proximity Rule

Internal spacing must be no more than 50% of external spacing. This is Gestalt proximity: elements that are closer together are perceived as belonging together.

| Relationship | Spacing | |-------------|---------| | Within a group (internal) | --space-2 to --space-4 | | Between groups (external) | --space-6 to --space-12 | | Between sections | --space-12 to --space-32 |

If the gap between a label and its input is the same as the gap between two form groups, the user cannot parse the structure at a glance.

Section Gaps

| Density | Section Gap | Use Case | |---------|-------------|----------| | Compact | 32--48px | Dashboards, data-heavy apps | | Standard | 64--96px | SaaS marketing, documentation | | Premium | 96--128px+ | Landing pages, brand sites |

Vertical rhythm rule: Section gap standard deviation must be 8px or less. Inconsistent section gaps destroy the sense of structure. Pick one gap value per page density and use it everywhere.

Anti-Patterns

| Anti-Pattern | Problem | Fix | |-------------|---------|-----| | Edge-to-edge cramming | Content touching container edges | Add --space-4 to --space-6 padding minimum | | Borders everywhere | Visual noise, heavy feel | Replace with whitespace or background shifts | | Inconsistent spacing | No visual rhythm, feels unpolished | Use the spacing scale exclusively | | Claustrophobic layouts | Users feel overwhelmed | Start with 2x the spacing you think you need | | Equal internal/external gaps | Groups unreadable | Internal spacing <= 50% of external |

Cross-Media Notes

• Presentations: 50--65% whitespace ratio, 10--15% slide margins on each side, generous line spacing (1.4--1.6x)
• CVs/Resumes: 1-inch (2.54cm) margins minimum, 35--45% whitespace ratio, consistent section gaps
• Dashboards: 25--35% whitespace, tighter spacing acceptable for data density, use background shifts over borders

Examples

Working implementations in examples/:

• examples/spacing-system-and-separation.md -- Complete spacing system in CSS/Tailwind/React, demonstrates separation without borders

Review Checklist

When reviewing or building spacing and density:

• [ ] A constrained spacing scale is defined (4px/8px base)
• [ ] No magic-number spacing values outside the scale
• [ ] Internal spacing is no more than 50% of external spacing (Gestalt proximity)
• [ ] Whitespace preferred over background shifts, background shifts preferred over borders
• [ ] Borders used only when whitespace and background shifts are insufficient
• [ ] Section gaps are consistent (standard deviation <= 8px)
• [ ] Content never touches container edges (minimum padding applied)
• [ ] Macro whitespace (section-level) and micro whitespace (component-level) are both addressed
• [ ] Whitespace ratio is appropriate for the content type and audience
• [ ] Vertical rhythm is maintained across the full page
• [ ] Spacing tokens are used in Tailwind config or CSS custom properties
• [ ] The design passes the "start with too much, remove until right" test