# Spacing (/foundations/spacing)



<div className="hd-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.

  <SpacingExplorer />

  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 [#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](/foundations/design-system#token-playground) for the full scale.

  <SpacingScale />

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

  <details className="hd-space-reference">
    <summary>
      Spacing values and suggested uses
    </summary>

    | 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.               |
  </details>

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

  ```tsx
  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 [#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.

  <SpacingAnatomy />

  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 [#density]

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

  <details className="hd-space-reference">
    <summary>
      Density factors and values
    </summary>

    | Density       | Factor | Value of spacing `4` at a 16px root |
    | ------------- | ------ | ----------------------------------- |
    | `compact`     | 0.75   | 12px                                |
    | `normal`      | 1      | 16px                                |
    | `comfortable` | 1.25   | 20px                                |
  </details>

  ```tsx
  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](/foundations/accessibility#layout-targets-and-motion).

  ## Grouping content [#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.

  <SpacingGrouping />

  ## Spacing and size [#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.

  <SpacingSizes />

  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](/foundations/responsiveness) for adapting layout and [the package setup](/foundations/design-system#source-and-setup) for generating the required CSS.
</div>