> ## Documentation Index
> Fetch the complete documentation index at: https://substrate.docs.unknowncreatives.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Spacing Token Reference

> Substrate's continuous spacing model: one brand space unit scaled by runtime density and scale factors — no numbered spacing ladder.

Substrate emits exactly **one** spacing token: `--space-unit`, the brand's spatial unit in px (`space.unit`; every bundled demo brand uses 4). There is no `--space-1` … `--space-16` ladder. All spacing is computed at the use site from three independent scalars.

## The composition

Every spatial value in generated component CSS has this shape — real output from the badge component:

```css theme={null}
.sub-badge[data-ucs] {
  /* 8px at default density=1, scale=1, space-unit=4 */
  --surface-padding-x: calc(var(--density) * var(--scale) * var(--space-unit) * 2);
  /* 2px at default density=1, scale=1, space-unit=4 */
  --surface-padding-y: calc(var(--density) * var(--scale) * var(--space-unit) * 0.5);
  /* 6px at default density=1, scale=1, space-unit=4 */
  --surface-gap-x: calc(var(--density) * var(--scale) * var(--space-unit) * 1.5);
}
```

A component authors a spatial *multiplier* (here 2, 0.5, 1.5 — fractions welcome); the engine composes it with:

* `--space-unit` — the brand constant (`space.unit`, px).
* `--density` — the user's continuous density preference (`densityFactor`, 0.8 → 1.3), written by the runtime. **This is the lever for scoped density overrides**, not `--space-unit`.
* `--scale` — a continuous size multiplier for scaled contexts.

Because density is a runtime variable, changing it re-lays-out the interface instantly — no rebuild.

## Density presets

Brands name positions on the density continuum under `presets.density`. The names are brand-chosen (an open map). One brand might ship:

```yaml theme={null}
presets:
  density:
    compact:
      density-factor: 0.85
    default:
      density-factor: 1.0
    comfortable:
      density-factor: 1.15
```

Another names its levels `discovery` / `default` / `workspace` — proof the set is convention, not enum. The brand bounds how far users can push density via `flexibility.density` (`min`/`max`).

## Radius

Corner radius follows the same pattern: `--radius: calc(var(--radius-base) * var(--density))`, with `--radius-base` from `shape.radius-base`.

## All continuous scalars

For reference, the full scalar set (generated from the ground-truth manifest):

| Token                 | Description                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `--density`           | Continuous density multiplier written by the runtime from densityFactor (0.8 → 1.3). Scales spacing, sizing, and border radius at use sites. |
| `--scale`             | Continuous size multiplier composed into spatial calc() expressions alongside --density.                                                     |
| `--contrast-factor`   | The user's continuous contrast preference (0.75 → 1.5). Scales every APCA Lc target.                                                         |
| `--motion-factor`     | Continuous motion preference, 0 (instant/reduced) → 1 (full brand duration). Defaults to 0.75; set to 0 under prefers-reduced-motion.        |
| `--type-scale-factor` | Continuous type-scale preference (0.9 → 1.4), folded into --effective-ratio.                                                                 |
| `--duration-base`     | The brand's base duration in ms, from motion.duration-base.                                                                                  |
| `--duration`          | Resolved duration: calc(var(--duration-base) \* var(--motion-factor)).                                                                       |
| `--easing`            | The brand's single authored easing string, from motion.easing.                                                                               |
| `--radius-base`       | The brand's base corner radius in px, from shape.radius-base.                                                                                |
| `--radius`            | Resolved radius: calc(var(--radius-base) \* var(--density)).                                                                                 |
| `--space-unit`        | The brand's spatial unit in px, from space.unit. The only --space-\* token; spacing is computed, not enumerated.                             |
| `--scale-ratio`       | The brand's modular type ratio, from typography.scale-ratio.                                                                                 |
| `--effective-ratio`   | The ratio actually used for type sizing: calc(1 + (var(--scale-ratio) - 1) \* var(--type-scale-factor)).                                     |
| `--font-size-base`    | Base font size in rem, from typography.base-font-size.                                                                                       |
| `--font-size-quantum` | Rounding quantum for computed font sizes (default 0.25rem).                                                                                  |
| `--font-size-rate`    | Fluid typography rate, from typography.fluid.                                                                                                |
| `--weight-bump`       | Font-weight increase that kicks in at high contrast factors.                                                                                 |
| `--font-heading`      | Heading font stack, from typography.heading-family.                                                                                          |
| `--font-body`         | Body font stack, from typography.body-family.                                                                                                |
| `--font-mono`         | Monospace font stack, from typography.mono-family.                                                                                           |
| `--ucs-focus-ring`    | The solved focus-ring color (target Lc 60 × contrastFactor).                                                                                 |
| `--ctx-surface-l`     | The lightness of the actual surface the solver resolved against — the context every foreground was solved for.                               |

<Card title="Config: Spacing & Density" icon="ruler" href="/brand-config/spacing-density">
  How to author space.unit and density presets in a brand config.
</Card>