Home / Foundations / Spacing & layout
Spacing & layout
The observed spacing distribution, layout constants, breakpoints, z-index and elevation.
Observed spacing inventory
740 declarations scanned in the shipped sheets · 85% land on the 4px grid — kept as the historical census1px106
2px57
3px17off 4px grid
4px26
5px9off 4px grid
6px63
7px12off 4px grid
8px77
9px19off 4px grid
10px83
11px10off 4px grid
12px52
13px5off 4px grid
14px48
15px7off 4px grid
16px26
18px11
20px2
21px2off 4px grid
22px4off 4px grid
24px11
25px1off 4px grid
26px10
27px1off 4px grid
28px4
30px12
33px1off 4px grid
34px6off 4px grid
40px3
44px15
46px4off 4px grid
48px2
54px1off 4px grid
60px1
70px1off 4px grid
72px1
80px1
82px1off 4px grid
84px1
86px1off 4px grid
92px2
96px1
104px2
110px1off 4px grid
115px3off 4px grid
118px1off 4px grid
120px5
130px1off 4px grid
140px2
150px2off 4px grid
160px2
180px2
190px1off 4px grid
200px1
Spacing is tokenised — a curated preferred scale, semantic roles, and layout dimensions. 0.10 curates the preferred scale (2/4/8/12/16/24/32/48) and adds semantic roles so components name intent, not a raw step: --space-page, --space-card, --space-field and --space-control. Fixed chrome/column widths that are not spacing gaps (sidebar, content column, dock) live in a separate --layout-* group. The fine/odd steps the shipped sheets still use (1, 3, 5, 6, 7 … 480) are kept for compatibility and labelled legacy — new work should prefer the preferred scale. TDS005 flags anything outside the token set, and core references the tokens instead of raw px (the remaining literals are calc()/env() and negative offsets).
Preferred spacing scale
the canonical scale — prefer these steps for new work| Token | Value | Typical use |
|---|---|---|
| --space-2 | 2px | hairline gaps |
| --space-4 | 4px | tight gaps, checkbox rows |
| --space-8 | 8px | default control gap, form-field padding |
| --space-12 | 12px | button inline padding, toolbar gap |
| --space-16 | 16px | card padding |
| --space-24 | 24px | page padding (.content), section rhythm |
| --space-32 | 32px | dialog gutter, large gaps |
| --space-48 | 48px | section breaks |
Semantic spacing roles
roles name intent; components read the role, not a step| Token | Value | Consumed by |
|---|---|---|
| --space-page | 24px | .content page padding (top + inline) |
| --space-card | 16px | .card padding |
| --space-field | 8px | label/field gap and form-field padding |
| --space-control | 12px | .btn / .iconbtn inline padding |
Legacy / observed steps
Emitted as --space-* for compatibility: 1, 3, 5, 6, 7, 9, 10, 11, 13, 14, 15, 18, 20, 22, 26, 28, 30, 33, 34, 44, 46, 80, 92, 96, 104, 120, 140, 150, 180, 190, 236, 240, 250, 260, 280, 300, 340, 352, 396, 420, 480. These are the fine/odd values the original sheets used; prefer the preferred scale for new work and do not add new tokens from this tier.
Layout dimensions
fixed chrome and column widths — deliberately not spacing gaps, so they emit as --layout-*| Token | Value | Consumed by |
|---|---|---|
| --layout-sidebar | 236px | .side width, .main inline offset |
| --layout-content-max | 1160px | .content max-width |
| --layout-dock | 352px | assistant dock open-width fallback |
Layout constants
| Constant | Value | Where |
|---|---|---|
| Sidebar width | var(--layout-sidebar) = 236px (fixed/inset) | .side |
| Content column | max-width var(--layout-content-max) = 1160px · padding var(--space-page) 24px | .content |
| Assistant sidebar | rail 46px · open var(--dock-w, var(--layout-dock) 352px) · clamp 280…min(720, innerWidth−480) | .dock |
| Chat shell rail | 240px + fluid column | .chat-layout |
| Chat stack | height calc(100vh − 300px) · min 480px (mobile 100dvh variants) | .chat-flex |
| Mobile tab bar | content reserves bottom 92px + safe-area | .bottom-nav |
| grid2 | 1fr 1fr | form / card grids |
| grid3 | 150px 130px 1fr | condition rows |
| grid5 | 118px 104px 92px minmax(0,1fr) 86px | dense rules grid |
| split-grid | minmax(0,1.6fr) minmax(0,1fr) | dashboard |
| detail-grid | minmax(0,2fr) minmax(0,1fr) | message viewer |
| settings-grid | 216px minmax(0,1fr) | settings |
| metrics | repeat(auto-fit, minmax(200px,1fr)) | dashboard hero strip |
| stat | min-width 104px (mobile calc(50% − 10px)) | .stat |
Breakpoints
| Width | What flips |
|---|---|
| 640px | Chat bubble width, assistant stack height, log font |
| 767px | Phone mode: bottom tab bar, mcards reflow, sheets, chat-head, savebar lifts, .page-desc/.foot hidden, 16px inputs |
| 900px | Settings side nav becomes horizontal chips; .setting-row single column |
| 1023px | Off-canvas sidebar + topbar; .dock hidden; detail-grid/settings/split-grid single column; tighter content padding |
| 1239px | Dashboard system strip 4 → 2 columns |
| pointer:coarse | 44px targets, 48px nav rows, 16px inputs (kills iOS zoom) regardless of width |
Z-index ladder
anything full-screen must clear 180 or the mobile tab bar punches through| Layer | z |
|---|---|
| bulkbar | 6 |
| menu-pop | 30 |
| topbar | 30 |
| scrim | 35 |
| side | 40 |
| dock | 45 |
| bottom-nav | 180 |
| sheet + overlay | 190 |
| skip link | 200 |
| toasts | 300 |
Elevation & radius
| Layer | Shadow | Use |
|---|---|---|
| menu-pop | 0 10px 30px rgba(0,0,0,.14) | floating menu |
| flow-insert-menu | 0 10px 28px rgba(0,0,0,.10) | flow insert palette |
| toast2 | 0 8px 24px rgba(0,0,0,.25) | toast |
| mobile drawer | 0 0 40px rgba(0,0,0,.18) | off-canvas sidebar |
| #jump | 0 4px 14px rgba(0,0,0,.15) | jump-to-latest pill |
| flow-node | 0 1px 0 rgba(0,0,0,.04) | flow node hairline lift |
0 everywhere — `*{border-radius:0 !important}` is deliberate policy. Values are not part of the token set.
Triage Design System v0.13.1-experiment — the central, app-agnostic UI design authority.
Source of truth: /tokens/tokens.json. Showcase chrome only:
site/.