Spacing & scale

A 4px base unit drives the spacing scale. Gaps between blocks come from named rungs that say what the two blocks are to each other, not from a number.


Rhythm

Pick a rung by what two blocks are to each other. Read it live, as Stack’s gap prop or gap-(--spacing-rhythm-*). A numbered class like gap-10 freezes the length at build time, so a theme can no longer move it.

On a screen

A settings screen built from kit parts, with every gap marked by the rung that sets it.

Settings

Your profile and your plan.

Profile

How your team sees you.

JD

Jane Doe

jane@example.com

Shown on comments and invites.

Plan

Pro, billed yearly.

Seats
3 of 5
2 open
Storage
18 GB
Of 50 GB

Seats reset on 1 December.

All rungs

Every rung, including the ones this screen does not use.

RungUseValue
pairA line and the smaller line bound to it: a name over an email4px
bindProse to the block it introduces8px
labelA label to its control8px
helpA control to its help text8px
linesThree or more short lines that read as one unit12px
trim-pairA cap-trimmed title to its description12px
trim-pair-displayThe same, for a display headline (17px under a 36px title)8px + 0.25em
clusterBoxed siblings and card grids16px
mediaThe one sideways rung: an avatar or icon to its text16px
fieldOne form field to the next20px
submitThe last form field to the submit button24px
groupOne group inside a form to the next24px
actionsStacked secondary buttons8px
heading-smUnder a small heading, before its content20px
heading-mdUnder a medium heading. Also peer items inside one surface24px
heading-lgUnder a large heading, such as a page title32px
heading-displayUnder a display headline40px
peerPeer blocks in a section40px
regionSub-sections within a page60px
sectionWhole page sections96px

Scale

The 4px scale for insets. All spacing derives from --spacing: 0.25rem (4px). Bars scale in proportion to value.

ClassScaleValue
p-1
4px
p-2
8px
p-3
12px
p-4
default
16px
p-5
20px
p-6
24px
p-8
32px
p-12
48px
p-16
64px
p-20
80px

Widths

How wide things get: panels, the page, a line of text, and the screen sizes the layout answers to.

Widths and chrome

Width caps for panels, columns and the full page. The header and footer share one width and one side padding, so anything lined up with them lines up with the page edge. Bars show widths, in proportion to value.

TokenScale and useValue
--container-sm

Narrow panels

320px
--container-md

Small panels

384px
--container-lg

Dialog and AlertDialog width, forms

512px
--container-column

A page column of rows or cards: a projects list, a gallery index

576px
--container-xl

Content columns, prose

672px
--container-2xl

Wide content, two-column

896px
--container-chrome

Width of the SiteHeader and SiteFooter content

1280px
--container

Page content maximum

1540px
--spacing-chrome-gutter

Side padding for the site chrome and anything lined up with it

24px
--spacing-site-header

SiteHeader height. Pad a hero clear of the bar with it

80px

Reading measure

Line length governs reading rhythm. Caps are measured in ch, so a single value holds at every type tier. You may go narrower than a measure, never wider. Bars scale against 60ch.

ClassScale and useValue
max-w-measure

Reading copy: a 60 character measure

60ch
max-w-measure-heading

Headings wrap short rather than stretch

24ch
max-w-measure-heading-relaxed

Headings that run longer, as in Lockup and a hero

32ch
max-w-content

A block that is read, not examined: a code block stops where the copy does

= measure

Headings break into lines rather than stretch across the page.

Body copy holds a 60 character measure so the eye returns to a predictable left edge on every line. Long lines tire the eye; short ones fragment the thought. The measure is set in ch, so the physical width tracks the type size without a separate cap per tier.

Vertical rhythm

The prose-flow utility spaces long-form text. A heading gets more space above than below, so it belongs to what follows. An h2 or h3 takes only the 16px floor below; an h1 takes 40px. A table or code block has its own steps. Bars scale in proportion to value.

TokenScale and useValue
--rhythm-base

Floor gap between any two blocks, and the gap under an h2 or h3

16px
--rhythm-above-h3

Above h3 through h6

36px
--rhythm-above-h2

Above h2

56px
--rhythm-above-h1

Above h1

72px
--rhythm-below-h1

Below h1

40px
--rhythm-figure

Above a table or code block

48px
--rhythm-figure-bind

Between a paragraph and the table or code block it introduces

24px
--rhythm-figure-after

Below a table or code block

32px

Trigger conditions

Each contract specifies a trigger event tied to an objective public source. The gap above this heading is large; the gap below it is the 16px floor, so the heading reads as the start of this block.

Event definition

The trigger event is a measurable condition with a single binary outcome. Sub-headings take a smaller gap above than the section heading, keeping the hierarchy legible through spacing alone.

A second paragraph sits one floor-gap (16px) below the first. Body blocks never crowd and never drift.

Breakpoints

Mobile-first responsive breakpoints. Tailwind defaults, applied as min-width media queries. Bars scale in proportion to value.

BreakpointScale and useValue
sm:

Large phones, small tablets

640px
md:

Tablets, primary breakpoint

768px
lg:

Small laptops

1024px
xl:

Desktops

1280px
2xl:

Large desktops

1536px

Shape and depth

Corners, shadows and stacking order.

Border radius

A progressive scale from subtle rounding to fully circular. Each level has a defined usage.

xs

0.25rem

Close buttons, micro elements

sm

0.375rem

Checkbox, small controls

md (default)

0.5rem

Menu items, Popover, Tooltip

lg

0.75rem

Cards, dialogs, menu popups

xl

1rem

Drawers, sheets, large panels

2xl

1.25rem

Unassigned

3xl

1.5rem

Unassigned

4xl

2rem

Unassigned

full

9999px

Badges, pills, switches

action-xs

0.5625rem

Controls 24px tall

action-sm

0.65625rem

Controls 28px tall

action

0.75rem

Controls 32px tall

action-lg

0.9375rem

Controls 40px tall

action-xl

1.03125rem

Controls 44px tall (touch)

Shadow scale

Seven shadow tokens, from form control depth to modal lift. shadow-ring-flat is an edge with no lift. A Card with variant muted has no ring or shadow, only a fill.

shadow-ring-flat

An edge with no lift (Alert, Badge)

shadow-xs

Form controls (Input, Select, Checkbox) and Table

shadow-sm

Subtle elevation

shadow-ring-mddefault

Cards, popovers, menus, drawers

shadow-md

Plain drop shadow (inverted Tooltip)

shadow-lg

Heavy drop shadow

shadow-ring-lg

Modals, dialogs

Z-index scale

Four rungs, no named tokens. Every overlay shares z-50 on purpose: Base UI portals them to the body in mount order, so the last one opened wins. That is what lets a Select inside a Dialog sit above it, and a Dialog opened from a menu sit above the menu. Never give an overlay its own z-index.

UtilityDescriptionValue
z-10Elevation inside one component10
z-20Sticky region in a scroll container20
z-40Page chrome (SiteHeader)40
z-50Anything portaled to the body50