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

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