Spacing

Diwa provides two spacing scales: fluid tokens that scale smoothly between breakpoints using clamp(), and static tokens fixed to the 4 px base grid. Use fluid tokens for layout-level spacing and static tokens for component-internal spacing where pixel-perfect predictability matters.

Example

Spacing Fluid(xs – 3xl)

xs4–8px

sm8–14px

md12–20px

lg16–28px

xl24–40px

2xl32–56px

3xl48–80px

Size	Token	Range	Use
xs	--diwa-space-fluid-xs	4–8 px	Icon gaps, tight row padding
sm	--diwa-space-fluid-sm	8–14 px	Inline padding, list items
md	--diwa-space-fluid-md	12–20 px	Card padding (small)
lg	--diwa-space-fluid-lg	16–28 px	Card padding (standard) · grid gap
xl	--diwa-space-fluid-xl	24–40 px	Section spacing · page margin
2xl	--diwa-space-fluid-2xl	32–56 px	Large section gaps
3xl	--diwa-space-fluid-3xl	48–80 px	Page-level padding

Spacing Static(1 – 12)

14px

26px

38px

410px

512px

614px

716px

820px

924px

1032px

1148px

1296px

Step	Token	Value
1	--diwa-space-1	4 px
2	--diwa-space-2	6 px
3	--diwa-space-3	8 px
4	--diwa-space-4	10 px
5	--diwa-space-5	12 px
6	--diwa-space-6	14 px
7	--diwa-space-7	16 px
8	--diwa-space-8	20 px
9	--diwa-space-9	24 px
10	--diwa-space-10	32 px
11	--diwa-space-11	48 px
12	--diwa-space-12	96 px

Usage

Fluid spacing scales up or down based on viewport size in a predefined range. Static spacing is set to a specific pixel value and does not scale.

✓Use fluid tokens for layout-level spacing — section margins, page padding, and grid gaps — so space breathes proportionally with the viewport.
✓Use "md" as the default space value since it corresponds to the grid gap.
✓Use xs → lg for distances within a container: between heading, text, and buttons, or for spacing and grouping of form fields.
✓Use lg → 3xl for spacing between sections on a page.
✓Use static tokens inside custom components where precise, viewport-independent sizing matters.

Don't

✕Only use static tokens when needed — prefer fluid tokens for all layout-level spacing.
✕Don't use values outside the recommended range for a specific type of spacing.
✕Don't manually override a fluid spacer per viewport — the clamp() handles scaling automatically.
✕Don't mix fluid and static tokens on the same axis of a single layout container.

ℹ

Grid alignment: All static values snap to the 4 px grid. The two exceptions — --diwa-space-2 = 6 px and --diwa-space-4 = 10 px — match the PDS compact rhythm for icon rows and badge padding.

Styles

Import JS tokens for CSS-in-JS frameworks. Use CSS custom properties directly in stylesheets.

// JS — fluid
import {
  spacingFluid,
  spacingFluidXs,  spacingFluidSm, spacingFluidMd,
  spacingFluidLg,  spacingFluidXl,
  spacingFluid2xl, spacingFluid3xl,
} from '@diwacopilot/components/styles';

// JS — static
import {
  spacingStatic,
  spacingStatic1,  spacingStatic2,  spacingStatic3,
  spacingStatic4,  spacingStatic5,  spacingStatic6,
  spacingStatic7,  spacingStatic8,  spacingStatic9,
  spacingStatic10, spacingStatic11, spacingStatic12,
} from '@diwacopilot/components/styles';

/* ─── CSS — fluid (layout-level) ─────────────────────────────────────── */
.page-section {
  padding-block: var(--diwa-space-fluid-xl);   /* 24–40 px */
  gap:           var(--diwa-space-fluid-lg);   /* 16–28 px · grid gap */
}

.page-section + .page-section {
  margin-top:    var(--diwa-space-fluid-2xl);  /* 32–56 px */
}

/* ─── CSS — static (component-internal) ──────────────────────────────── */
.card {
  padding: var(--diwa-space-9) var(--diwa-space-7);  /* 24px 16px */
}

.card__header {
  display: flex;
  align-items: center;
  gap: var(--diwa-space-3);  /* 8px */
}

.badge {
  padding: var(--diwa-space-2) var(--diwa-space-5);  /* 6px 12px */
}

@use '@diwacopilot/components/styles' as *;

/* Layout-level — fluid spacing */
.page-section {
  padding-block: $diwa-space-fluid-xl;
  gap: $diwa-space-fluid-lg;
}

.page-section + .page-section {
  margin-top: $diwa-space-fluid-2xl;
}

/* Component-internal — static spacing */
.card {
  padding: $diwa-space-9 $diwa-space-7;
}

.card__header {
  display: flex;
  align-items: center;
  gap: $diwa-space-3;
}