Spacing

Use spacing tokens, base-unit multipliers, and precise low-level values for layout rhythm.

Overview

Spacing controls the rhythm inside components, between related elements, and across page sections. Master CSS maps the default spacing scale to spacing variables, so padding, margin, gap, and inset can share the same design language.

Use the scale by relationship:

• 4xs to 2xs for micro spacing between icons, tags, compact controls, and inline text.
• xs to sm for form fields, list rows, toolbar controls, and tight component groups.
• md as the default component rhythm.
• lg to xl for card padding, grouped content, and larger component separation.
• 2xl to 5xl for layout gutters, section spacing, and large editorial rhythm.

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

@layer theme {    :root {        --spacing-md: 1rem    }}@layer utilities {    .gap\:md {        gap: var(--spacing-md)    }    .p\:md {        padding: var(--spacing-md)    }    .grid-cols\:4 {        display: grid;        grid-template-columns: repeat(4, minmax(0, 1fr))    }}

Namespace for spacing

The spacing variable namespace is shared across padding, margin, gap, inset, scroll spacing, and similar layout rules.

This lets spacing-related utilities use md, lg, or project token names without the spacing- prefix.

@theme {    --spacing-sm: 0.75rem;    --spacing-md: 1rem;    --spacing-lg: 1.5rem;    --spacing-wide: 6rem;}

Apply the custom spacing tokens in your markup:

<section class="py:wide">    <div class="mt:md p:sm gap:lg">...</div></section>

Using spacing multiplier

The x suffix multiplies the base unit theme setting, which defaults to 4 pixels. Use it for measured geometry that should stay aligned with the spacing grid but does not need a named token.

For example, 1x is 0.25rem, 2x is 0.5rem, 3x is 0.75rem, and 8x is 2rem.

<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 -->

For product surfaces, prefer named spacing tokens such as sm, md, and lg. Use x values for measured local geometry, such as icon size, avatar size, skeleton blocks, or a component-specific fixed width.

Exact pixel values

Use 0 for resets, explicit 1px for hairlines, and other px units when a value needs exact pixel geometry. Bare numbers are emitted as written, so p:1 becomes padding: 1 and is not a valid CSS length.

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

Avoid mixing named spacing tokens, x multipliers, and exact pixel values arbitrarily. Prefer named tokens for layout rhythm, x values for measured local geometry, and px values only for hairlines or exact pixel adjustments.

Common mistakes

Do not use numeric keys as tokens

Avoid defining spacing tokens with numeric keys.

@theme {    --spacing-1: 0.25rem;     --spacing-2: 0.5rem; }

Numeric keys are easy to confuse with low-level CSS values. Prefer semantic token keys like sm or card, then use p:1px for a 1px value or p:1x for the default 4px base unit.

Use descriptive scale or role keys.

@theme {    --spacing-sm: 0.75rem;    --spacing-compact: 1.25rem;    --spacing-relaxed: 6rem;}

Summary

Master CSS provides a unified system for defining spacing:

• Use named spacing tokens for shared rhythm.
• Use x multipliers for measured local geometry.
• Use 0, 1px, or explicit pixel units for resets and exact pixel adjustments.
• Avoid numeric token keys so markup stays clear.