Spacing

Learn how to use spacing tokens in your design system.

Overview

This spacing scale ranges from 4xs to 5xl, allowing fine-tuned control over both compact and expansive layouts.

Spacing is a fundamental part of layout design. It ensures visual consistency, rhythm, and alignment across components and sections.

• 4xs ~ 2xs Used for micro spacing like between icons, tags, or inline controls.
• xs ~ sm Suitable for spacing between form fields, list items, or small content blocks.
• md The default spacing for most UI components.
• lg ~ xl For separating grouped content or larger components.
• 2xl ~ 5xl Ideal for layout gutters, section spacing, or hero areas.

For example, use gap:md for a grid layout:

<div class="grid-cols:4 gap:md">    <div>1</div>    <div>2</div>    ...</div>

Namespace for spacing

The spacing variable namespace is shared across related rules:

margin-left, margin-right, margin-top, margin-bottom, margin-x, margin-y, margin, margin-inline-start, margin-inline-end, margin-inline, padding-left, padding-right, padding-top, padding-bottom, padding-x, padding-y, padding, padding-inline-start, padding-inline-end, padding-inline, text-underline-offset, top, bottom, left, right, inset, transform, translate(), translateX(), translateY(), translateZ(), translate3d(), border-spacing, stroke-dashoffset, x, y, cx, cy, column-gap, row-gap, gap, outline-offset, scroll-margin-left, scroll-margin-right, scroll-margin-top, scroll-margin-bottom, scroll-margin-x, scroll-margin-y, scroll-margin, scroll-padding-left, scroll-padding-right, scroll-padding-top, scroll-padding-bottom, scroll-padding-x, scroll-padding-y, scroll-padding, shape-margin

It allows you to declare spacing without spacing- prefix, making it easier to write with spacing-related rules.

export default {    variables: {        spacing: {            sm: 12,             md: 16,             lg: 24,         }    }}

Apply the custom spacing tokens in your markup:

<div class="mt:md p:sm gap:lg">…</div>

Using spacing multiplier

The spacing system is grounded on a consistent and scalable design token foundation. It uses a base unit of 4 pixels, which acts as the smallest scalable measurement across your interface.

Use the x suffix to indicate a multiplier of the base unit.

<div class="m:1x"></div>       <!--  4px, margin: 0.25rem --><div class="p:2x"></div>       <!--  8px, padding: 0.5rem --><div class="w:8x"></div>       <!-- 32px, width: 2rem --><div class="gap:3x"></div>     <!-- 12px, gap: 0.75rem -->

The x suffix helps differentiate these scale-based tokens from unitless raw values, improving clarity and avoiding conflicts with system-generated class names.

Unitless values

In some cases, pixel-accurate control is necessary. Master CSS allows raw unitless values such as 0, 1, 2, ..., for low-level precision. These bypass the base unit system:

<div class="m:0">0px, margin: 0rem</div><div class="p:1">1px, padding: 0.0625rem</div><div class="w:2">2px, width: 0.125rem</div>

Avoid mixing x-based tokens and unitless values arbitrarily in design systems. Prefer sm x tokens for layout spacing, and unitless values only for micro-adjustments or pixel-grid alignment.

Common mistakes

Do not use numeric keys as tokens

Avoid defining spacing tokens with numeric keys.

export default {    variables: {        spacing: {            1: 4,             2: 8         }    }}

This approach creates ambiguity. These values can be misinterpreted as unitless pixel values, conflicting with the unit-sensing system, which intelligently detects whether a value should be interpreted as pixels, rems, or a variable reference.

Always use descriptive keys for clarity and scalability, such as sm, md, lg, etc.

Summary

Master CSS provides a unified system for defining spacing:

• Use the x multiplier to scale from the base unit.
• Define semantic variables like md for shared meanings across teams.
• Use raw unitless values sparingly and only when precision is necessary.
• Avoid numerical keys to prevent conflicts with the system’s value resolution logic.

By adopting this structured spacing approach, your design will be more consistent, maintainable, and collaborative.