# Spacing & Sizing

All spacing and sizing values are expressed as CSS custom properties from the `--sizing-sizing-*` scale and the semantic `--padding-*` aliases.

## Sizing Scale

| Token | Value | Usage |
|---|---|---|
| `--sizing-sizing-0` | 0px | No spacing |
| `--sizing-sizing-1` | 1px | Hairline borders |
| `--sizing-sizing-2` | 2px | Micro gaps, shadow spread |
| `--sizing-sizing-3` | 3px | — |
| `--sizing-sizing-4` | 4px | Extra-small spacing |
| `--sizing-sizing-8` | 8px | Small spacing |
| `--sizing-sizing-10` | 10px | Medium spacing |
| `--sizing-sizing-12` | 12px | Medium-large spacing |
| `--sizing-sizing-16` | 16px | Large spacing, extra-large border radius |
| `--sizing-sizing-20` | 20px | Large spacing, shadow blur |
| `--sizing-sizing-28` | 28px | — |
| `--sizing-sizing-36` | 36px | Extra-large padding |
| `--sizing-sizing-48` | 48px | Large touch targets |

## Semantic Padding Aliases

| Token | Value | Usage |
|---|---|---|
| `--padding-extra-small` | 2px | Tightest padding — badges, tags |
| `--padding-small` | 4px | Compact elements |
| `--padding-medium-small` | 8px | Standard small padding |
| `--padding-medium` | 10px | Standard medium padding |
| `--padding-medium-large` | 12px | Medium-large — section insets |
| `--padding-large` | 20px | Large padding — card bodies |
| `--padding-extra-large` | 36px | Hero sections |

## Border Radius

| Token | Value | Usage |
|---|---|---|
| `--radius-small` | 4px | Badges, tags, small elements |
| `--radius-medium` | 8px | Cards, inputs, dropdowns |
| `--radius-large` | 12px | Modals, panels |
| `--radius-extra-large` | 16px | Pills, popovers |

## Shadow System

| Token | Usage |
|---|---|
| `--shadows-xy-axis-small` + `--shadows-blur-small` | Subtle elevation (1px, 4px blur) |
| `--shadows-xy-axis-medium` + `--shadows-blur-medium` | Card / popover elevation (4px, 8px blur) |
| `--shadows-xy-axis-large-default` + `--shadows-blur-large` | Modal / sidecar elevation (4px, 20px blur) |
| `--shadows-color-light` / `--shadows-color-dark` | Shadow colour (dark blue `#0d2435`) |

## Scrollbar Tokens

| Token | Usage |
|---|---|
| `--scrollbar-default` | Default scrollbar thumb |
| `--scrollbar-hover` | Scrollbar thumb on hover |
| `--scrollbar-pressed` | Scrollbar thumb pressed |

## Decision Tree: Choosing Spacing

```
Gap between inline elements (icon + text)? → 4px (--padding-small)
Gap between stacked form fields? → 8px–12px (--padding-medium-small or --padding-medium-large)
Card body padding? → 20px (--padding-large)
Section inset? → 12px–20px
Hero / page header padding? → 36px (--padding-extra-large)
```

## Common Mistakes

- Do NOT use arbitrary pixel values — always map to a token from the sizing scale.
- Do NOT mix `padding` and `margin` with raw values when a semantic `--padding-*` token exists.