Spacing

Spacing is a single base unit stepped on a 4px scale. Tailwind v4 supplies the base --spacing variable (0.25rem = 4px); every spacing utility (p-4, gap-2, mt-6, w-12) resolves to calc(var(--spacing) * N). Prefer a scale step; an arbitrary value (p-[3px]) is for an optical fix the scale cannot express, the way upstream's own components use one.

The scaleCopy Anchor Link

Steps compose from the 4px base: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64px (and beyond). The SpacingScale bars above are derived live with calc(var(--spacing) * step) — the px figures are descriptive labels, not separate tokens. There is no per-step token; the scale is the base unit multiplied by Tailwind's numeric utility name.

var(--spacing)Copy Anchor Link

--spacing is Tailwind v4's own base unit (0.25rem), not a @vegastack/design-tokens value — the tokens package ships no --spacing of its own. Internal utilities reference it directly when they need a spacing-relative length, e.g. the scroll-fade reveal in @vegastack/design-tokens/utilities.css uses calc(var(--spacing) * 24). In app code, reach for the named utility. If a repeated computed length is truly needed, name it once (a CSS variable or a utility) rather than repeating the calculation in every class string:

<div className="gap-2 p-4" />
<div className="px-6" />

Tailwind usageCopy Anchor Link

Padding, margin, gap, width/height, inset, and space-* all read the same scale, so a layout stays on-grid by construction. Prefer gap on flex/grid containers over per-child margins.

<div className="flex flex-col gap-4 p-6">
  <header className="flex items-center gap-2" />
  <section className="space-y-3" />
</div>

Page rhythmCopy Anchor Link

One recipe spaces every product page, on the stock scale above. These are defaults, not tokens: reach for them first, and depart only where a surface has a reason.

<AppShellContent>
  <AppShellPage>
    <PageHeader title="Tasks" actions={<Button>New task</Button>} />
    <div className="flex flex-col gap-8">
      <section className="flex flex-col gap-3">
        <ListToolbar search={search} filterRow={<FilterRow chips={chips} />} />
        <DataList columns={columns} data={tasks} getRowId={(t) => t.id} />
      </section>
      <section className="flex flex-col gap-3">
        <h2 className="font-heading text-base font-medium">Completed</h2>…
      </section>
    </div>
  </AppShellPage>
</AppShellContent>

AppShellContent is the scrolling region and carries no padding of its own, so the gutter is AppShellPage's — see Page layout for the widths and the gutter scale. A card that holds a section wears its padding through --card-spacing, never a local p-*, so a size="sm" card tightens every part at once. FieldGroup and Field already space fields and their parts; an override on one form is the drift this recipe exists to prevent.

RelatedCopy Anchor Link

• Radius — the corner-rounding ramp, derived from one --radius, that pairs with spacing on every surface.
• Card and Separator — layout primitives that consume the spacing scale for their internal padding and rhythm.