Design System · 4 of 25
Spacing
Consistent rhythm through a systematic spacing scale.
Spacing philosophy
Spacing is a design element, not an afterthought.
Consistent spacing is one of the most impactful ways to improve a design system. It creates relationships between elements, establishes hierarchy, and guides the eye through content. Good spacing feels invisible — you notice it when it's missing.
The key is to use a limited set of spacing values from a scale rather than arbitrary pixel values. This creates visual rhythm and makes designs more predictable and easier to maintain.
Rules
Use spacing to create relationships and hierarchy.
Stick to the spacing scale — avoid magic numbers.
Be consistent with vertical rhythm.
Consider density based on context.
A systematic scale based on multiples of 4px provides flexibility while maintaining consistency.
The spacing scale
A mathematical approach to spacing.
A 4pt grid is the industry standard for digital interfaces. Starting from a base unit of 4px, you can create a scale of values that cover all needs from tight internal padding to large section breaks.
The scale should be used for all spacing — margins, padding, gaps, and positioning. This creates a cohesive rhythm throughout the interface.
Examples
space-0.5 (2px): Hairline borders, tight adjustments
space-1 (4px): Icon-text alignment, micro-spacing
space-2 (8px): Input padding, button padding, compact layouts
space-3 (12px): Form field gaps, list item spacing
space-4 (16px): Default padding, card padding, standard gaps
space-6 (24px): Section spacing, card gaps
space-8 (32px): Major section breaks
space-12 (48px): Page section spacing
space-16 (64px): Hero sections, large breaks
Rules
Base unit is 4px (0.25rem).
Use multiples of the base unit.
Name tokens by purpose or by scale value.
Limit to 12-16 values maximum.
:root {
--space-0: 0;
--space-0.5: 0.125rem; /* 2px */
--space-1: 0.25rem; /* 4px */
--space-2: 0.5rem; /* 8px */
--space-3: 0.75rem; /* 12px */
--space-4: 1rem; /* 16px */
--space-5: 1.25rem; /* 20px */
--space-6: 1.5rem; /* 24px */
--space-8: 2rem; /* 32px */
--space-10: 2.5rem; /* 40px */
--space-12: 3rem; /* 48px */
--space-16: 4rem; /* 64px */
--space-20: 5rem; /* 80px */
--space-24: 6rem; /* 96px */
}Margin, padding & gap
Understanding the different types of spacing.
Each type of spacing serves a specific purpose. Padding creates space inside an element between its border and content. Margin creates space outside an element between it and other elements. Gap creates space between children in flexbox or grid layouts.
Use padding for internal breathing room, margins for separation between components, and gaps for consistent spacing in layouts. Prefer gap over margins in flex/grid containers for more predictable layouts.
Rules
Use padding to increase clickable area and internal breathing room.
Use margin to create separation between sibling elements.
Use gap for spacing in flexbox and grid layouts.
Prefer gap over adding margins to flex/grid children.
Be consistent with spacing direction (usually top/bottom or rely on flow).
Visual demonstration of how each spacing type affects layout and relationships.
Grid gutters from the spacing scale
Consistent gutters derived from spacing tokens.
Grid gutters, container padding, and section spacing should all come from the spacing scale — not arbitrary pixels. The <a href="/design-system/layout">Layout</a> chapter shows the full 12-column grid with container and breakpoint implementation; this section documents the spacing-side decisions.
Use consistent gutters (typically <code>space-4</code> or <code>space-6</code>) and container padding that ramps with breakpoints (space-4 → space-6 → space-8) to maintain readability.
Examples
Gutter: space-4 (16px) mobile, space-6 (24px) desktop
Container padding: space-4 mobile, space-6 tablet, space-8 desktop
Section spacing: space-12 to space-24 between major sections
Card padding: space-4 or space-6 depending on content density
Rules
Define grid columns, gutters, and breakpoints once — in the layout layer.
Use the spacing scale for all grid-related spacing.
Align to the grid wherever possible.
Maintain consistent container margins.
Density & context
Adjust spacing based on use case.
Not all interfaces need the same amount of breathing room. Dense interfaces like data tables or admin dashboards benefit from tighter spacing to show more information. Consumer-facing apps often need more generous spacing for better readability and touch targets.
Provide density modes or choose appropriate spacing based on context. The same component can use different spacing tokens for compact vs comfortable variants.
Examples
Compact (admin tables): space-1 to space-3 for tight layouts
Default (product UI): space-2 to space-4 for balanced layouts
Comfortable (marketing): space-4 to space-8 for generous breathing room
Mobile: often tighter spacing than desktop
Rules
Consider information density needs.
Maintain touch target sizes (minimum 44x44px) even in compact modes.
Be consistent within a context.
Provide density as a system option when needed.
Compact, default, and comfortable densities use different spacing values for different contexts.
Vertical rhythm
Creating harmonious vertical flow.
Vertical rhythm keeps text and elements aligned to a baseline grid. For body text with line-height, your spacing should relate to that rhythm. A common approach is to use spacing values that are multiples related to your base line-height.
Consistent vertical rhythm improves readability and creates a sense of order. Stack related elements with smaller gaps, and separate sections with larger gaps.
Examples
Between label and input: space-1 or space-2
Between form fields: space-4 or space-6
Between paragraphs: space-4
Between sections: space-8, space-12, or space-16
Between page header and content: space-6 or space-8
Rules
Use larger spacing to separate unrelated groups.
Use smaller spacing to relate elements together.
Follow the principle of proximity.
Maintain consistency with line-height.
Practical guidelines
Tips for applying spacing effectively.
Start with the spacing scale and only deviate when necessary with justification. Use a spacing multiplier or stick to the predefined values. In CSS, prefer logical properties and use rem units for scalability.
Do
Use space-4 for default padding. Use larger gaps to separate sections. Stack related items with space-2 or space-3.
Don't
Don't use random values like 13px or 17px. Don't add margin to every child in a flex container when gap works. Don't forget mobile spacing adjustments.
Rules
Use the scale for all spacing decisions.
Avoid hard-coded pixel values.
Use rem units (1rem = 16px by default).
Prefer gap in flex/grid layouts.
Use padding for internal space, margin for external space.
Consider responsive spacing (smaller on mobile).
Test layouts at different zoom levels.
// Card component using spacing tokens
export function Card({ children }: { children: React.ReactNode }) {
return (
<div className="card" style={{
padding: "var(--space-6)",
display: "flex",
flexDirection: "column",
gap: "var(--space-4)",
marginBottom: "var(--space-8)"
}}>
{children}
</div>
);
}Checklist
Verify your spacing implementation.
Scale
All spacing uses values from the 4pt scale. No magic numbers in styles. Tokens are defined and documented.
Layout
Consistent gutters and padding. Proper use of margin/padding/gap. Grid system is applied correctly.
Hierarchy
Related elements are grouped with tight spacing. Unrelated elements separated with more space. Clear visual rhythm.
Responsive
Spacing adapts across breakpoints. Touch targets remain adequate. Readable at all screen sizes.