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
- 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
In v4 the default dark variant follows the media query. To use a class selector in CSS-first configuration, define @custom-variant dark (&:where(.dark, .dark *));. The table below describes behavior choices, not v4 JavaScript config keys.
| 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 supported build integration | Benchmark the actual project; no universal speedup | |
| 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.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.