/tailwind-patterns

name: tailwind-patterns
description: "Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture. Use when building with Tailwind v4 or migrating from v3."
domain: design
supports: [claude-code, cursor, codex, generic]
version: 0.1.0

Tailwind CSS Patterns (v4 - 2025)

Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture. Use when building with Tailwind CSS v4, migrating from v3, configuring design tokens in CSS, implementing responsive layouts, or applying utility-first 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 System

OKLCH vs RGB/HSL

| Format | Advantage | |--------|-----------| | **OKLCH** | Perceptually uniform, better for design | | **HSL** | Intuitive hue/saturation | | **RGB** | Legacy compatibility |

Color Token Architecture

| Layer | Example | Purpose | |-------|---------|---------| | **Primitive** | `--blue-500` | Raw color values | | **Semantic** | `--color-primary` | Purpose-based naming | | **Component** | `--button-bg` | Component-specific |

---

8. Typography System

Font Stack Pattern

| Type | Recommended | |------|-------------| | Sans | `'Inter', 'SF Pro', system-ui, sans-serif` | | Mono | `'JetBrains Mono', 'Fira Code', monospace` | | Display | `'Outfit', 'Poppins', sans-serif` |

Type Scale

| Class | Size | Use | |-------|------|-----| | `text-xs` | 0.75rem | Labels, captions | | `text-sm` | 0.875rem | Secondary text | | `text-base` | 1rem | Body text | | `text-lg` | 1.125rem | Lead text | | `text-xl`+ | 1.25rem+ | Headings |

---

9. Animation & Transitions

Built-in Animations

| Class | Effect | |-------|--------| | `animate-spin` | Continuous rotation | | `animate-ping` | Attention pulse | | `animate-pulse` | Subtle opacity pulse | | `animate-bounce` | Bouncing effect |

Transition Patterns

| Pattern | Classes | |---------|---------| | All properties | `transition-all duration-200` | | Specific | `transition-colors duration-150` | | With easing | `ease-out` or `ease-in-out` | | Hover effect | `hover:scale-105 transition-transform` |

---

10. Component Extraction

When to Extract

| Signal | Action | |--------|--------| | Same class combo 3+ times | Extract co