space

The use-design-tokens rule checks that CSS spacing declarations (e.g. margins, padding, gaps, inset, etc.) use design token variables instead of hardcoded values. This ensures consistent spacing across the application and makes it easier to maintain design system consistency.

This rule applies to the following properties:

• padding and all of its longhand properties

• margin and all of its longhand properties

• inset and all of its longhand properties

• gap, column-gap, row-gap

• Positioning attributes: left, right, top, and bottom.

Note that the following properties accept both space and size tokens:

• inset and all of its longhand properties

• Positioning attributes: left, right, top, and bottom

Use space tokens when these properties represent spacing/positioning offsets, and size tokens when they represent element dimensions.

Space tokens are rem-valued, and rem is not 16px in chrome. A chrome document’s root font size is the system UI font size, which is roughly 11px on macOS, 12px on Windows and 14 to 15px on Linux; only content documents get 16px. The space scale is 16px-based, so every space token comes out proportionally shorter in chrome - 25% shorter at a 12px root.

A px value and the space token this rule suggests for it are therefore equal only at a 16px root, autofixed replacements included. Where the quantity must not scale with the system font, such as a geometric bleed, an overlay inset or an icon box, use a fixed-px token instead: --size-item-*, --icon-size-*, --size-image-* and --size-layout-* are all literal px.

Examples of incorrect code for this rule

.custom-button {
  padding: 0.5rem;
}

.card {
  margin-inline: 8px;
}

.overlay {
  inset: 1rem;
}

.grid {
  gap: 4px 12px;
}

Examples of correct token usage for this rule

.custom-button {
  padding-block: var(--space-small);
}

.custom-button {
  padding-inline: var(--space-medium);
}

.custom-button {
  column-gap: var(--space-xxsmall);
}

.custom-button {
  margin-block-start: var(--space-large);
}

/* Local CSS variables that reference valid space tokens are allowed */
:root {
  --custom-space: var(--space-xsmall);
}

.custom-button {
  padding: var(--custom-space);
}

.custom-button {
  margin-inline-end: var(--custom-space, --space-xlarge);
}

.overlay {
  inset: var(--space-small);
}

.positioned-element {
  top: var(--space-large);
  left: var(--space-medium);
}

The rule also allows these values to be non-token values:

.inherited-inset {
  inset: inherit;
}

.unset-padding {
  padding: unset;
}

.initial-row-gap {
  row-gap: initial;
}

.auto-margin {
  margin-inline: auto;
}

.zero-padding {
  padding: 0;
}

Autofix functionality

This rule can automatically fix some violations by replacing common pixel values with appropriate space tokens. Examples of autofixable violations:

/* Before */
.a {
  margin: 2px;
}

/* After autofix */
.a {
  margin: var(--space-xxsmall);
}

/* Before */
.a {
  padding: 8px 16px;
}

/* After autofix */
.a {
  padding: var(--space-small) var(--space-large);
}

/* Before */
.a {
  gap: 24px 32px;
}

/* After autofix */
.a {
  gap: var(--space-xlarge) var(--space-xxlarge);
}