CSS Spacing Tokens

Define a neutral base scale

CSS custom properties hold the source values. Components consume them with var(), so a scale change can move through the interface without a search-and-replace pass.

:root {
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
}

The numeric suffix describes position in the scale, not a pixel count. That gives you room to revise the values later without leaving names such as space-16 attached to a token that no longer equals 16 pixels.

Add semantic aliases where the role is stable

:root {
  --control-padding-block: var(--space-2);
  --control-padding-inline: var(--space-4);
  --card-gap: var(--space-4);
  --page-gutter: var(--space-6);
}

Keep aliases close to the component or layout layer that owns them. A global medium token says little. control-padding-inline tells a developer what can change together.

Expose the same source values in Tailwind

Tailwind CSS v4 uses theme variables to create utility classes. Map the --spacing-* namespace to the base variables instead of typing the values again. The inline option makes the generated utilities use the referenced --space-* values.

@import "tailwindcss";

@theme inline {
  --spacing-1: var(--space-1);
  --spacing-2: var(--space-2);
  --spacing-3: var(--space-3);
  --spacing-4: var(--space-4);
  --spacing-6: var(--space-6);
  --spacing-8: var(--space-8);
}

Tailwind's theme-variable documentation covers namespaces, referenced variables, and the inline option. MDN documents the underlying CSS custom-property behavior.

Roll the tokens out without a rewrite

1. Add the base scale without changing components.
2. Replace repeated values in one component family.
3. Add a semantic alias only when several instances share the same role.
4. Track exceptions and revisit them after the main paths have moved.

Generate CSS and Tailwind spacing tokens

The calculator also exports SCSS, JavaScript, JSON, and the Design Tokens Community Group format. Start with the format your codebase uses; a token pipeline earns its upkeep when more than one consumer needs the same source file.

Compare the values in the 4-point vs 8-point guide, or return to the spacing system guide.

For a shared token model across product design and frontend code, review the design system service.