Structure

Spacing, page layout, and breakpoints — how UI sits in the viewport.

Structure covers the 4px spacing scale, content widths and grids, and the min-width breakpoints that change layout. Prefer these tokens over arbitrary padding, track sizes, or media queries.

w-60

px-4 · md:px-10 · lg:px-14

Content

max-w-5xl

Prose

max-w-3xl

Spacing

Driven by --spacing at 0.25rem (4px). Prefer p-4, gap-3, and space-y-6 over arbitrary values. Click a row to copy a padding class.

Preview

Step

Usage

Step	Value	Usage
0.5	0.125rem (2px)	Hairline gaps, icon optical tweaks
1	0.25rem (4px)	Tightest stack spacing, badge padding
1.5	0.375rem (6px)	Compact control gaps
2	0.5rem (8px)	Default inline gaps, small padding
2.5	0.625rem (10px)	Dense list row padding
3	0.75rem (12px)	Control padding, form field gaps
4	1rem (16px)	Default section padding, card padding
5	1.25rem (20px)	Comfortable panel padding
6	1.5rem (24px)	Section gaps, spacious cards
8	2rem (32px)	Large section spacing
10	2.5rem (40px)	Page block gaps
12	3rem (48px)	Major section separation
16	4rem (64px)	Hero / page rhythm

Role	Typical steps	Examples
Inline / control	1 – 3	Icon + label gaps, badge padding, dense rows
Component padding	3 – 5	Buttons, inputs, cards, menu items
Section rhythm	6 – 12	Stacked sections, page blocks, form groups
Page / hero	10 – 16	Major separations and first-viewport breathing room

Widths and grid

Docs pages center content with a max width, then pad the main column with responsive gutters. Grids handle multi-column regions without inventing custom track sizes.

Content widths

Name	Class	Value	Usage
Prose	max-w-3xl	48rem (768px)	Guidelines, descriptions, and long-form copy
Docs	max-w-5xl	64rem (1024px)	Default foundation and component pages
Wide	max-w-6xl	72rem (1152px)	Wide galleries (e.g. color palettes)

Shell measures

Name	Class	Value	Usage
Sidebar	w-60	15rem (240px)	Docs navigation column
Gutter (mobile)	px-4	1rem (16px)	Main content horizontal padding below md
Gutter (md)	md:px-10	2.5rem (40px)	Main content padding from md
Gutter (lg)	lg:px-14	3.5rem (56px)	Main content padding from lg

Grid patterns

grid grid-cols-2 gap-3 sm:grid-cols-4

Pattern	Class	Usage
Two column	grid gap-4 md:grid-cols-2	Intro cards, paired previews, split content
Four column	grid grid-cols-2 sm:grid-cols-4	Icon galleries and dense tile grids
Auto fill	grid gap-4 grid-cols-[repeat(auto-fill,minmax(12rem,1fr))]	Responsive card collections without fixed breakpoints

Breakpoints

Mobile-first min-width steps. Base styles apply below the first step; each prefix applies from that width upward via --breakpoint-*.

Active viewport…

min-width scale

380px

576px

768px

1024px

1280px

2xl

1536px

Name	Prefix	Min width	Usage
xs	xs:	380px (23.75rem)	Large phones — earliest responsive step
sm	sm:	576px (36rem)	Small tablets / large phones landscape
md	md:	768px (48rem)	Tablets — docs sidebar appears
lg	lg:	1024px (64rem)	Laptops — wider gutters and layouts
xl	xl:	1280px (80rem)	Desktops — roomy multi-column layouts
2xl	2xl:	1536px (96rem)	Wide desktops — max canvas

Common patterns

Pattern	Classes	Notes
Docs sidebar	hidden md:block	Nav docks from md; TopBar handles smaller viewports.
Page gutters	px-4 md:px-10 lg:px-14	Padding steps up with available width.
Two-column grids	grid-cols-1 md:grid-cols-2	Stack on small screens; split from md.
Dense galleries	grid-cols-2 sm:grid-cols-4	Earlier column increase at sm for tiles.

tsx

<div className="grid grid-cols-1 gap-4 md:grid-cols-2">
  <section>…</section>
  <section>…</section>
</div>

Usage guidelines

Do

Use spacing scale utilities (gap-4, p-3, mt-6)
Wrap page content in max-w-5xl (or max-w-6xl for wide galleries); keep guidelines to max-w-3xl
Write mobile-first, then layer sm: / md: / lg:
Match shell behavior: sidebar at md, wider gutters at lg
Keep diagrams in neutrals (bg-fg-primary, bg-background-tertiary)

Don't

Don't use arbitrary spacing like p-[13px] or custom breakpoints like min-[900px]:
Don't stretch unbounded content across ultra-wide viewports
Don't design desktop-first and override everything downward
Don't change layout at every breakpoint — reserve jumps for real structure changes