1---2name: tailwind-patterns3description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.4---56# Tailwind CSS Patterns (v4 - 2025)78> Modern utility-first CSS with CSS-native configuration.910---1112## 1. Tailwind v4 Architecture1314### What Changed from v31516| v3 (Legacy) | v4 (Current) |17| -------------------- | ---------------------------- |18| `tailwind.config.js` | CSS-based `@theme` directive |19| PostCSS plugin | Oxide engine (10x faster) |20| JIT mode | Native, always-on |21| Plugin system | CSS-native features |22| `@apply` directive | Still works, discouraged |2324### v4 Core Concepts2526| Concept | Description |27| ------------------ | ------------------------------------ |28| **CSS-first** | Configuration in CSS, not JavaScript |29| **Oxide Engine** | Rust-based compiler, much faster |30| **Native Nesting** | CSS nesting without PostCSS |31| **CSS Variables** | All tokens exposed as `--*` vars |3233---3435## 2. CSS-Based Configuration3637### Theme Definition3839```40@theme {41 /* Colors - use semantic names */42 --color-primary: oklch(0.7 0.15 250);43 --color-surface: oklch(0.98 0 0);44 --color-surface-dark: oklch(0.15 0 0);4546 /* Spacing scale */47 --spacing-xs: 0.25rem;48 --spacing-sm: 0.5rem;49 --spacing-md: 1rem;50 --spacing-lg: 2rem;5152 /* Typography */53 --font-sans: 'Inter', system-ui, sans-serif;54 --font-mono: 'JetBrains Mono', monospace;55}56```5758### When to Extend vs Override5960| Action | Use When |61| ------------------- | ------------------------------------------ |62| **Extend** | Adding new values alongside defaults |63| **Override** | Replacing default scale entirely |64| **Semantic tokens** | Project-specific naming (primary, surface) |6566---6768## 3. Container Queries (v4 Native)6970### Breakpoint vs Container7172| Type | Responds To |73| ---------------------------- | -------------------- |74| **Breakpoint** (`md:`) | Viewport width |75| **Container** (`@container`) | Parent element width |7677### Container Query Usage7879| Pattern | Classes |80| -------------------- | ---------------------------------- |81| Define container | `@container` on parent |82| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |83| Named containers | `@container/card` for specificity |8485### When to Use8687| Scenario | Use |88| -------------------------- | --------------------------------------- |89| Page-level layouts | Viewport breakpoints |90| Component-level responsive | Container queries |91| Reusable components | Container queries (context-independent) |9293---9495## 4. Responsive Design9697### Breakpoint System9899| Prefix | Min Width | Target |100| ------ | --------- | -------------------------- |101| (none) | 0px | Mobile-first base |102| `sm:` | 640px | Large phone / small tablet |103| `md:` | 768px | Tablet |104| `lg:` | 1024px | Laptop |105| `xl:` | 1280px | Desktop |106| `2xl:` | 1536px | Large desktop |107108### Mobile-First Principle1091101. Write mobile styles first (no prefix)1112. Add larger screen overrides with prefixes1123. Example: `w-full md:w-1/2 lg:w-1/3`113114---115116## 5. Dark Mode117118### Configuration Strategies119120| Method | Behavior | Use When |121| ---------- | ------------------------- | --------------------- |122| `class` | `.dark` class toggles | Manual theme switcher |123| `media` | Follows system preference | No user control |124| `selector` | Custom selector (v4) | Complex theming |125126### Dark Mode Pattern127128| Element | Light | Dark |129| ---------- | ----------------- | ---------------------- |130| Background | `bg-white` | `dark:bg-zinc-900` |131| Text | `text-zinc-900` | `dark:text-zinc-100` |132| Borders | `border-zinc-200` | `dark:border-zinc-700` |133134---135136## 6. Modern Layout Patterns137138### Flexbox Patterns139140| Pattern | Classes |141| ------------------ | ----------------------------------- |142| Center (both axes) | `flex items-center justify-center` |143| Vertical stack | `flex flex-col gap-4` |144| Horizontal row | `flex gap-4` |145| Space between | `flex justify-between items-center` |146| Wrap grid | `flex flex-wrap gap-4` |147148### Grid Patterns149150| Pattern | Classes |151| ------------------- | ----------------------------------------------------- |152| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |153| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |154| Sidebar layout | `grid grid-cols-[auto_1fr]` |155156> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.157158---159160## 7. Modern Color System161162### OKLCH vs RGB/HSL163164| Format | Advantage |165| --------- | --------------------------------------- |166| **OKLCH** | Perceptually uniform, better for design |167| **HSL** | Intuitive hue/saturation |168| **RGB** | Legacy compatibility |169170### Color Token Architecture171172| Layer | Example | Purpose |173| ------------- | ----------------- | -------------------- |174| **Primitive** | `--blue-500` | Raw color values |175| **Semantic** | `--color-primary` | Purpose-based naming |176| **Component** | `--button-bg` | Component-specific |177178---179180## 8. Typography System181182### Font Stack Pattern183184| Type | Recommended |185| ------- | ------------------------------------------ |186| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |187| Mono | `'JetBrains Mono', 'Fira Code', monospace` |188| Display | `'Outfit', 'Poppins', sans-serif` |189190### Type Scale191192| Class | Size | Use |193| ----------- | -------- | ---------------- |194| `text-xs` | 0.75rem | Labels, captions |195| `text-sm` | 0.875rem | Secondary text |196| `text-base` | 1rem | Body text |197| `text-lg` | 1.125rem | Lead text |198| `text-xl`+ | 1.25rem+ | Headings |199200---201202## 9. Animation & Transitions203204### Built-in Animations205206| Class | Effect |207| ---------------- | -------------------- |208| `animate-spin` | Continuous rotation |209| `animate-ping` | Attention pulse |210| `animate-pulse` | Subtle opacity pulse |211| `animate-bounce` | Bouncing effect |212213### Transition Patterns214215| Pattern | Classes |216| -------------- | -------------------------------------- |217| All properties | `transition-all duration-200` |218| Specific | `transition-colors duration-150` |219| With easing | `ease-out` or `ease-in-out` |220| Hover effect | `hover:scale-105 transition-transform` |221222---223224## 10. Component Extraction225226### When to Extract227228| Signal | Action |229| ------------------------- | ------------------ |230| Same class combo 3+ times | Extract component |231| Complex state variants | Extract component |232| Design system element | Extract + document |233234### Extraction Methods235236| Method | Use When |237| ----------------------- | -------------------- |238| **React/Vue component** | Dynamic, JS needed |239| **@apply in CSS** | Static, no JS needed |240| **Design tokens** | Reusable values |241242---243244## 11. Anti-Patterns245246| Don't | Do |247| --------------------------- | -------------------------- |248| Arbitrary values everywhere | Use design system scale |249| `!important` | Fix specificity properly |250| Inline `style=` | Use utilities |251| Duplicate long class lists | Extract component |252| Mix v3 config with v4 | Migrate fully to CSS-first |253| Use `@apply` heavily | Prefer components |254255---256257## 12. Performance Principles258259| Principle | Implementation |260| ------------------ | -------------------------- |261| **Purge unused** | Automatic in v4 |262| **Avoid dynamism** | No template string classes |263| **Use Oxide** | Default in v4, 10x faster |264| **Cache builds** | CI/CD caching |265266---267268> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.
odjaramillo