Spacing

Use spacing tokens to group related information and separate distinct tasks. Keep repeated controls and sections on the same scale so a screen can change density without many individual overrides.

Show dimensions

density: "normal"Padding 16pxGap 12pxFactor ×1

Switch density to compare the same panel with padding: "4" and gap: "3". Turn on Show dimensions to see arrows and pixel measurements for the outer padding and each gap between rows. Text and the 32px icon container keep their size. Values assume a 16px root; this is an illustrative composition, not a replacement for component defaults.

The scale

One spacing unit is 0.25rem before density is applied. The examples below assume a 16px root font size and normal density. The package also includes larger and half-step values; inspect the token playground for the full scale.

TokenRelative lengthPixels

spacing.00px

spacing.0.52px

spacing.14px

spacing.28px

spacing.312px

spacing.416px

spacing.624px

spacing.832px

spacing.1248px

The bars compare relative lengths at normal density; their labels give the exact values.

Spacing values and suggested uses

Token	Normal value	Suggested use
`0`	0px	Joined elements.
`0.5`	2px	A small visual adjustment.
`1`	4px	Tightly related details.
`2`	8px	An icon and its label, or compact control padding.
`3`	12px	Related controls.
`4`	16px	A group of fields or content padding.
`6`	24px	Distinct content groups.
`8`	32px	Section spacing.
`12`	48px	Major sections in a spacious layout.

These uses are suggestions. Start with the spacing already used by nearby components, then adjust for the content.

import { css } from "@hashintel/ds-helpers/css";

export const fieldGroup = css({
  display: "flex",
  flexDirection: "column",
  gap: "3",
  padding: "4",
});

Panda style properties take the token name ("4"). The token helper uses its full path, such as token.var("spacing.4"), when a CSS variable is needed outside a style object.

Padding, gaps, and margins

The same token can create space in different places. These diagrams isolate each property; the blue areas show where that space belongs.

Padding

Space inside the edge of a container. Give its content room on every side.

padding: "4" · 16px

Gap

Space between items in a grid or flex layout. No extra space at the outer edges.

gap: "3" · 12px

Margin

Space outside an element. Here, the lower panel has space above it.

marginTop: "6" · 24px

Prefer gap for repeated siblings in a flex or grid layout. Vertical margins in normal block flow can collapse; they do not always add together.

Density

The density utility sets --density-factor on an element. Spacing tokens multiply their base value by this inherited factor.

Density factors and values

Density	Factor	Value of spacing `4` at a 16px root
`compact`	0.75	12px
`normal`	1	16px
`comfortable`	1.25	20px

import { css } from "@hashintel/ds-helpers/css";

export const compactGroup = css({
  density: "compact",
  display: "flex",
  gap: "3",
  padding: "4",
});

Apply density to a coherent region, such as a toolbar or data panel. Check its children and overlays together. Reduced spacing still needs to leave enough room for labels, focus indicators, and pointer targets.

Grouping content

Use a smaller gap within a group and a larger one between groups. This creates hierarchy even before adding a divider or another container.

One rhythm everywhere

Equal spacing gives every row the same relationship, making separate groups harder to scan.

Every gap: spacing.2 / 8px

Make the groups visible

Keep related details close. A larger gap between groups helps the eye find the next task.

Within: 8px · between: 24px

Spacing and size

Use spacing.* through gap, padding, and margin properties. Use sizes.* through width and height properties. Size tokens are independent of the density factor: padding: "4" changes with density, while width: "4" continues to use the size scale.

compactPadding: 12px · size: 32px

normalPadding: 16px · size: 32px

comfortablePadding: 20px · size: 32px

Each example keeps its inner square at sizes.8 (32px at a 16px root). Only the spacing.4 padding changes with density.

Allow content to determine height where possible. A fixed-height field can clip a multiline label or validation message even when its surrounding gaps are correct.

See Responsiveness for adapting layout and the package setup for generating the required CSS.