FoundationsSpacing
A 4 px base. Thirteen steps. No magic numbers.
Every gap, padding, and margin in the system is on a 4 px base. The thirteen named tokens are the only values that should ever appear in a component.
The scale
The scale is a simple 0–96 px progression. The named tokens are intentional because Tailwind's numeric classes (p-2, p-4) are not self-documenting — they don't tell the next contributor what role a particular gap is playing.
Mapping to Tailwind classes
The names above are documentation-only. In code, we use Tailwind's numeric utilities, which the design system constrains to the values in this table.
| Token | Tailwind | Pixels |
|---|---|---|
| space-1 | p-1, m-1, gap-1 | 4px |
| space-2 | p-2, m-2, gap-2 | 8px |
| space-3 | p-3, m-3, gap-3 | 12px |
| space-4 | p-4, m-4, gap-4 | 16px |
| space-6 | p-6, m-6, gap-6 | 24px |
| space-8 | p-8, m-8, gap-8 | 32px |
| space-12 | p-12, m-12, gap-12 | 48px |
| space-16 | p-16, m-16, gap-16 | 64px |
Rhythm, not randomness
The system has rules for what gap goes where. The rules are short, and the reason for each one is the same: a consistent rhythm is what makes a long page feel like a single document, not a list of sections.
| Where | Use |
|---|---|
| Component internal padding | space-2 → space-4 (8 → 16 px) |
| Form field gap | space-2 (8 px) |
| Card gap (related cards) | space-3 (12 px) or space-4 (16 px) |
| Section gap (same page) | space-12 (48 px) on mobile, space-20 (80 px) on desktop |
| Page-level vertical rhythm | space-16 → space-24 (64 → 96 px) |
| Within prose | space-4 (16 px) between paragraphs |
A worked example
The same card, the same content, the same space-4 / space-6 / space-8 layout across both desktop and mobile.
Section label
A worked example of the spacing system
The eyebrow is space-2 below the card top. The h3 is space-3 below the eyebrow. The body is space-4 below the h3. The CTA is space-6 below the body. Each gap is a named token; none of them is a magic number.
Read moreSection vertical rhythm
Sections on every page are separated by space-12 (48 px) on mobile and space-20 (80 px) on desktop. The two values are not a responsive tweak — they are the design: a section on desktop should breathe more than a section on mobile because the screen is wider and the eye travels further.
.ds-section {
margin-top: 3.5rem; /* 56 px on mobile */
}
@media (min-width: 768px) {
.ds-section {
margin-top: 4.5rem; /* 72 px on tablet, 80 px on desktop */
}
}Why this scale
The 4 px base is the smallest grid that still allows meaningful differences between adjacent steps. A 2 px base (typical on Windows desktop) reads as cramped next to a 19 px body; a 5 or 8 px base (typical on iOS HIG and some Western design systems) loses the fine control needed for compact UI like form fields and table cells.
The thirteen steps are enough to express all of the system's vertical relationships without giving a component author the option to pick a value outside the system. If a layout needs a 22 px gap, the right answer is to pick space-5 (20 px) or space-6 (24 px) — not to invent a new value.