edpachecojr/tailwind-patterns

Tailwind CSS Patterns (v4 - 2025)

Modern utility-first CSS with CSS-native configuration.

---

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