Skip to content

Spacing and sizing draft v0.2.0

The spacing scale and the element sizes from the Figma library, which components pick their paddings, gaps, heights and icon sizes from.

Two scales from the Figma library (Dimension), as they are, measure everything: space, the room inside and between elements, on a 4 px grid; and size, the dimensions of elements such as icons and avatars. Components and the docs site read them directly: each component picks its padding, gaps, heights and icon sizes from them in its own tokens. There is no semantic spacing layer in between.

Guidelines

From apps/docs/content/foundations/spacing.md

Overview

Two scales from the Figma library (Dimension) measure everything in the system:

  • Space is the room inside and between elements: paddings, gaps, margins. It sits on a 4 px grid, with a few finer steps (1, 2, 3, 5, 6, 7, 10 and 14 px) for optical adjustments. Each key is its value in px, so space.12 is 12 px.
  • Size is the dimension of an element: an icon, an avatar, an app icon. Its steps are numbered (size.1 is 8 px, size.10 is 128 px).

There is no semantic layer on top of them: components and the docs site read these scales directly.

Building with the scales

Each component picks its dimensions from the scales, per size, in its own tokens. The Button, from extra small to large:

Dimension Steps
Inner padding space.6, space.8, space.12, space.16
Gap between icon and label space.4
Minimum height space.24, space.32, space.40, space.48
Icon size size.2, size.2, size.3, size.4

A control takes a minimum height, never a fixed one: it grows when its content needs more. A new component with sizes should pick the same steps for the same sizes, so a small button and a small field line up.

Platforms

iOS

Lengths are read as points. The control heights are the same as on the web: the Figma library has no platform values, so the extra small, small and medium controls are under the 44 pt hit region Apple recommends (see Accessibility).

Android

Lengths are read as density-independent pixels. The control heights are the same as on the web, so the extra small, small and medium controls are under the 48 dp touch target Android recommends (see Accessibility).

Layout

There are no page layout tokens yet (page margins, section spacing, grid columns). Until a decision names them, layouts pick from the spacing scale. The docs site does the same with literal layout lengths, and will switch when layout tokens exist.

Accessibility

  • 24 px minimum target. Every pointer target is at least 24 by 24 CSS pixels (WCAG 2.5.8 Target Size (Minimum)). The extra small control height is exactly that minimum: no control may go below it. A component that has to be smaller relies on one of the criterion’s exceptions (enough spacing around the target, for instance), stated and cited in its spec.
  • Heights grow with text. Minimum heights, not fixed ones, keep labels from being clipped when people enlarge text up to 200% (WCAG 1.4.4 Resize Text).
  • 44 pt on iOS. Apple asks for a hit region of at least 44 by 44 pt (Apple HIG: Buttons, Accessibility, mobility). The extra small, small and medium controls (24, 32 and 40 pt) fall under it today: the overlay that raised them belonged to a semantic layer the Figma library does not have .
  • 48 dp on Android. Android asks for touch targets of at least 48 by 48 dp (Android: use large, simple controls, Compose: minimum touch target sizes). The extra small, small and medium controls fall under it today, for the same reason .
  • Typography: the label sizes that go with these heights.
  • Iconography: the icons drawn at the control icon sizes.
  • Platforms: the overlays (font families only today).
  • Button, Icon button, Dropdown: the components built on these dimensions.