---

name: tailwind-patterns description: "Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture." risk: unknown source: community date_added: "2026-02-27"

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 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 | |-------|------|-----