Spacing
The 4-point grid, semantic padding and gap tokens, and the primitive scale.
Spacing tokens control padding, margins, and gaps. BDS modulates --padding-* and --gap-* via three named density modes (compact, comfortable, spacious) plus the unmodified default — components react automatically once [data-mode-spacing] is set on :root.
All spacing values must be multiples of 4px. The 4-point grid is enforced by npm run lint-tokens:grid, which blocks PRs that introduce off-grid values. This holds across every consuming project.
Semantic padding tokens
Purpose-bound spacing used in components. These values change between Base and Spacious modes.
Padding
| Preview | Token | CSS Variable | Maps to |
|---|---|---|---|
| padding-none | --padding-none | var(--space-0) | |
| padding-tiny | --padding-tiny | var(--space-200) | |
| padding-xs | --padding-xs | var(--space-250) | |
| padding-sm | --padding-sm | var(--space-300) | |
| padding-md | --padding-md | var(--space-400) | |
| padding-lg | --padding-lg | var(--space-600) | |
| padding-xl | --padding-xl | var(--space-800) | |
| padding-huge | --padding-huge | var(--space-1200) |
Semantic gap tokens
Gap tokens for flex and grid layouts. Typically smaller than the equivalent padding tokens.
Gap
| Preview | Token | CSS Variable | Maps to |
|---|---|---|---|
| gap-none | --gap-none | var(--space-0) | |
| gap-tiny | --gap-tiny | var(--space-50) | |
| gap-xs | --gap-xs | var(--space-100) | |
| gap-sm | --gap-sm | var(--space-150) | |
| gap-md | --gap-md | var(--space-200) | |
| gap-lg | --gap-lg | var(--space-400) | |
| gap-xl | --gap-xl | var(--space-600) | |
| gap-huge | --gap-huge | var(--space-800) |
Component spacing
Dedicated spacing tokens for specific component types.
| Token | CSS Variable | Maps to |
|---|---|---|
| Button | --padding-button | var(--space-200) |
| Input | --padding-input | var(--space-200) |
Spacing modes
Three named modes plus default modulate --padding-* and --gap-*:
- Default (no attribute) — values from
figma-tokens.cssbase. Used by product apps. compact— tighter spacing for dense interfaces.comfortable— moderate increase from default.spacious— large increase, typical for marketing sites and.body-classed surfaces.
Mode values auto-generate at tokens/modes-spacing.css — never hand-edit. Re-run npm run build:sd-figma after a Figma mode update.
Space scale (primitives)
The raw spacing scale from 0 to 176px. Semantic tokens reference these steps.
--space-00px--space-251px--space-502px--space-1004px--space-1506px--space-2008px--space-25010px--space-30012px--space-35014px--space-40016px--space-45018px--space-50020px--space-60024px--space-70028px--space-80032px--space-90036px--space-100040px--space-110044px--space-120048px--space-130052px--space-140056px--space-150060px--space-160064px--space-170072px--space-180080px--space-190084px--space-200088px--space-210096px--space-2200104px--space-2300112px--space-2400128px--space-2500136px--space-2600144px--space-2700152px--space-2800160px--space-2900168px--space-3000176pxRelated
- Cascade rules — how layers interact
- Color tokens — semantic surface tokens that pair with these spacings
- Typography tokens — type scale for content within these spaces