# Spacing

Every gap, pad, and offset lands on a multiple of 4. The scale reaches from tight form fields to generous hero blocks, and components read it as `--bd-s-*` variables instead of fixed pixel values.

<h2 id="purpose">A 4-base rhythm</h2>

Spacing encodes relationship. Blocks that belong together sit closer, independent blocks sit farther apart. A single 4px base keeps that signal legible: two gaps either match or differ by a step a reader can perceive.

<h2 id="anatomy">Scale structure</h2>

Twelve steps run 4, 8, 12, 16, 20, 24, 32, 40, 56, 72, 96, and 128 px, exposed as `--bd-s-1` through `--bd-s-12`. Small steps handle control internals, mid steps handle grouping, large steps frame sections and hero blocks.

<h2 id="usage">Applying the scale</h2>

Space a group of blocks with the parent container's `gap`, not with the children's own margins. Use semantic HTML and local flex or grid CSS with `--bd-s-*` tokens. One container owns each rhythm.

<h2 id="details">Proximity ramp</h2>

Pick the gap between two blocks by how related they are. Tight (`--bd-s-1`) joins an element to its own satellite, such as a label and its control. Grouped (`--bd-s-3`) separates peers in one group. Related (`--bd-s-4`) separates headingless peer blocks. Distinct (`--bd-s-6`) separates sub-blocks within one surface. Zone (`--bd-s-8`) separates independent top-level sections and is the whitespace ceiling — when a firmer break is needed, add a boundary such as a `Divider` or a `Card` rather than more space.

<h2 id="accessibility">Density and targets</h2>

Keep controls far enough apart that a pointer or a focus ring cannot land ambiguously between them. Grouped is the practical floor between adjacent interactive rows; Tight is reserved for an element and its own satellite. Density changes the scale a component consumes, so verify hit areas after switching density.

<h2 id="tokens">Tokens</h2>

`BD_TOKENS.space` holds the numeric scale, and `bdBuildCssVars` emits it as `--bd-s-1` through `--bd-s-12`. Reference the variables in component styles; read the numbers only when code needs the same values as CSS.

<h2 id="related">Related</h2>

Compose rhythm with semantic HTML and `--bd-s-*` tokens. Use [Section](/docs/components/section), [Divider](/docs/components/divider), or [Card](/docs/components/card) when a stable public frame is needed.