---
id: seed:conventions/spacing-scale
title: Spacing scale
source_type: seed_convention
priority: warm
---

Generated CSS should use a consistent spacing scale, never one-off pixel values like `padding: 37px`. Visitors don't see the scale, but they see what its absence produces: a page that feels "off" without being able to explain why.

**The default scale (rem-based, root font-size 16px):**

```
0.25rem  4px   xs    tight gaps between icon and label
0.5rem   8px   sm    button padding-y, small inline gaps
1rem     16px  md    paragraph line-height adjustments
1.5rem   24px  lg    card padding, container padding-inline
2rem     32px  xl    space between adjacent text blocks
3rem     48px  2xl   space between cards in a grid
4rem     64px  3xl   space inside section padding-block on mobile
6rem     96px  4xl   space inside section padding-block on desktop
8rem     128px 5xl   hero padding-block on desktop
```

**Apply via CSS custom properties:**

```css
:root {
  --space-xs:  0.25rem;
  --space-sm:  0.5rem;
  --space-md:  1rem;
  --space-lg:  1.5rem;
  --space-xl:  2rem;
  --space-2xl: 3rem;
  --space-3xl: 4rem;
  --space-4xl: 6rem;
  --space-5xl: 8rem;
}

.hero-section { padding-block: var(--space-5xl) var(--space-4xl); }
.features-section { padding-block: var(--space-4xl); }
.feature-card { padding: var(--space-lg); }
.features-grid { gap: var(--space-2xl); }
```

**Section padding pattern:** `padding-block: 4rem 4rem` mobile, `padding-block: 6rem 6rem` desktop. Use a media query at the section level. Avoid using top/bottom margins on sections — sibling section margin collapse is unpredictable; padding inside the section is.

**Gap > margin.** For flex/grid layouts (cards, list rows), use `gap` on the parent, not `margin` on children. Cleaner and matches the scale uniformly.

**No magic numbers.** If you need 27px somewhere, it almost always means you're missing a step in your scale OR you're trying to nudge instead of fixing the underlying layout.
