tw-blocks

A semantic spacing system for Tailwind CSS v4 based on two fundamental units:

• Block: Component sizes (buttons, inputs, toolbars) — default 32px (2rem)
• Tab: Padding, margins, gaps — default 4px (0.25rem)

The 4:1 ratio (4 tabs = 1 block) creates harmonious, predictable layouts.

Installation

For AI Coding Assistants (Recommended)

Add the TW-Blocks skill to your AI assistant (Cursor, Windsurf, etc.):

npx skills add vercel-labs/tw-blocks

This enables your AI to use TW-Blocks patterns automatically when building UIs.

Manual Installation

pnpm add tw-blocks

Usage

/* app/globals.css */
@import "tailwindcss";
@import "tw-blocks";

That's it! No JavaScript config file needed.

Generated Utilities

Spacing

All spacing utilities (p-*, m-*, gap-*, w-*, h-*, inset-*, etc.):

Tab scale (17 values):

• tab-0 (0)
• tab-0.5 (2px)
• tab-1 (4px)
• tab-1.5 (6px)
• tab-2 (8px)
• tab-2.5 (10px)
• tab-3 (12px)
• tab-4 (16px)
• tab-5 (20px)
• tab-6 (24px)
• tab-8 (32px)
• tab-10 (40px)
• tab-12 (48px)
• tab-16 (64px)
• tab-20 (80px)
• tab-24 (96px)
• tab-32 (128px)

Block scale (14 values):

• block-0 (0)
• block-0.5 (16px)
• block-1 (32px)
• block-1.5 (48px)
• block-2 (64px)
• block-2.5 (80px)
• block-3 (96px)
• block-4 (128px)
• block-5 (160px)
• block-6 (192px)
• block-8 (256px)
• block-10 (320px)
• block-12 (384px)
• block-16 (512px)

Border Radius

<div class="rounded-tab-2">Small radius (8px)</div>
<div class="rounded-block-0.5">Large radius (16px)</div>

Examples

<!-- Button with tab padding, block height -->
<button class="h-block-1 px-tab-4 rounded-tab-2">
  Click me
</button>

<!-- Card with block-based sizing -->
<div class="p-tab-4 rounded-tab-3 w-block-10">
  <h2 class="mb-tab-2">Title</h2>
  <p>Content</p>
</div>

<!-- Toolbar with consistent spacing -->
<div class="h-block-1.5 px-tab-3 gap-tab-2 flex items-center">
  <button class="size-block-1">Icon</button>
  <span class="px-tab-2">Label</span>
</div>

Customization

Override the base units in your CSS:

@import "tailwindcss";
@import "tw-blocks";

/* Custom base sizes */
:root {
  --spacing-block: 2.5rem;  /* 40px blocks */
  --spacing-tab: 0.5rem;    /* 8px tabs */
}

All utilities automatically recalculate based on your custom values!

Philosophy

The block/tab system is inspired by professional design tools where:

1. Blocks define structural dimensions (like a toolbar height or panel width)
2. Tabs provide the fine-grained adjustments within those structures

This creates a natural hierarchy:

• Use block-* for component sizes
• Use tab-* for internal spacing

Migration from v3

If you're migrating from the v3 JavaScript plugin:

1. Remove tailwind.config.js (or the plugin from it)
2. Update your CSS:

   /* Old (v3) */
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
      
   /* New (v4) */
   @import "tailwindcss";
   @import "tw-blocks";

All existing classes (p-tab-2, h-block-1, etc.) work exactly the same!

License

MIT