Spacing

Every spacing value in PDS is a multiple of 4px, and there are ten of them: spacing[0] through spacing[9]. The numbers are the names — there is no spacing.sm — so the scale can be read in either direction but cannot gain a value in the middle without renaming everything above it.

spacing[1] to spacing[4] climb in fours: 4, 8, 12, 16. From spacing[4] on they climb in eights: 24, 32, 40, 48, 56.

So the scale has no 20px and no 28px, and the gap between its two most-used steps is a quarter of the gap at the top. If a layout wants 20px, the answer is 16 or 24 rather than a new step, because inserting one between 4 and 5 renumbers every token above it and silently changes the meaning of every spacing[6] already written.

Across @persona/design-system, spacing tokens set padding 59 times and gap 49 times. They also set height 5 times, width 4 times, right and left 6 times between them, text-underline-offset once, and border-radius twice.

That last one is Modal and Match Highlight, whose corners are both spacing[1]. It works — spacing[1] and borderRadius.md are both 4px — and it means the scale is being used as a general length scale rather than a rhythm. Retune a step to fix vertical rhythm and you also move a corner radius and an underline.

spacing[1] and spacing[2] — 4px and 8px — account for 267 of the 396 spacing references in @persona/design-system, and spacing[8] and spacing[9] are used once each. Components are dense, and the scale reflects it: nearly all of it is the space inside a control. The top of the scale belongs to the things that arrange controls rather than contain them — spacing[7] is used by the PageLayout pattern, spacing[8] by Data Table, spacing[9] by CardV2. Below 16px you are spacing a control’s interior, above it you are spacing a page, and those are different decisions sharing one set of numbers.