Spacing

Updated: Sep 24, 2026
Choose every gap, inset, and content padding from the --uit-spacing-* scale. Pick the ordinal step that expresses the relationship between regions, then let the theme resolve its length.
Spacing and icon sizes are CSS custom properties declared at the document root by the library stylesheet. Nothing about them is exported from JavaScript — read them with var().

The scale

Twelve steps, smallest to largest:
TokenTypical use
--uit-spacing-2xs
Hairline separation between tightly coupled parts.
--uit-spacing-xsmall
Gap between an element and its immediate label or indicator.
--uit-spacing-small
Gap inside a compact group.
--uit-spacing-sm-med
Gap between related controls.
--uit-spacing-medium
Gap between items in a group.
--uit-spacing-med-lg
Gap between elements in a text stack.
--uit-spacing-large
Screen and surface content inset.
--uit-spacing-xlarge
Separation between distinct sections.
--uit-spacing-2xl
Major section break.
--uit-spacing-3xl
Larger major section break.
--uit-spacing-4xl
Generous vertical rhythm on sparse screens.
--uit-spacing-5xl
Largest step; use sparingly.
The steps are not evenly spaced and they do not map one-to-one onto the corner radius scale. Choose by relationship, not by arithmetic.

Icon sizes

Icon dimensions are their own ordinal scale, seven steps smallest to largest: --uit-icon-2xs, --uit-icon-xsmall, --uit-icon-small, --uit-icon-medium, --uit-icon-large, --uit-icon-xlarge, --uit-icon-2xl.
Components that render icons or media choose the size that fits their anatomy, and where a size is configurable they expose a closed enum rather than a length — ButtonItemIconSize, AvatarSize, ChipAvatarSize, MediaWrapperSize, and similar. Use the --uit-icon-* tokens only for icons you place yourself.

Component metrics are not part of this scale

The stylesheet also declares per-component anatomy variables: minimum row heights, internal icon container sizes, the thickness of a divider, and the lengths of the fading edges a scroll container draws. Each metric belongs to the component that reads it. Component anatomy variables are not a supported application customization surface and can change with the component.

Usage

import { TextStyle, TextView } from '@wearables-ui-toolkit/mrbd';

<section className="detail-block">
  <TextView as="h2" textStyle={TextStyle.HEADING2}>Route</TextView>
  <TextView textStyle={TextStyle.BODY2}>Turn right in 200 metres</TextView>
</section>

.detail-block {
  display: flex;
  flex-direction: column;
  gap: var(--uit-spacing-med-lg);
  padding-inline: var(--uit-spacing-large);
}

Standard insets

  • General screen content uses the large horizontal inset.
  • ScrollView, VerticalList, and ButtonRail extend to both screen edges; their children own the content insets. Do not wrap them in a page inset. Inside a ScrollView, put authored content in a single wrapper that carries the large inline inset rather than padding the scroll viewport itself.
  • A backdrop-style Panel may also extend edge to edge. Modals stay inset.
  • Content that is not full bleed inside Container, StaticContainer, Surface, and Panel uses the large spacing token from the component edge.
  • A bottom action dock holding a ButtonRail or ButtonGroup sits outside the route’s vertical scroller and keeps the xsmall spacing token as its bottom clearance.
  • Adjacent ListItem rows have no additional gap between them.

Layout guidance

  • Application CSS owns arrangement between regions. Component anatomy owns spacing inside a component.
  • Lay out against available space: flexible tracks, percentages, and intrinsic component sizes. Never assume a device width or height.
  • A fixed length is still hardcoded when it sits inside min(), max(), clamp(), a grid track, or a shadow. Changing the unit to em or rem does not make it a token.
  • Use one spacing token per gap so the scale expresses each relationship.
  • Let scroll containers reach the screen edges so directional scrolling and fading edges use the full viewport.

Avoid

  • Reference tokens directly rather than copying their resolved lengths into application code.
  • Compose around component anatomy instead of compensating for it with margins.
  • Let fading edges overlay the scroll boundary rather than reserving permanent space for them.
  • Use one rounded surface for a region instead of nesting another only to add padding.
Corner radius, Typography, Screen layout, ScrollView.