Spacing

Nim UI uses a harmonious spacing scale based on a 4px base unit. This scale provides consistent spacing for padding, margins, gaps, and layout dimensions.

The kit ships no spacing tokens of its own. Spacing comes from Tailwind's own scale, which derives every step from a single --spacing base of 0.25rem: p-4 compiles to calc(var(--spacing) * 4). The names below are a shared vocabulary for talking about that scale — they are not CSS custom properties, and there is no var(--spacing-md) to reach for.

Spacing Scale

Each step roughly doubles in size, creating a natural visual rhythm.

Visual Reference

<div className="p-1" />   {/* xs  — 4px  */}
<div className="p-2" />   {/* sm  — 8px  */}
<div className="p-4" />   {/* md  — 16px */}
<div className="p-6" />   {/* lg  — 24px */}
<div className="p-8" />   {/* xl  — 32px */}
<div className="p-12" />  {/* 2xl — 48px */}
<div className="p-16" />  {/* 3xl — 64px */}

Padding

Use padding utilities to add internal spacing within elements.

<div className="p-1">4px padding</div>
<div className="p-2">8px padding</div>
<div className="p-4">16px padding</div>
<div className="p-6">24px padding</div>
<div className="p-8">32px padding</div>

Margins

Use margin utilities to add external spacing between elements.

// Vertical spacing between elements
<div className="mb-4">First section</div>
<div className="mb-4">Second section</div>

// Horizontal spacing
<div className="mr-2">Left item</div>
<div className="ml-2">Right item</div>

// Directional margin utilities
<div className="mt-8">Top margin only</div>
<div className="mx-4">Horizontal margins</div>
<div className="my-6">Vertical margins</div>

Gap (Flexbox & Grid)

The gap utility is the preferred method for spacing items within flex and grid containers. It applies consistent spacing without adding margin to individual children.

<div className="flex gap-1">  {/* 4px gap */}
  <Item /><Item /><Item />
</div>

<div className="flex gap-4">  {/* 16px gap */}
  <Item /><Item /><Item />
</div>

<div className="flex gap-8">  {/* 32px gap */}
  <Item /><Item /><Item />
</div>

Component Spacing

Nim UI components use the spacing tokens internally. Here is how the scale maps to common component patterns:

Tailwind Spacing Reference

The full Tailwind spacing scale includes additional values beyond the named tokens. Here are the most commonly used values:

p-0    → 0px        m-0    → 0px
p-0.5  → 2px        m-0.5  → 2px
p-1    → 4px  (xs)  m-1    → 4px
p-1.5  → 6px        m-1.5  → 6px
p-2    → 8px  (sm)  m-2    → 8px
p-3    → 12px       m-3    → 12px
p-4    → 16px (md)  m-4    → 16px
p-5    → 20px       m-5    → 20px
p-6    → 24px (lg)  m-6    → 24px
p-8    → 32px (xl)  m-8    → 32px
p-10   → 40px       m-10   → 40px
p-12   → 48px (2xl) m-12   → 48px
p-16   → 64px (3xl) m-16   → 64px

Customizing Spacing

Tailwind derives the whole scale from a single base, so any multiple already works — p-18 compiles to calc(var(--spacing) * 18) without being declared anywhere. Declare a step only to put it off that rhythm:

@theme {
  --spacing-gutter: 1.375rem;  /* 22px — not a multiple of the 4px base */
}

That gives you p-gutter, gap-gutter and the rest of the family. To rescale everything at once, change the base instead:

@theme {
  --spacing: 0.2rem;  /* p-4 becomes 12.8px rather than 16px */
}

Use CSS custom properties for dynamic spacing:

:root {
  --section-padding: 2rem;
}

@media (min-width: 768px) {
  :root {
    --section-padding: 4rem;
  }
}

<section style={{ padding: 'var(--section-padding)' }}>
  Content with responsive padding
</section>

Best Practices

1. Use the spacing scale consistently. Avoid arbitrary pixel values. Stick to the defined tokens so all spacing is harmonious.
2. Prefer gap over margins for layout spacing. The gap property on flex and grid containers produces cleaner markup and avoids issues with collapsing margins.
3. Use spacing tokens from components. When using Nim UI layout components like Stack, Grid, and Flex, use the built-in spacing props rather than adding manual padding or margin.
4. Increase spacing for larger screens. Use responsive Tailwind utilities like md:p-8 lg:p-12 to scale spacing up on wider viewports.
5. Keep vertical rhythm consistent. Use the same spacing value between sibling elements (e.g., all form fields spaced with gap-4).

What's Next?

• Colors - Color palette and design tokens
• Typography - Fonts, sizes, and text styles
• Dark Mode - Implementing dark mode