Spacing

CreateUI ships a set of semantic spacing tokens. You write one class, such as gap-layout-xl, and it resolves to a different value at every breakpoint (48px on mobile, 64px on tablet, 128px on desktop). The responsive curve lives inside the token, so you stop hand-tuning spacing per screen size and the whole product keeps a consistent rhythm.

The problem it solves

Responsive spacing usually means stacking breakpoint variants on every element. It is verbose, easy to get wrong, and impossible to change globally.

<section className="gap-12 p-4 md:gap-16 md:p-8 xl:gap-32 xl:p-16">...</section>

With tokens, the same intent is two classes:

<section className="gap-layout-xl p-layout-md">...</section>

The win is not just shorter class lists:

• One source of truth. The mobile, tablet, and desktop values are defined once per token. Every surface that uses gap-layout-xl scales identically.
• Global changes are one edit. Want page rhythm to feel tighter on tablet? You change the token, not hundreds of md: variants spread across the codebase.
• No drift. Designers and engineers reference the same named scale, so spacing stays on-system instead of becoming a pile of one-off gap-7 values.

The three scales

Spacing is split into three scales by what sits on either side of the gap. Pick the scale that matches the size of the things you are spacing.

Rule of thumb: the bigger the things on either side of the gap, the higher the scale. A gap between two full sections is layout. A gap between two lines of text inside a card is component.

How a token responds

Every token carries three values, one per breakpoint range:

• Mobile: 320 to 767px
• Tablet: 768 to 1279px
• Desktop: 1280px and up

A single utility class emits all three. For example, gap-layout-xl produces:

/* gap-layout-xl resolves to */
gap: 48px; /* mobile  (320-767px)  */
gap: 64px; /* tablet  (768-1279px) */
gap: 128px; /* desktop (1280px+)    */

You never write the breakpoints yourself. The token already knows its full curve.

Token reference

Values below are the resolved pixels at each breakpoint, on the default --spacing base of 4px. Each bar is drawn at its live token width, so it resizes with the viewport exactly as the token does.

Layout

Page-level spacing.

Section

Section-level spacing.

Component

Component-internal spacing.

Using the tokens

The token name plugs into any Tailwind spacing utility. Tailwind v4 generates the full set automatically, so all of these work:

<div className="p-component-md" />        {/* padding */}
<div className="px-layout-sm py-layout-md" /> {/* axis padding */}
<div className="gap-section-lg" />        {/* flex / grid gap */}
<div className="mt-section-md" />         {/* margin */}
<div className="space-y-component-sm" />  {/* child spacing */}

The same applies to m-, mx-, my-, mt-, gap-x-, gap-y-, and the rest of the spacing utilities.

Choosing semantic vs raw spacing

Semantic tokens scale across breakpoints. That is exactly what you want when the design opts into responsive spacing, and exactly what you do not want for a fixed, static gap.

Real-world example

The three scales compose naturally: layout frames the section, section spaces the groups inside it, and component handles the internals of each card.

<section className="gap-layout-md px-layout-sm py-layout-lg flex flex-col items-center">
  <header className="gap-section-sm flex flex-col">
    <h2>Latest posts</h2>
    <p>Updates from the team.</p>
  </header>
 
  <div className="gap-section-md grid">
    <article className="gap-component-lg p-component-xl flex flex-col">
      <h3>Post title</h3>
      <p>Excerpt...</p>
    </article>
  </div>
</section>

Resize the viewport and every gap retunes itself. You did not write a single breakpoint variant.

How it works

You do not need this to use the tokens, but it helps to know the numbers are generated, not hand-written.

Programmatic access

For Storybook, tests, or runtime logic, createui-spacing.ts exports helpers to resolve tokens in JavaScript.

import {
  resolveToken,
  tokenNames,
  tokensByCategory,
  type BreakpointName,
} from "@/lib/createui-spacing"
 
resolveToken("layout-xl", "desktop") // "calc(var(--spacing) * 32)"
resolveToken("layout-xl", "mobile") // "calc(var(--spacing) * 12)"
resolveToken("layout-xl") // defaults to "desktop"
 
tokenNames() // ["layout-xl", "layout-lg", ...]
tokensByCategory() // { layout: [...], section: [...], component: [...] }

BreakpointName is "mobile" | "tablet" | "desktop".

Changing or adding a token

export const TOKENS = {
  "section-2xl": { value: r(8, 12, 16) }, // 32px | 48px | 64px
}

pnpm registry:build

pnpm dlx @create-ui/cli init