Spacing

Use spacing tokens, native CSS lengths, 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,  :host {    --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="gap-lg mt-md p-sm">...</div></section>

Using explicit lengths

Use native CSS units for local geometry that does not need a named token. rem lengths follow the browser’s root font size; px lengths retain their CSS pixel value.

<div class="m:0.25rem"></div><div class="p:0.5rem"></div><div class="w:2rem"></div><div class="gap:0.75rem"></div>

For product surfaces, prefer shared names such as p-sm, gap-md, and m-lg. Master CSS does not generate a numeric spacing scale or convert length multipliers.

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">margin: 0</div><div class="p:1px">1px, padding: 1px</div><div class="w:2px">width: 2px</div>

Avoid mixing named spacing tokens, explicit native lengths, and exact pixel values arbitrarily. Prefer named tokens for layout rhythm, explicit lengths 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:0.25rem for a root-relative length.

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 explicit native lengths 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.