Foundations

Spacing

Sixteen steps built around an 8px rhythm, with 4px half-steps where dense UI needs them. Spacing says what belongs together without adding another visible element to the page.

Translated from the reference

The visual reference repeatedly uses 8, 24, 32 and 64px. The system keeps that rhythm and retains 4px half-steps for compact icon gaps and controls — a predictable scale is one teams can use consistently.

The scalePermalink to this section

Steps get coarser as they grow, because the difference between 4 and 8 matters and the difference between 80 and 84 does not.

4pxIcon to label inside a control

8pxRelated elements inside one component

12pxControl padding, list item gaps

16pxDefault gap between related blocks

24pxCard padding, paragraph rhythm

32pxGap between content groups

48pxMajor section separation

80pxMarketing section padding

ProximityPermalink to this section

Elements that belong together sit closer than elements that do not. Getting this relationship right removes the need for most dividers.

Workspace nameShown in the sidebar.

RegionWhere data is stored.

Do — group by distance

4px inside a pair, 24px between pairs. The grouping is obvious before a single word is read.

Workspace nameShown in the sidebar.RegionWhere data is stored.

Don't — space everything equally

With one gap everywhere, the reader has to parse the text to work out which label owns which description.

AppliedPermalink to this section

Which step to reach for at each level of the interface.

Level	Step	Example
Inside a control	4–8px	Gap between a button's icon and its label
Between form fields	16–20px	One field stack in a form
Card padding	16–24px	Compact and default cards
Between related blocks	24–32px	A heading and the group it introduces
Between doc sections	40–56px	Two sections on a documentation page
Marketing sections	64–96px	Mobile and desktop section padding

Vertical rhythmPermalink to this section

Spacing above a heading is always larger than spacing below it, so a heading attaches to the content it introduces rather than floating between two blocks.

Preceding paragraph.

40px above

Section heading

8px below

The content this heading introduces.

In codePermalink to this section

Tailwind's 4px base supplies the half-step; even-numbered utilities carry the dominant 8px rhythm and line up with the authored tokens.

app/settings/settings-section.tsx

// gap-1 = 4px  · label to description
// gap-4 = 16px · between fields
// gap-8 = 32px · between sections
// p-6   = 24px · card padding
<section className="flex flex-col gap-8">
  <div className="flex flex-col gap-4">
    <div className="flex flex-col gap-1">
      <label className="type-label">Workspace name</label>
      <p className="type-caption text-ink-muted">Shown in the sidebar.</p>
    </div>
  </div>
</section>

TokensPermalink to this section

The full spacing scale.