Tailwind Patterns Agent Skill

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

• Write mobile styles first (no prefix)
• Add larger screen overrides with prefixes
• 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 component |

| Complex state variants | Extract component |

| Design system element | Extract + document |

Extraction Methods

| Method | Use When |

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

| React/Vue component | Dynamic, JS needed |

| @apply in CSS | Static, no JS needed |

| Design tokens | Reusable values |

11. Anti-Patterns

| Don't | Do |

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

| Arbitrary values everywhere | Use design system scale |

| !important | Fix specificity properly |

| Inline style= | Use utilities |

| Duplicate long class lists | Extract component |

| Mix v3 config with v4 | Migrate fully to CSS-first |

| Use @apply heavily | Prefer components |

12. Performance Principles

| Principle | Implementation |

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

| Purge unused | Automatic in v4 |

| Avoid dynamism | No template string classes |

| Use Oxide | Default in v4, 10x faster |

| Cache builds | CI/CD caching |

> Remember: Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.