Tailwind Patterns

# Tailwind CSS Patterns (v4 - 2025)

> Modern utility-first CSS with CSS-native configuration.

When to Use

Use this skill when configuring Tailwind v4, using CSS-first theme and design tokens, or implementing container queries and modern Tailwind patterns.

---

1. Tailwind v4 Architecture

What Changed from v3

| v3 (Legacy) | v4 (Current) |

|-------------|--------------|

| `tailwind.config.js` | CSS-based `@theme` directive |

| PostCSS plugin | Oxide engine (10x faster) |

| JIT mode | Native, always-on |

| Plugin system | CSS-native features |

| `@apply` directive | Still works, discouraged |

v4 Core Concepts

| Concept | Description |

|---------|-------------|

| **CSS-first** | Configuration in CSS, not JavaScript |

| **Oxide Engine** | Rust-based compiler, much faster |

| **Native Nesting** | CSS nesting without PostCSS |

| **CSS Variables** | All tokens exposed as `--*` vars |

---

2. CSS-Based Configuration

Theme Definition

@theme {
  /* Colors - use semantic names */
  --color-primary: oklch(0.7 0.15 250);
  --color-surface: oklch(0.98 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  
  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  
  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
}

When to Extend vs Override

| Action | Use When |

|--------|----------|

| **Extend** | Adding new values alongside defaults |

| **Override** | Replacing default scale entirely |

| **Semantic tokens** | Project-specific naming (primary, surface) |

---

3. Container Queries (v4 Native)

Breakpoint vs Container

| Type | Responds To |

|------|-------------|

| **Breakpoint** (`md:`) | Viewport width |

| **Container** (`@container`) | Parent element width |

Container Query Usage

| Pattern | Classes |

|---------|---------|

| Define container | `@container` on parent |

| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |

| Named containers | `@container/card` for specificity |

When to Use

| Scenario | Use |

|----------|-----|

| Page-level layouts | Viewport breakpoints |

| Component-level responsive | Container queries |

| Reusable components | Container queries (context-independent) |

---

4. Responsive Design

Breakpoint System

| Prefix | Min Width | Target |

|--------|-----------|--------|

| (none) | 0px | Mobile-first base |

| `sm:` | 640px | Large phone / small tablet |

| `md:` | 768px | Tablet |

| `lg:` | 1024px | Laptop |

| `xl:` | 1280px | Desktop |

| `2xl:` | 1536px | Large desktop |

Mobile-First Principle

1. Write mobile styles first (no prefix)

2. Add larger screen overrides with prefixes

3. Example: `w-full md:w-1/2 lg:w-1/3`

---

5. Dark Mode

Configuration Strategies

| Method | Behavior | Use When |

|--------|----------|----------|

| `class` | `.dark` class toggles | Manual theme switcher |

| `media` | Follows system preference | No user control |

| `selector` | Custom selector (v4) | Complex theming |

Dark Mode Pattern

| Element | Light | Dark |

|---------|-------|------|

| Background | `bg-white` | `dark:bg-zinc-900` |

| Text | `text-zinc-900` | `dark:text-zinc-100` |

| Borders | `border-zinc-200` | `dark:border-zinc-700` |

---

6. Modern Layout Patterns

Flexbox Patterns

| Pattern | Classes |

|---------|---------|

| Center (both axes) | `flex items-center justify-center` |

| Vertical stack | `flex flex-col gap-4` |

| Horizontal row | `flex gap-4` |

| Space between | `flex justify-between items-center` |

| Wrap grid | `flex flex-wrap gap-4` |

Grid Patterns

| Pattern | Classes |

|---------|---------|

| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |

| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |

| Sidebar layout | `grid grid-cols-[auto_1fr]` |

> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.

---

7. Modern Color Sy