tw-spacing-semantics-plugin weekly downloads statistics

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

Setup

In your Tailwind v4 CSS entry file:

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

Customization

By changing --spacing

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

Individual token overrides

Pin a specific token to an exact value.

Add new tokens

If you need more tokens you can add them.

Responsive variants

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

License

MIT

Description from the npm listing.