Eve library

Spacing System

Guide

Revision 1

On this page

import { Meta } from 'storybook/blocks';

<Meta title="Style Guide/Spacing" />

Our spacing system uses a consistent scale to create harmonious layouts and maintain visual rhythm.

Spacing Principles#

  1. 8px Base Unit: All spacing values are multiples of 8px for consistency
  2. Semantic Naming: Use purpose-based names for clarity
  3. Responsive Design: Spacing can adapt to screen sizes
  4. Predictable Scale: Each step is proportionally larger

Spacing Scale#

Token Value Pixels Use Case
none 0 0px No spacing
xs 0.125rem 2px Minimal gaps
sm 0.25rem 4px Tight spacing, icon margins
md 0.5rem 8px Default small spacing
lg 1rem 16px Component internal padding
xl 1.5rem 24px Section spacing
2xl 2rem 32px Large gaps
3xl 3rem 48px Major section spacing
4xl 4rem 64px Page-level spacing
5xl 6rem 96px Hero sections
6xl 8rem 128px Maximum spacing

Visual Scale#

text
xs:   ██
sm:   ████
md:   ████████
lg:   ████████████████
xl:   ████████████████████████
2xl:  ████████████████████████████████
3xl:  ████████████████████████████████████████████████

Component Spacing#

Padding Guidelines#

Component Padding
Button (small) py-2 px-3 (8px / 12px)
Button (medium) py-2.5 px-4 (10px / 16px)
Button (large) py-3 px-6 (12px / 24px)
Input py-2 px-3 (8px / 12px)
Card p-6 (24px)
Modal body p-6 (24px)
Table cell p-4 (16px)

Margin Guidelines#

Element Margin
Heading after heading mt-2 (8px)
Paragraph after paragraph mt-4 (16px)
Section spacing mt-8 or mt-12
Form field gap gap-4 (16px)
Button group gap gap-2 (8px)

Layout Spacing#

Page Layout#

tsx
// Standard page layout
<main className="px-4 md:px-6 lg:px-8 py-8">
  <header className="mb-8">
    <h1>Page Title</h1>
  </header>

  <section className="mb-12">
    {/* Content sections with 48px spacing */}
  </section>
</main>

Card Layout#

tsx
// Card with consistent spacing
<Card className="p-6">
  <CardHeader className="pb-4">
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent className="space-y-4">
    {/* 16px gap between children */}
  </CardContent>
  <CardFooter className="pt-4">
    {/* Footer actions */}
  </CardFooter>
</Card>

Form Layout#

tsx
// Form with proper spacing
<form className="space-y-6">
  <div className="space-y-4">
    <Input label="Name" />
    <Input label="Email" />
  </div>

  <div className="flex gap-2 justify-end">
    <Button variant="outline">Cancel</Button>
    <Button>Submit</Button>
  </div>
</form>

Gap Utilities#

Use flexbox or grid gap for consistent spacing between children:

tsx
// Horizontal button group
<div className="flex gap-2">
  <Button>One</Button>
  <Button>Two</Button>
</div>

// Vertical stack
<div className="flex flex-col gap-4">
  <Card>First</Card>
  <Card>Second</Card>
</div>

// Grid layout
<div className="grid grid-cols-3 gap-6">
  <Card>A</Card>
  <Card>B</Card>
  <Card>C</Card>
</div>

Responsive Spacing#

Adjust spacing based on viewport size:

tsx
// Responsive padding
<div className="p-4 md:p-6 lg:p-8">
  {/* 16px → 24px → 32px */}
</div>

// Responsive gap
<div className="grid gap-4 md:gap-6 lg:gap-8">
  {/* Grid with responsive gaps */}
</div>

// Responsive margins
<section className="mt-8 md:mt-12 lg:mt-16">
  {/* Section with growing top margin */}
</section>

Spacing Tokens in Code#

Import and use spacing tokens programmatically:

tsx
import { spacing, componentSpacing } from '@/design-system/tokens';

// Access raw values
console.log(spacing.lg); // '1rem'
console.log(spacing['2xl']); // '2rem'

// Component-specific spacing
console.log(componentSpacing.card.padding); // '24px'
console.log(componentSpacing.button.gap); // '8px'

Best Practices#

Do#

  • Use spacing tokens consistently throughout the app
  • Apply responsive spacing for different screen sizes
  • Use gap utilities instead of margins on children
  • Keep related elements closer together than unrelated ones

Don't#

  • Use arbitrary pixel values (p-[17px])
  • Mix spacing systems within a component
  • Apply margin to both sides of a gap (use gap instead)
  • Forget mobile-first responsive spacing

Spacing Checklist#

When building a new component, verify:

  • Padding uses spacing scale tokens
  • Margins use spacing scale tokens
  • Gap utilities used where appropriate
  • Responsive variants defined for key breakpoints
  • Spacing is consistent with similar components
  • Touch targets are at least 44px for accessibility