Skip to main content
This skill covers Tailwind CSS v4 (2025) with CSS-native configuration, Oxide engine, and modern patterns. The architecture has fundamentally changed from v3.

​
What This Skill Provides

The Tailwind CSS Patterns skill provides comprehensive knowledge of Tailwind v4’s modern, CSS-first approach to styling. It covers the architectural shift from JavaScript configuration to CSS-based theming.

​
Core Concepts

CSS-First Configuration

Theme definition using @theme directive instead of JavaScript config files

Oxide Engine

Rust-based compiler providing 10x faster builds with always-on JIT

Container Queries

Native support for container-based responsive design without breakpoints

Modern Color System

OKLCH color space for perceptually uniform color tokens

​
When This Skill Is Loaded

Agents load this skill when:
  • Implementing CSS styling with Tailwind
  • Configuring Tailwind v4 themes
  • Working with responsive design and container queries
  • Setting up design tokens and color systems
  • Optimizing CSS performance
  • Migrating from Tailwind v3 to v4

​
Key Changes from v3 to v4

v3 (Legacy)v4 (Current)
tailwind.config.jsCSS-based @theme directive
PostCSS pluginOxide engine (10x faster)
JIT modeNative, always-on
Plugin systemCSS-native features
@apply directiveStill works, discouraged
Tailwind v4 embraces CSS-first philosophy. The config file is now optional - everything can be defined in CSS using CSS variables.

​
Use Cases

​
CSS-Based Theme Configuration

Define design tokens directly in CSS: 
@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;
}

​
Container Queries (v4 Native)

Respond to parent element width instead of viewport: When to use:
  • Page-level layouts → Viewport breakpoints (md:, lg:)
  • Component-level responsive → Container queries (@md:, @lg:)
  • Reusable components → Container queries (context-independent)

Container Query Pattern

Define container on parent with @container, then use @sm:, @md:, @lg: prefixes on children to respond to parent width instead of viewport.

​
Modern Layout Patterns

Flexbox Patterns:
  • Center both axes: flex items-center justify-center
  • Vertical stack: flex flex-col gap-4
  • Space between: flex justify-between items-center
Grid Patterns:
  • 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]

​
Dark Mode Strategies

MethodBehaviorUse When
class.dark class togglesManual theme switcher
mediaFollows system preferenceNo user control
selectorCustom selector (v4)Complex theming

​
Modern Color System

​
OKLCH vs RGB/HSL

OKLCH

Perceptually uniform, better for design systems

HSL

Intuitive hue/saturation control

RGB

Legacy compatibility

​
Color Token Architecture

Three-Layer System:
  1. Primitive - Raw color values (--blue-500)
  2. Semantic - Purpose-based naming (--color-primary)
  3. Component - Component-specific (--button-bg)

​
Typography System

​
Font Stack Pattern

TypeRecommended
Sans'Inter', 'SF Pro', system-ui, sans-serif
Mono'JetBrains Mono', 'Fira Code', monospace
Display'Outfit', 'Poppins', sans-serif

​
Type Scale

ClassSizeUse
text-xs0.75remLabels, captions
text-sm0.875remSecondary text
text-base1remBody text
text-lg1.125remLead text
text-xl+1.25rem+Headings

​
Animation & Transitions

​
Built-in Animations

  • animate-spin - Continuous rotation (loading spinners)
  • animate-ping - Attention pulse (notifications)
  • animate-pulse - Subtle opacity pulse (loading state)
  • animate-bounce - Bouncing effect (scroll indicators)

​
Transition Patterns

  • 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

Frontend Design

Design principles for color, typography, and layout decisions

Next.js React Expert

Performance optimization for CSS and rendering

Web Design Guidelines

Accessibility and best practices for implementations

​
Which Agents Use This Skill

Frontend Specialist

The Frontend Specialist loads this skill for all styling work with Tailwind CSS. It’s used in conjunction with frontend-design for design decisions and nextjs-react-expert for performance considerations.

​
Component Extraction

​
When to Extract

SignalAction
Same class combo 3+ timesExtract component
Complex state variantsExtract component
Design system elementExtract + document

​
Extraction Methods

React/Vue Component

When dynamic behavior or JS needed

@apply in CSS

For static styles without JS

Design Tokens

For reusable values across components

​
Anti-Patterns to Avoid

Don’t:
  • Use arbitrary values everywhere → Use design system scale
  • Add !important → Fix specificity properly
  • Use inline style= → Use utilities instead
  • Duplicate long class lists → Extract component
  • Mix v3 config with v4 → Migrate fully to CSS-first
  • Use @apply heavily → Prefer components
Do:
  • Use the design system scale
  • Configure theme tokens in CSS
  • Extract reusable patterns
  • Leverage Oxide performance
  • Embrace CSS-native features

​
Performance Principles

Automatic Optimizations

  • Purge unused CSS - Automatic in v4
  • Oxide compiler - Default, 10x faster than v3
  • JIT compilation - Always on, no configuration needed
  • CSS caching - Leverage CI/CD caching for builds
Important: Avoid dynamic class names in template strings - Tailwind cannot detect them at build time. Use complete class names for proper purging.
Remember: Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The JavaScript config file is now optional.

Build docs developers (and LLMs) love

Get started for freeTalk to us