Spacing

Create UI 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. The responsive curve lives inside the token, so you stop hand-tuning spacing per screen size and the whole product keeps a consistent rhythm.

There are 18 of them across three scales. Thirteen scale with the viewport and five hold one value on purpose.

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. The bigger the things you are separating, the higher the scale.

Token reference

Each scale is drawn against its own largest step, so the steps within a scale compare directly and the card header says what a full track is worth. The head of each bar is the mobile value and each step after it is what the token gains as the screen grows, so the whole curve reads at a glance. Clicking a token name copies its gap-* class.

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.

Reading a token at runtime

The tokens reach your project as CSS custom properties, so Storybook, tests, and runtime logic read them off the document rather than importing a module.

const layoutXl = getComputedStyle(document.documentElement)
  .getPropertyValue("--spacing-layout-xl")
  .trim()

The value you get back is the one for the current viewport, because the two max-width blocks have already resolved.

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.

Changing or adding a token

:root {
  --spacing-section-2xl: calc(var(--spacing) * 16); /* 64px */
}
@media (max-width: 1279px) {
  :root {
    --spacing-section-2xl: calc(var(--spacing) * 12);
  } /* 48px */
}

@theme inline {
  --spacing-section-2xl: var(--spacing-section-2xl);
}

pnpm dlx @create-ui/cli init