YourAI.tools
Vercel Labs logo

Skill

tw-blocks

build UIs with Tailwind CSS spacing

Published by Vercel Labs Updated Jul 17
Covers Tailwind CSS UI Components Frontend Design

Description

Semantic spacing system for Tailwind CSS v4 using block (32px) and tab (4px) units. Use when building UIs with consistent spacing, dashboards, admin panels, design tools, or any interface requiring a harmonious spacing system. Provides patterns for buttons, inputs, cards, toolbars, panels, and layouts.

SKILL.md

TW-Blocks Design System

Core Principles

TW-Blocks provides semantic spacing using two fundamental units:

  • Block (2rem / 32px): Component sizes - buttons, inputs, headers, toolbars, avatars
  • Tab (0.25rem / 4px): Padding, margins, gaps - spacing between and within elements

The 4:1 Ratio: 4 tabs = 1 block. This creates predictable, harmonious layouts.

1 block = 32px = 4 tabs
████████  ████████  ████████  ████████
 tab-1     tab-2     tab-3     tab-4
  4px       8px       12px      16px

Installation & Setup

pnpm add tw-blocks

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

Class Reference

Tab Spacing Scale (17 values)

Class suffixValuePixels
tab-000px
tab-0.50.5 × tab2px
tab-11 × tab4px
tab-1.51.5 × tab6px
tab-22 × tab8px
tab-2.52.5 × tab10px
tab-33 × tab12px
tab-44 × tab16px
tab-55 × tab20px
tab-66 × tab24px
tab-88 × tab32px
tab-1010 × tab40px
tab-1212 × tab48px
tab-1616 × tab64px
tab-2020 × tab80px
tab-2424 × tab96px
tab-3232 × tab128px

Block Spacing Scale (14 values)

Class suffixValuePixels
block-000px
block-0.50.5 × block16px
block-11 × block32px
block-1.51.5 × block48px
block-22 × block64px
block-2.52.5 × block80px
block-33 × block96px
block-44 × block128px
block-55 × block160px
block-66 × block192px
block-88 × block256px
block-1010 × block320px
block-1212 × block384px
block-1616 × block512px

Border Radius Values

ClassValuePixels
rounded-tab-11 × tab4px
rounded-tab-22 × tab8px
rounded-tab-33 × tab12px
rounded-tab-44 × tab16px
rounded-block-0.50.5 × block16px
rounded-block-11 × block32px (fully round)

Supported Tailwind Utilities

All standard Tailwind spacing utilities work with block/tab:

  • Padding: p-tab-4, px-tab-3, py-tab-2, p-block-1
  • Margin: m-tab-4, mx-tab-3, my-tab-2, m-block-1
  • Gap: gap-tab-4, gap-x-tab-3, gap-block-1
  • Width/Height: w-block-2, h-block-1, size-block-1
  • Inset: top-tab-2, left-tab-4, inset-block-1
  • Space: space-x-tab-2, space-y-tab-4

Quick Patterns

Button

<button class="h-block-1 px-tab-4 rounded-tab-2 bg-blue-500 text-white">Click me</button>

Small Button

<button class="h-tab-6 px-tab-3 rounded-tab-1.5 text-sm">Small</button>

Icon Button

<button class="size-block-1 flex items-center justify-center rounded-tab-2">
  <svg class="w-tab-4 h-tab-4" />
</button>

Input Field

<input type="text" class="h-block-1 px-tab-3 rounded-tab-2 border border-gray-300" />

Card

<div class="p-tab-4 rounded-block-0.5 bg-white shadow-sm border">
  <h3 class="text-lg font-semibold">Title</h3>
  <p class="mt-tab-2 text-gray-600">Description</p>
</div>

Best Practices

Component Height Guidelines

ComponentHeightClass
Standard button32pxh-block-1
Small button24pxh-tab-6
Large button48pxh-block-1.5
Input field32pxh-block-1
Small input24pxh-tab-6
Toolbar48pxh-block-1.5
Header (main)64pxh-block-2
Status bar24pxh-tab-6
Avatar (small)32pxsize-block-1
Avatar (large)48pxsize-block-1.5

Horizontal Padding Standards

ContainerPadding
Page contentpx-tab-6
Cardp-tab-4
Buttonpx-tab-4
Inputpx-tab-3
Panel sectionp-tab-2 or p-tab-3
Headerpx-tab-4

Border Radius Guidelines

ElementRadius
Buttonrounded-tab-2 (8px)
Cardrounded-block-0.5 (16px)
Inputrounded-tab-2 (8px)
Small badgerounded-tab-1 (4px)
Avatarrounded-full

UI Density Patterns

Compact UI (Code editors, IDEs, tools):

  • Toolbar: h-block-1 (32px)
  • List items: h-tab-5 or h-tab-6 (20-24px)
  • Padding: p-tab-2, px-tab-3
  • Gaps: gap-tab-1, gap-tab-2

Normal UI (Dashboards, apps):

  • Header: h-block-2 (64px)
  • Buttons: h-block-1 (32px)
  • Cards: p-tab-4 or p-tab-6
  • Gaps: gap-tab-4, gap-tab-6

Spacious UI (Marketing, content):

  • Headers: h-block-2.5 or h-block-3
  • Cards: p-tab-8, p-tab-12
  • Gaps: gap-tab-8, gap-tab-12

Combining with Standard Tailwind

TW-Blocks focuses on spacing and sizing. Use standard Tailwind for everything else:

✅ Use Standard Tailwind For:

  • Colors: bg-blue-500, text-gray-700, border-gray-200
  • Typography: text-sm, font-bold
  • Flexbox/Grid: flex, grid, items-center
  • Borders: border, border-t
  • Effects: shadow-md, hover:bg-gray-100

❌ Avoid Standard Tailwind For:

  • Spacing: Use p-tab-4 not p-4
  • Component sizing: Use h-block-1 not h-8
  • Block-aligned radius: Use rounded-tab-2 not rounded-md

Detailed Patterns

For complete component patterns, see references/patterns.md:

  • Dashboard layouts (sidebar, stat cards)
  • Toolbars & headers (dashboard, design tool, status bar)
  • Panels & sidebars (tool palette, property panels, layers)
  • Forms & inputs (buttons, inputs, cards)
  • Tables & lists (dense lists, email lists)
  • Status indicators (badges, progress bars, selected states)
  • Chat & messages (chat bubbles, message lists)
  • Charts & data viz (containers, recommended heights)
  • Timeline & animation panels
  • Code editor interface (full IDE layout)

Read patterns.md when you need specific implementation examples.

Common Mistakes to Avoid

❌ Don't mix spacing systems

<!-- Bad -->
<div class="p-4 mt-tab-2 mb-8">

<!-- Good -->
<div class="p-tab-4 mt-tab-2 mb-tab-8">

❌ Don't use blocks for small padding

<!-- Bad -->
<button class="p-block-1">

<!-- Good -->
<button class="px-tab-4 py-tab-2">

❌ Don't use tabs for component sizing

<!-- Bad -->
<button class="h-tab-8">

<!-- Good -->
<button class="h-block-1">

✅ Do use fractional values

<div class="p-tab-1.5">  <!-- 6px -->
<div class="h-block-1.5"> <!-- 48px -->
<div class="gap-tab-2.5"> <!-- 10px -->

Debugging Tips

Inspect CSS Variables

getComputedStyle(document.documentElement).getPropertyValue('--spacing-block') // "2rem"
getComputedStyle(document.documentElement).getPropertyValue('--spacing-tab')   // "0.25rem"

Test with Visible Borders

<div class="p-tab-4 border-2 border-red-500">
  <div class="h-block-1 border-2 border-blue-500">Button height</div>
</div>

Quick Reference

┌─────────────────────────────────────────────────────────┐
│ BLOCKS (Component Sizing)                                │
│ block-1 = 32px | block-1.5 = 48px | block-2 = 64px      │
├─────────────────────────────────────────────────────────┤
│ TABS (Spacing/Padding)                                   │
│ tab-1 = 4px | tab-2 = 8px | tab-3 = 12px | tab-4 = 16px │
├─────────────────────────────────────────────────────────┤
│ HEIGHT: Button h-block-1 | Header h-block-2 | Toolbar h-block-1.5 │
├─────────────────────────────────────────────────────────┤
│ PADDING: Button px-tab-4 | Card p-tab-4 | Input px-tab-3 │
├─────────────────────────────────────────────────────────┤
│ RADIUS: Button rounded-tab-2 | Card rounded-block-0.5    │
└─────────────────────────────────────────────────────────┘
AboutPrivacy PolicyTerms and Conditions

© 2026 YourAI.tools. Every skill from an identity-verified publisher.

Independent catalog. Not affiliated with, endorsed by, or sponsored by Anthropic or any listed publisher. All trademarks belong to their respective owners.