1---2name: tailwind-patterns3description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.4---5
6# Tailwind CSS Patterns (v4)
7
8> Modern utility-first CSS with CSS-native configuration.
9
10---
11
12## 1. Tailwind v4 Architecture
13
14### What Changed from v3
15
16| v3 (Legacy) | v4 (Current) |
17|-------------|--------------|
18| `tailwind.config.js` | CSS-based `@theme` directive |
19| PostCSS plugin | Oxide engine (full builds ~5x, incremental >100x) |
20| JIT mode | Native, always-on |
21| Plugin system | CSS-native features |
22| `@apply` directive | Still works, discouraged |
23
24### v4 Core Concepts
25
26| 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 |
32
33---
34
35## 2. CSS-Based Configuration
36
37### Theme Definition
38
39```
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);
45
46 /* Spacing scale */
47 --spacing-xs: 0.25rem;
48 --spacing-sm: 0.5rem;
49 --spacing-md: 1rem;
50 --spacing-lg: 2rem;
51
52 /* Typography */
53 --font-sans: 'Inter', system-ui, sans-serif;
54 --font-mono: 'JetBrains Mono', monospace;
55}
56```
57
58### When to Extend vs Override
59
60| 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) |
65
66---
67
68## 3. Container Queries (v4 Native)
69
70### Breakpoint vs Container
71
72| Type | Responds To |
73|------|-------------|
74| **Breakpoint** (`md:`) | Viewport width |
75| **Container** (`@container`) | Parent element width |
76
77### Container Query Usage
78
79| Pattern | Classes |
80|---------|---------|
81| Define container | `@container` on parent |
82| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
83| Named containers | `@container/card` for specificity |
84
85### When to Use
86
87| Scenario | Use |
88|----------|-----|
89| Page-level layouts | Viewport breakpoints |
90| Component-level responsive | Container queries |
91| Reusable components | Container queries (context-independent) |
92
93---
94
95## 4. Responsive Design
96
97### Breakpoint System
98
99| 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 |
107
108### Mobile-First Principle
109
1101. Write mobile styles first (no prefix)
1112. Add larger screen overrides with prefixes
1123. Example: `w-full md:w-1/2 lg:w-1/3`
113
114---
115
116## 5. Dark Mode
117
118### Configuration Strategies
119
120| 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 |
125
126### Dark Mode Pattern
127
128| 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` |
133
134---
135
136## 6. Modern Layout Patterns
137
138### Flexbox Patterns
139
140| 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` |
147
148### Grid Patterns
149
150| 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]` |
155
156> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.
157
158---
159
160## 7. Modern Color System
161
162### OKLCH vs RGB/HSL
163
164| Format | Advantage |
165|--------|-----------|
166| **OKLCH** | Perceptually uniform, better for design |
167| **HSL** | Intuitive hue/saturation |
168| **RGB** | Legacy compatibility |
169
170### Color Token Architecture
171
172| Layer | Example | Purpose |
173|-------|---------|---------|
174| **Primitive** | `--blue-500` | Raw color values |
175| **Semantic** | `--color-primary` | Purpose-based naming |
176| **Component** | `--button-bg` | Component-specific |
177
178---
179
180## 8. Typography System
181
182### Font Stack Pattern
183
184| 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` |
189
190### Type Scale
191
192| 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 |
199
200---
201
202## 9. Animation & Transitions
203
204### Built-in Animations
205
206| Class | Effect |
207|-------|--------|
208| `animate-spin` | Continuous rotation |
209| `animate-ping` | Attention pulse |
210| `animate-pulse` | Subtle opacity pulse |
211| `animate-bounce` | Bouncing effect |
212
213### Transition Patterns
214
215| 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` |
221
222---
223
224## 10. Component Extraction
225
226### When to Extract
227
228| Signal | Action |
229|--------|--------|
230| Same class combo 3+ times | Extract component |
231| Complex state variants | Extract component |
232| Design system element | Extract + document |
233
234### Extraction Methods
235
236| Method | Use When |
237|--------|----------|
238| **React/Vue component** | Dynamic, JS needed |
239| **@apply in CSS** | Sparingly — only when a component layer isn't available |
240| **Design tokens** | Reusable values |
241
242---
243
244## 11. Anti-Patterns
245
246| 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 |
254
255---
256
257## 12. Performance Principles
258
259| Principle | Implementation |
260|-----------|----------------|
261| **Purge unused** | Automatic in v4 |
262| **Avoid dynamism** | No template string classes |
263| **Use Oxide** | Default in v4 (full builds ~5x, incremental >100x) |
264| **Cache builds** | CI/CD caching |
265
266---
267
268> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.
vudovn