Spacing

Overview

Byteion uses named spacing tokens mapped into Tailwind utilities, so spacing decisions are governed by the design system instead of random one-off values.

Spacing tokens help:

• keep cards, forms, tables, modals, and dashboards visually consistent
• support compact, default, and comfortable density modes
• reduce one-off arbitrary classes like p-[13px]
• make future design updates safer — change one token, update every component

Spacing token model

Byteion organises spacing into three semantic groups, each with a distinct purpose:

Inset spacing controls internal padding inside components — buttons, inputs, badges, cards, and panels. Use p-inset-* or px-inset-* / py-inset-*.

Stack spacing controls the gap between sibling elements — form fields, toolbar items, card sections, and vertical lists. Use gap-stack-* or space-y-stack-*.

Surface spacing defines the padding of layout containers — cards, panels, modals, and page sections. Use p-surface-*.

Spacing token table

All tokens are defined in packages/tokens/spacing.js and mapped to Tailwind utilities through the shared preset:

Inset spacing

Inset tokens control internal padding. Components use these for button padding, input padding, and card internal spacing:

Tailwind classes: p-inset-xs, px-inset-sm, py-inset-md, pt-inset-lg, pb-inset-xl, and any combination of the padding utility prefix with the token suffix.

Stack spacing

Stack tokens control the gap between vertically or horizontally stacked elements. Use gap-stack-* on flex/grid containers or space-y-stack-* for simple vertical stacks:

Tailwind classes: gap-stack-xs, gap-stack-sm, gap-stack-md, gap-stack-lg, gap-stack-xl, gap-stack-2xl. The legacy aliases p-sm, p-md, p-lg (and their gap-* / space-y-* counterparts) are backed by --spacing-* CSS variables and support runtime overrides.

Surface spacing

Surface tokens define the padding of layout containers. Use p-surface-card, p-surface-panel, or p-surface-section on wrapping elements:

Practical usage examples

Card padding:

<div class="rounded-xl border border-border bg-card p-surface-card shadow-card">
  <div class="space-y-stack-md">
    <h3 class="text-lg font-semibold text-foreground">Billing details</h3>
    <p class="text-sm text-muted-foreground">Update invoice and payment settings.</p>
  </div>
</div>

Form field stack:

<div class="space-y-stack-md">
  <div>
    <label class="text-sm font-medium text-foreground">Email</label>
    <input class="w-full rounded-lg border border-border px-inset-md py-inset-sm" />
  </div>
  <div>
    <label class="text-sm font-medium text-foreground">Password</label>
    <input type="password" class="w-full rounded-lg border border-border px-inset-md py-inset-sm" />
  </div>
</div>

Toolbar gap:

<div class="flex items-center gap-stack-sm">
  <button class="rounded-lg bg-primary px-inset-md py-inset-sm text-sm font-medium text-primary-foreground">Save</button>
  <button class="rounded-lg border border-border px-inset-md py-inset-sm text-sm font-medium text-foreground">Cancel</button>
</div>

Page section spacing:

<div class="space-y-stack-2xl">
  <section class="rounded-xl border border-border bg-card p-surface-section">
    <h2 class="text-xl font-semibold text-foreground">General settings</h2>
  </section>
  <section class="rounded-xl border border-border bg-card p-surface-section">
    <h2 class="text-xl font-semibold text-foreground">Notifications</h2>
  </section>
</div>

Modal body spacing:

<div class="fixed inset-0 z-50 flex items-center justify-center">
  <div class="w-full max-w-lg rounded-xl border border-border bg-card p-surface-panel shadow-lg">
    <div class="space-y-stack-md">
      <h3 class="text-lg font-semibold text-foreground">Confirm deletion</h3>
      <p class="text-sm text-muted-foreground">This action cannot be undone.</p>
    </div>
  </div>
</div>

Choosing the right spacing token

• Use inset tokens for internal component padding — buttons, inputs, badges, and card interiors.
• Use stack tokens for spacing between siblings — form fields, toolbar buttons, list items, and card sections.
• Use surface tokens for containers and sections — cards, panels, modals, and page-level blocks.
• Use smaller tokens (xs, sm) for dense dashboards, tables, and admin lists.
• Use larger tokens (lg, xl, 2xl) for empty states, onboarding flows, docs, and marketing-like sections.

Density guidance

Different interfaces need different density levels. Choose a density and apply it consistently within each component or screen:

Do not mix compact and comfortable spacing randomly inside the same component. Density should be intentional and consistent.

Correct and incorrect examples

<div class="space-y-stack-md">
  <label class="text-sm font-medium text-foreground">Email</label>
  <input class="w-full rounded-lg border border-border px-inset-md py-inset-sm" />
</div>

<div class="space-y-[13px]">
  <label class="text-[13px]">Email</label>
  <input class="w-full rounded-[11px] px-[17px] py-[9px]" />
</div>

Customization

Spacing tokens are defined in packages/tokens/spacing.js and consumed through the shared Tailwind preset. The approach to customization depends on how you use the tokens:

• Build-time tokens — the semantic inset, stack, and surface tokens are compiled from JavaScript. To change them, update packages/tokens/spacing.js and rebuild your assets.
• Runtime tokens — the legacy sm, md, lg spacing keys are backed by --spacing-sm, --spacing-md, and --spacing-lg CSS variables. These can be overridden at runtime in your variables.css or theme file:

:root {
  --spacing-sm: 0.25rem;   /* Tighter compact mode */
  --spacing-md: 0.75rem;   /* Reduced default rhythm */
  --spacing-lg: 1.25rem;   /* More compact sections */
}

For full control across all token groups, modify the JavaScript source file and rebuild. Do not claim runtime spacing changes unless your setup uses CSS variable-backed tokens.

Do and Don't

Developer tips

Related

• Design Principles — Why tokens matter
• Design Tokens — Source of spacing values
• Stack — Vertical spacing layout
• Container — Width-constrained layout
• Card — Surface padding example
• Form — Field spacing example
• Table — Dense data spacing
• Layout — Page and section rhythm