Responsive Spacing Tokens — Viewport-Adaptive Spacing Values

Responsive Spacing with Design Tokens

Static spacing values (like 16px) work on desktop but may be too generous on mobile or too tight on large displays. Responsive spacing tokens solve this by adapting values to the viewport.

CSS clamp() Approach

The modern approach uses clamp() to create fluid spacing that scales smoothly:

:root {
  --spacing-sm: clamp(0.5rem, 1vw, 0.75rem);
  --spacing-md: clamp(0.75rem, 2vw, 1.5rem);
  --spacing-lg: clamp(1rem, 3vw, 2rem);
  --spacing-xl: clamp(1.5rem, 4vw, 3rem);
  --spacing-2xl: clamp(2rem, 6vw, 4rem);
}

Media Query Override Pattern

For more control, override token values at specific breakpoints:

:root {
  --spacing-section: 2rem;
  --spacing-card-padding: 1rem;
}

@media (min-width: 768px) {
  :root {
    --spacing-section: 3rem;
    --spacing-card-padding: 1.5rem;
  }
}

@media (min-width: 1280px) {
  :root {
    --spacing-section: 4rem;
    --spacing-card-padding: 2rem;
  }
}

Container Query Tokens

With container queries, spacing can adapt to the component's container rather than the viewport:

.card-container {
  container-type: inline-size;
}

@container (min-width: 400px) {
  .card {
    padding: var(--spacing-lg);
  }
}

Token File Structure

In your JSON token file, you can express responsive values as objects with breakpoint keys, then transform them during build time with tools like Style Dictionary.