Spacing & Grid

Spacing scale, responsive breakpoints, container sizes, z-index layers, and aspect ratios.

Spacing Scale

Base unit: --spacing: 0.25rem (4px). All values are multiples of this base. Use with p-*, m-*, gap-*, w-*, h-*, etc.

0px (0rem)

1px (1px)

2px (0.125rem)

4px (0.25rem)

6px (0.375rem)

8px (0.5rem)

10px (0.625rem)

12px (0.75rem)

14px (0.875rem)

16px (1rem)

20px (1.25rem)

24px (1.5rem)

28px (1.75rem)

32px (2rem)

36px (2.25rem)

40px (2.5rem)

44px (2.75rem)

48px (3rem)

56px (3.5rem)

64px (4rem)

80px (5rem)

96px (6rem)

112px (7rem)

128px (8rem)

144px (9rem)

160px (10rem)

176px (11rem)

192px (12rem)

208px (13rem)

224px (14rem)

240px (15rem)

256px (16rem)

288px (18rem)

320px (20rem)

384px (24rem)

Breakpoints

Mobile-first responsive design breakpoints. Prefix any utility with the breakpoint name to apply it at that screen size and above.

Min Width	Rem	CSS
640px	40rem	`@media (min-width: 640px)`
768px	48rem	`@media (min-width: 768px)`
1024px	64rem	`@media (min-width: 1024px)`
1280px	80rem	`@media (min-width: 1280px)`
1536px	96rem	`@media (min-width: 1536px)`

Container Sizes

Named max-width values for constraining content width. Use with max-w-* or @container queries.

256px (16rem)

288px (18rem)

320px (20rem)

384px (24rem)

448px (28rem)

512px (32rem)

576px (36rem)

672px (42rem)

768px (48rem)

896px (56rem)

1024px (64rem)

1152px (72rem)

1280px (80rem)

Z-Index

Stacking order utilities for controlling layer precedence. Use consistent values to avoid z-index conflicts.

auto

Class	Value	CSS
	0	`z-index: 0`
	10	`z-index: 10`
	20	`z-index: 20`
	30	`z-index: 30`
	40	`z-index: 40`
	50	`z-index: 50`
	auto	`z-index: auto`

Aspect Ratios

Control the proportional relationship between an element's width and height.

auto

Browser default

1 / 1

Square

16 / 9

Widescreen video

Composition Patterns

Common spacing patterns showing how tokens combine in real layouts. Consistent spacing creates rhythm and reduces visual noise.

Card padding

p-3 — Compact

p-4 — Default

p-6 — Spacious

Stack spacing

space-y-2 (tight)

space-y-4 (default)

space-y-8 (sections)

Grid gap

gap-4

Design Guidelines

Use the 4px base grid. All spacing values are multiples of 4px. Stick to the scale for consistent rhythm across components.
Use gap for grid and flex layouts. Prefer gap-*over margins on children — it simplifies removal and reordering of items.
Use space-y for vertical stacks. space-y-4 for related content, space-y-8 for section separation.
Constrain content with max-w. Use named container tokens (max-w-4xl, max-w-prose) to keep line lengths readable.
Design mobile-first breakpoints. Start with the base (mobile) layout and progressively enhance at sm:, md:, lg:.

Don't

Don't use arbitrary spacing values. Avoid p-[13px] or gap-[7px]. Stick to the scale so spacing stays predictable and harmonious.
Don't mix margin directions in a stack. Use either space-y-* or individual mt-* values, never both. Mixing causes hard-to-debug double spacing.
Don't skip breakpoints. Going straight from base to lg: leaves tablet users with a suboptimal layout. Design for at least base, sm:, and lg:.
Don't hard-code z-index values. Use the z-index scale tokens (z-10 through z-50) to prevent stacking conflicts.
Don't set fixed aspect ratios with padding hacks. Use the native aspect-* utilities instead of the legacy padding-bottom technique.

Developer Reference

Accessibility

Touch targets must be at least 44×44px (WCAG 2.5.8). Use padding and min-height to meet this even when visual size is smaller.
Ensure adequate spacing between interactive elements (at least 8px) to prevent accidental taps on mobile.
Content must be accessible at 400% zoom without horizontal scrolling (WCAG 1.4.10). Use responsive breakpoints and max-w-* to support reflow.
Avoid using spacing alone to convey grouping. Combine spacing with borders, headings, or semantic HTML (fieldset, section) for screen reader users.

Usage

// Spacing utilities (multiples of 4px base)
<div className="p-4">16px padding</div>
<div className="m-6">24px margin</div>
<div className="gap-3">12px gap</div>

// Vertical stacks
<div className="space-y-4">  {/* 16px between items */}
  <Card />
  <Card />
</div>

// Responsive breakpoints (mobile-first)
<div className="p-4 sm:p-6 lg:p-8">
  <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
    ...
  </div>
</div>

// Container widths
<div className="mx-auto max-w-4xl">Content</div>

// Z-index layers
<div className="z-10">Base layer</div>
<div className="z-20">Dropdown</div>
<div className="z-30">Sticky header</div>
<div className="z-40">Modal overlay</div>
<div className="z-50">Toast / tooltip</div>

// Aspect ratios
<div className="aspect-video">16:9 video</div>
<div className="aspect-square">1:1 square</div>