Tailwind CSS Patterns (v4 - 2025)
Modern utility-first CSS with CSS-native configuration.
- 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
- 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)
- 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)
- 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
- 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
- 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.
- 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
- 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
- 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
- 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
- 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
- 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.