tailwind-patterns

Tailwind Patterns — A Modern Guide for Tailwind CSS v4

Skill Overview

Tailwind Patterns is a set of modern layout and design pattern reference guides based on Tailwind CSS v4. It helps developers master the latest features such as CSS-first configuration, container queries, and the OKLCH color system, enabling them to quickly build responsive, maintainable user interfaces.

Use Cases

1. Starting a New Project and Choosing Technology

When you begin a new web project, Tailwind Patterns provides a complete v4 architecture reference, including CSS-first configuration, the performance advantages of the Oxide engine, and mobile-first responsive design principles. Whether for personal projects or enterprise applications, you can directly use these proven patterns.

2. Upgrading from Tailwind v3 to v4

If you’re using Tailwind v3 and plan to upgrade, this guide details the differences between v3 and v4: migrating from JavaScript configuration files to the CSS @theme directive, PostCSS plugins being replaced by the Oxide engine, and native support for container queries. It clearly explains the habits and best practices that need to change during the upgrade.

3. Building a Reusable Component Library

When you need to build a component library for a team or an open-source community, Tailwind Patterns provides strategies for extracting components, a design token architecture, and semantic naming conventions. From Flexbox and Grid layout patterns to the color and typography system, all patterns are designed with reusability and maintainability in mind.

Core Features

1. CSS-First Theme Configuration

Tailwind v4 completely changes the way configuration is done. Instead of relying on tailwind.config.js, it uses the native CSS @theme directive directly inside style files to define the theme. This means all design tokens (colors, spacing, fonts, etc.) are automatically exposed as CSS variables that can be accessed dynamically at runtime. Configuration supports either extending default values or completely overriding them, and it recommends using semantic names (e.g., --color-primary instead of --blue-500).

2. Native Container Query Support

v4 includes container query capabilities, allowing components to adjust responsively based on the size of their parent container rather than the viewport. By defining containers with @container, child elements use prefixes such as @sm:, @md:, and @lg: to respond to container width changes. This makes components truly independent of the page layout, so they render correctly in any context.

3. References for Modern Layout Patterns

Covers common layout patterns for Flexbox and Grid, including centering, vertical stacking, horizontal layouts, adaptive grids, and Bento-style asymmetric layouts. Each pattern provides specific class combinations and usage recommendations to help developers quickly implement typical layout needs.

Frequently Asked Questions

What are the main differences between Tailwind CSS v4 and v3?

The most significant change in v4 is adopting a CSS-first configuration approach, no longer using JavaScript configuration files. The build engine switches from PostCSS plugins to the Rust-based Oxide engine, improving compile speed by about 10x. Container queries become a native feature; CSS nesting works without requiring additional PostCSS plugins, and all design tokens are automatically exposed as CSS variables. At the same time, v4 no longer recommends overusing @apply, and instead favors extracting components.

How do I upgrade from Tailwind v3 to v4?

The main work is to migrate the configuration from tailwind.config.js into the CSS @theme directive. Check and replace deprecated plugins and features (most have been superseded by native CSS features). Remove or reduce the use of @apply and switch to component extraction. The container query syntax changes from @variants to native @container. It’s recommended to test in a non-production environment first to ensure compatibility with the build pipeline and dependency packages.

How do Tailwind container queries work?

First, add an @container class on the parent element to define the container. Then, on child elements, use prefixes like @sm:, @md:, and @lg: to respond to container width changes. For example: parent .card { @container }, children @sm:text-base @md:text-lg. This creates truly independent responsive components without relying on the overall page layout. For containers that need to be isolated, you can use named containers such as @container/card.

How do I configure dark mode in Tailwind CSS?

v4 supports three dark mode strategies: the class mode manually controls dark mode by toggling the .dark class, suitable for apps that need theme-switching buttons; the media mode follows system preferences, suitable for cases where users don’t control it; and the selector mode allows custom selectors to implement complex theme logic. A common approach is to provide dark variants for each element, such as bg-white dark:bg-zinc-900 and text-zinc-900 dark:text-zinc-100.

What are some tips for optimizing Tailwind performance?

In v4, the Oxide engine enables JIT mode by default and automatically removes unused styles. Avoid generating class names dynamically using template strings, since that prevents effectively clearing unused styles. Cache build artifacts in your CI/CD pipeline to speed up builds. For large projects, use component extraction appropriately to avoid long repeated class lists, and prefer predefined values from your design system over arbitrary values.

Is Tailwind CSS suitable for large projects?

Absolutely. v4’s CSS-first configuration makes theme management clearer; container queries allow components to be truly independent and reusable; and the Oxide engine ensures fast builds even for large projects. The design token architecture supports consistent maintenance across large design systems. The key is to follow best practices: extract components reasonably, use semantic tokens, avoid overusing arbitrary values, and establish team conventions.

How do I customize a Tailwind theme?

Use the CSS @theme directive in your style files to define custom values. You can extend default values or completely override a category. It’s recommended to use semantic naming (e.g., --color-primary, --spacing-content) instead of visual-based naming (e.g., --blue-500), as semantic names make future theme switching and design system maintenance easier. All custom values automatically become CSS variables, which you can access and modify at runtime.

How do you use OKLCH colors in Tailwind CSS?

OKLCH is a perceptually uniform color space, making it better suited for design work than HSL. In v4, you can directly define colors using the oklch(L C H) syntax—for example, --color-primary: oklch(0.7 0.15 250). The three parameters represent lightness (0–1), chroma (0–0.4), and hue (0–360). The advantage of OKLCH is that it makes it easier to generate coordinated color schemes while maintaining visual consistency, which is especially suitable for building a design token system.