# SPACING_SYSTEM.md

## 1. Scale (8pt base, 4pt half-step)

| Token | px | Use |
|---|---|---|
| `space-1` | 4 | Chip inner gaps, icon-to-label |
| `space-2` | 8 | Inside chips/buttons vertical, tight stacks |
| `space-3` | 12 | Button horizontal padding unit, list gaps |
| `space-4` | 16 | Card inner padding (mobile), paragraph gaps |
| `space-5` | 24 | Card inner padding (desktop), grid gutters |
| `space-6` | 32 | Between related blocks |
| `space-7` | 48 | Between component groups |
| `space-8` | 64 | Section inner top/bottom (mobile) |
| `space-9` | 96 | Section rhythm (desktop) |
| `space-10` | 128 | Hero breathing room, page top/bottom |

Only these ten values exist. No 20px, no 30px, no eyeballing.

## 2. Rules

1. **Section rhythm:** homepage sections separated by `space-9` desktop / `space-8` mobile; the mono section label sits `space-6` above its H2.
2. **Proximity encodes relationship:** gap within a skill group (`space-2`) < gap between groups (`space-5`) < gap between sections (`space-9`). If two things feel related but aren't, increase the gap before adding a divider; hairlines are the *second* resort.
3. **Cards:** `space-5` padding desktop, `space-4` mobile; media flush to card edge (screenshots bleed to the frame), text content padded.
4. **Touch targets:** min 44×44px tap area on mobile (chips visually smaller but hit-area padded); nav/footer link spacing ≥ `space-3` vertically on mobile.
5. **Header:** 72px tall default, compresses to 56px on scroll; content top-padding accounts for it (anchor scroll offset = header height + `space-5`).
6. **Prose:** paragraph gap `space-4`; heading top `space-7`/bottom `space-3` (the 2:1 before/after rule from TYPOGRAPHY_GUIDE).
7. **Density gradient:** marketing-calm at top of pages → denser in technical sections (case-study decision lists, footer). Density shift is achieved by stepping down *one* spacing token, never by shrinking type below `small`.
