Provides Tailwind CSS v4 patterns for CSS-first configuration, container queries, design tokens, and utility-first component architecture. Use when working with Tailwind CSS files or when the user mentions Tailwind, Tailwind v4, or utility-first CSS.
日本語に翻訳 name: tailwind-patterns
type: reference
description: "Provides Tailwind CSS v4 patterns for CSS-first configuration, container queries, design tokens, and utility-first component architecture. Use when working with Tailwind CSS files or when the user mentions Tailwind, Tailwind v4, or utility-first CSS."
paths: ["/*.tsx", " /.jsx", "**/ .css", "**/tailwind.config.*"]
when_to_use: "When writing Tailwind CSS v4, configuring design tokens, implementing container queries, or building responsive layouts"
allowed-tools: Read, Glob, Grep
user-invocable: true
effort: 3
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.jsCSS-based @theme directive PostCSS plugin Oxide engine (10x faster) JIT mode Native, always-on Plugin system CSS-native features @apply directiveStill 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 parentContainer breakpoint @sm:, @md:, @lg: on childrenNamed 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 togglesManual theme switcher mediaFollows system preference No user control selectorCustom selector (v4) Complex theming
Dark Mode Pattern
Element Light Dark Background bg-whitedark:bg-zinc-900Text text-zinc-900dark:text-zinc-100Borders border-zinc-200dark:border-zinc-700
6. Modern Layout Patterns
Flexbox Patterns
Pattern Classes Center (both axes) flex items-center justify-centerVertical stack flex flex-col gap-4Horizontal row flex gap-4Space between flex justify-between items-centerWrap 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 spansSidebar 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-500Raw color values Semantic --color-primaryPurpose-based naming Component --button-bgComponent-specific
8. Typography System
Font Stack Pattern
Type Recommended Sans 'Inter', 'SF Pro', system-ui, sans-serifMono 'JetBrains Mono', 'Fira Code', monospaceDisplay 'Outfit', 'Poppins', sans-serif
Type Scale
Class Size Use text-xs0.75rem Labels, captions text-sm0.875rem Secondary text text-base1rem Body text text-lg1.125rem Lead text text-xl+1.25rem+ Headings
9. Animation & Transitions
Built-in Animations
Class Effect animate-spinContinuous rotation animate-pingAttention pulse animate-pulseSubtle opacity pulse animate-bounceBouncing effect
Transition Patterns
Pattern Classes All properties transition-all duration-200Specific transition-colors duration-150With easing ease-out or ease-in-outHover 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 !importantFix 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.