whitespace-density

name: whitespace-density description: This skill should be used when the user is adjusting spacing, padding, margins, content density, section gaps, vertical rhythm, or separation between elements. Also applies when reviewing whether a design feels cramped or too sparse, choosing between borders and whitespace for separation, or defining a spacing system. Covers the 4px/8px spacing system, macro vs micro whitespace, content density spectrum, separation techniques (whitespace > background shifts > borders), and vertical rhythm. version: 1.0.0

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

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.

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

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

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