tw-spacing-semantics-plugin

A production-ready Tailwind CSS v4 plugin that adds a semantic spacing layer — p-md, gap-xl, mx-2xl, top-lg — built on an isolated --space-* custom property system that never touches Tailwind's own spacing scale.

Why this exists

Tailwind's built-in spacing utilities use numeric keys: p-4, gap-8, mt-12. These are structural primitives tied to the raw --spacing unit. They work great for low-level layout work, but design systems benefit from named, semantic tokens: is this the "comfortable" padding or the "tight" padding?

Also, changing --spacing-xl, for example, will modify classes that already have semantic variants such as max-w-xl, forcing you to create your custom spacings with another prefix like max-w-s-xl.

This plugin adds that semantic layer without touching Tailwind's internals. Utilities like max-w-xl, w-4, h-screen, and gap-8 continue working exactly as Tailwind intended.

The default token scale is based on the concepts of Refactoring UI by Adam Wathan & Steve Schoger. Yes, the Tailwind creators!.

Features

• Fully isolated --space-* namespace — zero interference with Tailwind internals
• Generates only p-*, m-*, -m-*, top-*/right-*/bottom-*/left-*, gap-*, space-x-*/space-y-*, their negative variants and logical (ms-*, pe-*, mbs-*, …) utilities
• Two-level customization: global scale factor + individual token override
• Native Tailwind v4 responsive variants (sm:px-xl, md:gap-2xl)
• CSS-first, ESM, npm-publishable
• JIT tree-shakable — only used utilities appear in output
• Zero Tailwind internals mutated

Installation

pnpm add tw-spacing-semantics-plugin

Setup

In your Tailwind v4 CSS entry file:

@import 'tailwindcss';
@import 'tw-spacing-semantics-plugin';

That's it. All semantic utilities are now available.

Default token reference

At Tailwind's default --spacing: 0.25rem:

| Token | Multiplier | Value (rem) | Value (px) | | ------ | ---------- | ----------- | ---------- | | none | — | 0 | 0px | | 3xs | × 0.5 | 0.125rem | 2px | | 2xs | × 1 | 0.25rem | 4px | | xs | × 2 | 0.5rem | 8px | | sm | × 3 | 0.75rem | 12px | | md | × 4 | 1rem | 16px | | lg | × 6 | 1.5rem | 24px | | xl | × 8 | 2rem | 32px | | 2xl | × 12 | 3rem | 48px | | 3xl | × 16 | 4rem | 64px | | 4xl | × 24 | 6rem | 96px | | 5xl | × 32 | 8rem | 128px | | 6xl | × 48 | 12rem | 192px | | 7xl | × 64 | 16rem | 256px | | 8xl | × 96 | 24rem | 384px | | 9xl | × 128 | 32rem | 512px | | 10xl | × 192 | 48rem | 768px | | 11xl | × 256 | 64rem | 1024px |

Generated utilities

Every token is available across spacing axes.

Padding

| Classes generated | | ----------------------------------------------------------------------- | | p-{t} px-{t} py-{t} pt-{t} pr-{t} pb-{t} pl-{t} | | ps-{t} pe-{t} pbs-{t} pbe-{t} (logical) |

Padding does NOT support negative values.

Margin and negative margin

| Classes generated | | ---------------------------------------------------------------------------------------------- | | m-{t} mx-{t} my-{t} mt-{t} mr-{t} mb-{t} ml-{t} ms-{t} me-{t} mbs-{t} mbe-{t} | | -m-{t} -mx-{t} -my-{t} -mt-{t} -mr-{t} -mb-{t} -ml-{t} | | -ms-{t} -me-{t} -mbs-{t} -mbe-{t} (logical) |

Logical margins (ms/me/mbs/mbe) follow the writing direction of the document, so they flip automatically in RTL layouts. Their negative variants are also supported.

Gap

| Classes generated | | --------------------------------- | | gap-{t} gap-x-{t} gap-y-{t} |

Gap does NOT support negative values in CSS.

Space between children

| Classes generated | | ------------------------------------ | | space-x-{t} space-y-{t} | | -space-x-{t} -space-y-{t} |

Applies the semantic token as spacing between sibling elements (margin-based, like Tailwind's native space-x-*/space-y-*). Negative variants collapse the space between siblings.

Inset (positioning)

| Classes generated | | -------------------------------------------------------------- | | inset-{t} inset-x-{t} inset-y-{t} | | -inset-{t} -inset-x-{t} -inset-y-{t} | | top-{t} right-{t} bottom-{t} left-{t} | | -top-{t} -right-{t} -bottom-{t} -left-{t} |

Only the classes you actually used will appear in the final CSS.

Usage

<!-- Semantic padding -->
<article class="p-md">…</article>

<!-- Responsive semantic padding -->
<section class="px-sm sm:px-md lg:px-xl">…</section>

<!-- Semantic gap in a grid -->
<div class="grid grid-cols-3 gap-lg">…</div>

<!-- Responsive gap -->
<div class="flex flex-col gap-sm md:gap-lg">…</div>

<!-- Margin -->
<div class="mt-md mb-lg">…</div>

<!-- Negative margin -->
<div class="-mt-md -mb-lg"></div>

<!-- Horizontal negative margin -->
<div class="-mx-xl"></div>

<!-- Semantic inset positioning -->
<div class="top-md left-lg">…</div>

<!-- Inset shorthand -->
<div class="inset-lg inset-x-md inset-y-sm">…</div>

<!-- Negative inset -->
<div class="-top-sm -right-md -inset-x-xl">…</div>

<!-- Responsive inset -->
<div class="top-sm md:top-lg xl:top-2xl">…</div>

<!-- Mixed layout: Tailwind structural + semantic spacing -->
<div class="max-w-xl mx-auto px-md py-lg">
	<!-- max-w-xl → max-width: var(--container-xl) -->
	<!-- px-md    → padding-inline: var(--space-md) -->
</div>

<!-- Logical padding (flips in RTL) -->
<div class="ps-md pe-lg">…</div>

<!-- Logical margin -->
<div class="ms-auto me-md">…</div>

<!-- Spacing between children -->
<ul class="space-y-md">
	<li>…</li>
	<li>…</li>
</ul>
<div class="flex space-x-lg">
	<button>…</button>
	<button>…</button>
</div>

Customization

By changing --spacing

If you have a custom --spacing theme, the plugin will automatically adapt the utilities to use your custom spacing.

@import 'tailwindcss';
@import 'tw-spacing-semantics-plugin';

@theme {
	--spacing: 4rem;
}

Individual token overrides

Pin a specific token to an exact value.

@theme {
	--space-md: 1.5rem; /* always 24px, regardless of --spacing */
	--space-xl: 2.75rem; /* always 44px, regardless of --spacing */
}

Add new tokens

If you need more tokens you can add them.

@theme {
	--space-4xs: calc(var(--spacing) * 0.25)
	--space-12xl: calc(var(--spacing) * 512)
}
```

## Responsive variants

All semantic utilities participate in Tailwind v4's full variant system with no extra configuration:

```html
<!-- Responsive -->
<div class="py-sm md:py-lg xl:py-2xl">…</div>
<div class="gap-md lg:gap-xl">…</div>

<!-- State-based -->
<button class="px-md hover:px-lg transition-all">…</button>

<!-- Combined -->
<section class="p-sm sm:p-md lg:p-xl dark:p-lg">…</section>
```

---

## License

MIT