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#
- 8px Base Unit: All spacing values are multiples of 8px for consistency
- Semantic Naming: Use purpose-based names for clarity
- Responsive Design: Spacing can adapt to screen sizes
- 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