Spacing

Spacing is the distance around and between elements. It shapes components (the space between an icon and its label) and layouts (the margin between the content and the window edge). Spacing follows an 8dp scale, and tokens keep that scale in one place.

There are three kinds:

• Padding is the space inside an element, between its edge and its content.
• Gaps are the spaces between elements in a row, column or grid.
• Margins are the space outside an element, between it and its parent or the screen edge.

Each one can be vertical, horizontal, or on one edge: top, bottom, leading or trailing. Leading and trailing swap sides in right-to-left languages, so write them as logical properties (padding-inline, margin-inline-start).

Define padding and gaps on the parent container first. Margins on child elements are harder to keep uniform, so use them only for space beyond the parent's padding, or in a layout.

The unit is --md-sys-space-unit, 8px. Each token is a multiple of it. The token name is the value times 100, so space200 is 2 units (16px). The in-between values (2, 4, 6 and 10px) are nested units for small gaps, such as an icon and its label.

The tokens are defined in labs/gb/styles/space/md-space-tokens.scss. They are fixed pixel values, so they do not grow with the text size.

A product can add a token that follows the same pattern. For example, --md-sys-space-225: calc(var(--md-sys-space-unit) * 2.25) gives 18px.

Some spacing should change with the window. Three adaptive tokens do this:

• --md-sys-space-adaptive-inline: horizontal padding
• --md-sys-space-adaptive-block: vertical padding
• --md-sys-space-adaptive-gap: gap between elements

Each one points at a scale token that depends on the window size class. The classes are the ones in Adaptive layout.

Direct children of a .md-window element follow that element's width, so a layout can adapt to its pane rather than the screen. Other elements follow the viewport. The spacing unit does not change with the window.

<div class="item-list">
  <md-gb-button color="tonal">Inbox</md-gb-button>
  <md-gb-button color="tonal">Drafts</md-gb-button>
  <md-gb-button color="tonal">Sent</md-gb-button>
</div>

.item-list {
  display: grid;
  gap: var(--md-sys-space-adaptive-gap);
  padding-inline: var(--md-sys-space-adaptive-inline);
  padding-block: var(--md-sys-space-adaptive-block);
  background: var(--md-sys-color-surface-container-low);
}

The adaptive tokens are defined, but no labs/gb component reads them yet: component spacing is the same at every window size today. Use them in your own layouts, or remap a component's own spacing property to one (see below).

Components map their padding, margins and gaps to scale tokens in their own custom properties (--leading-space, --icon-label-space and so on), so a product can change one mapping and every use follows. For example, md-gb-button { --leading-space: var(--md-sys-space-adaptive-inline); } makes a button's leading padding follow the window class.

Every value is the same as before, so nothing changes visually. A few values are still plain pixels: some generated button, list, FAB, button group and navigation rail values, the dialog and sheet paddings, and the few values a component reads in code (a carousel's leading padding, a tooltip's viewport margin, a tab indicator's inset).

Density changes components, not the spacing scale. Each density step removes height from the component, and the component's touch target stays 48dp. See Density.

The spec's accessibility guidance is one point: when text is scaled up to 200%, keep the same spacing. Spacing tokens are fixed in pixels, so the spacing stays the same while the text grows. For touch targets and focus, see Accessibility.

• Use the scale tokens, not hardcoded pixel values. A raw 16px will not follow a remapped token.
• Set spacing on the parent, not the children, unless you need space beyond the parent's padding.
• Use logical properties (padding-inline, gap) so right-to-left layouts flip correctly.
• Do not adapt spacing to density yourself. Set the density attribute on the component and let it apply its own steps.
• Keep the spacing the same at 200% text. Do not replace a token with a value that grows with the text.