tw-blocks

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 suffix	Value	Pixels
tab-0	0	0px
tab-0.5	0.5 × tab	2px
tab-1	1 × tab	4px
tab-1.5	1.5 × tab	6px
tab-2	2 × tab	8px
tab-2.5	2.5 × tab	10px
tab-3	3 × tab	12px
tab-4	4 × tab	16px
tab-5	5 × tab	20px
tab-6	6 × tab	24px
tab-8	8 × tab	32px
tab-10	10 × tab	40px
tab-12	12 × tab	48px
tab-16	16 × tab	64px
tab-20	20 × tab	80px
tab-24	24 × tab	96px
tab-32	32 × tab	128px

Block Spacing Scale (14 values)

Class suffix	Value	Pixels
block-0	0	0px
block-0.5	0.5 × block	16px
block-1	1 × block	32px
block-1.5	1.5 × block	48px
block-2	2 × block	64px
block-2.5	2.5 × block	80px
block-3	3 × block	96px
block-4	4 × block	128px
block-5	5 × block	160px
block-6	6 × block	192px
block-8	8 × block	256px
block-10	10 × block	320px
block-12	12 × block	384px
block-16	16 × block	512px

Border Radius Values

Class	Value	Pixels
rounded-tab-1	1 × tab	4px
rounded-tab-2	2 × tab	8px
rounded-tab-3	3 × tab	12px
rounded-tab-4	4 × tab	16px
rounded-block-0.5	0.5 × block	16px
rounded-block-1	1 × block	32px (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

Component	Height	Class
Standard button	32px	h-block-1
Small button	24px	h-tab-6
Large button	48px	h-block-1.5
Input field	32px	h-block-1
Small input	24px	h-tab-6
Toolbar	48px	h-block-1.5
Header (main)	64px	h-block-2
Status bar	24px	h-tab-6
Avatar (small)	32px	size-block-1
Avatar (large)	48px	size-block-1.5

Horizontal Padding Standards

Container	Padding
Page content	px-tab-6
Card	p-tab-4
Button	px-tab-4
Input	px-tab-3
Panel section	p-tab-2 or p-tab-3
Header	px-tab-4

Border Radius Guidelines

Element	Radius
Button	rounded-tab-2 (8px)
Card	rounded-block-0.5 (16px)
Input	rounded-tab-2 (8px)
Small badge	rounded-tab-1 (4px)
Avatar	rounded-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    │
└─────────────────────────────────────────────────────────┘