Tailwind Patterns

1---
2name: tailwind-patterns
3description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.
4allowed-tools: Read, Write, Edit, Glob, Grep
5---
6 
7# Tailwind CSS Patterns (v4 - 2025)
8 
9> Modern utility-first CSS with CSS-native configuration.
10 
11---
12 
13## 1. Tailwind v4 Architecture
14 
15### What Changed from v3
16 
17| v3 (Legacy) | v4 (Current) |
18|-------------|--------------|
19| `tailwind.config.js` | CSS-based `@theme` directive |
20| PostCSS plugin | Oxide engine (10x faster) |
21| JIT mode | Native, always-on |
22| Plugin system | CSS-native features |
23| `@apply` directive | Still works, discouraged |
24 
25### v4 Core Concepts
26 
27| Concept | Description |
28|---------|-------------|
29| **CSS-first** | Configuration in CSS, not JavaScript |
30| **Oxide Engine** | Rust-based compiler, much faster |
31| **Native Nesting** | CSS nesting without PostCSS |
32| **CSS Variables** | All tokens exposed as `--*` vars |
33 
34---
35 
36## 2. CSS-Based Configuration
37 
38### Theme Definition
39 
40```
41@theme {
42  /* Colors - use semantic names */
43  --color-primary: oklch(0.7 0.15 250);
44  --color-surface: oklch(0.98 0 0);
45  --color-surface-dark: oklch(0.15 0 0);
46  
47  /* Spacing scale */
48  --spacing-xs: 0.25rem;
49  --spacing-sm: 0.5rem;
50  --spacing-md: 1rem;
51  --spacing-lg: 2rem;
52  
53  /* Typography */
54  --font-sans: 'Inter', system-ui, sans-serif;
55  --font-mono: 'JetBrains Mono', monospace;
56}
57```
58 
59### When to Extend vs Override
60 
61| Action | Use When |
62|--------|----------|
63| **Extend** | Adding new values alongside defaults |
64| **Override** | Replacing default scale entirely |
65| **Semantic tokens** | Project-specific naming (primary, surface) |
66 
67---
68 
69## 3. Container Queries (v4 Native)
70 
71### Breakpoint vs Container
72 
73| Type | Responds To |
74|------|-------------|
75| **Breakpoint** (`md:`) | Viewport width |
76| **Container** (`@container`) | Parent element width |
77 
78### Container Query Usage
79 
80| Pattern | Classes |
81|---------|---------|
82| Define container | `@container` on parent |
83| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |
84| Named containers | `@container/card` for specificity |
85 
86### When to Use
87 
88| Scenario | Use |
89|----------|-----|
90| Page-level layouts | Viewport breakpoints |
91| Component-level responsive | Container queries |
92| Reusable components | Container queries (context-independent) |
93 
94---
95 
96## 4. Responsive Design
97 
98### Breakpoint System
99 
100| Prefix | Min Width | Target |
101|--------|-----------|--------|
102| (none) | 0px | Mobile-first base |
103| `sm:` | 640px | Large phone / small tablet |
104| `md:` | 768px | Tablet |
105| `lg:` | 1024px | Laptop |
106| `xl:` | 1280px | Desktop |
107| `2xl:` | 1536px | Large desktop |
108 
109### Mobile-First Principle
110 
1111. Write mobile styles first (no prefix)
1122. Add larger screen overrides with prefixes
1133. Example: `w-full md:w-1/2 lg:w-1/3`
114 
115---
116 
117## 5. Dark Mode
118 
119### Configuration Strategies
120 
121| Method | Behavior | Use When |
122|--------|----------|----------|
123| `class` | `.dark` class toggles | Manual theme switcher |
124| `media` | Follows system preference | No user control |
125| `selector` | Custom selector (v4) | Complex theming |
126 
127### Dark Mode Pattern
128 
129| Element | Light | Dark |
130|---------|-------|------|
131| Background | `bg-white` | `dark:bg-zinc-900` |
132| Text | `text-zinc-900` | `dark:text-zinc-100` |
133| Borders | `border-zinc-200` | `dark:border-zinc-700` |
134 
135---
136 
137## 6. Modern Layout Patterns
138 
139### Flexbox Patterns
140 
141| Pattern | Classes |
142|---------|---------|
143| Center (both axes) | `flex items-center justify-center` |
144| Vertical stack | `flex flex-col gap-4` |
145| Horizontal row | `flex gap-4` |
146| Space between | `flex justify-between items-center` |
147| Wrap grid | `flex flex-wrap gap-4` |
148 
149### Grid Patterns
150 
151| Pattern | Classes |
152|---------|---------|
153| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |
154| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |
155| Sidebar layout | `grid grid-cols-[auto_1fr]` |
156 
157> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.
158 
159---
160 
161## 7. Modern Color System
162 
163### OKLCH vs RGB/HSL
164 
165| Format | Advantage |
166|--------|-----------|
167| **OKLCH** | Perceptually uniform, better for design |
168| **HSL** | Intuitive hue/saturation |
169| **RGB** | Legacy compatibility |
170 
171### Color Token Architecture
172 
173| Layer | Example | Purpose |
174|-------|---------|---------|
175| **Primitive** | `--blue-500` | Raw color values |
176| **Semantic** | `--color-primary` | Purpose-based naming |
177| **Component** | `--button-bg` | Component-specific |
178 
179---
180 
181## 8. Typography System
182 
183### Font Stack Pattern
184 
185| Type | Recommended |
186|------|-------------|
187| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |
188| Mono | `'JetBrains Mono', 'Fira Code', monospace` |
189| Display | `'Outfit', 'Poppins', sans-serif` |
190 
191### Type Scale
192 
193| Class | Size | Use |
194|-------|------|-----|
195| `text-xs` | 0.75rem | Labels, captions |
196| `text-sm` | 0.875rem | Secondary text |
197| `text-base` | 1rem | Body text |
198| `text-lg` | 1.125rem | Lead text |
199| `text-xl`+ | 1.25rem+ | Headings |
200 
201---
202 
203## 9. Animation & Transitions
204 
205### Built-in Animations
206 
207| Class | Effect |
208|-------|--------|
209| `animate-spin` | Continuous rotation |
210| `animate-ping` | Attention pulse |
211| `animate-pulse` | Subtle opacity pulse |
212| `animate-bounce` | Bouncing effect |
213 
214### Transition Patterns
215 
216| Pattern | Classes |
217|---------|---------|
218| All properties | `transition-all duration-200` |
219| Specific | `transition-colors duration-150` |
220| With easing | `ease-out` or `ease-in-out` |
221| Hover effect | `hover:scale-105 transition-transform` |
222 
223---
224 
225## 10. Component Extraction
226 
227### When to Extract
228 
229| Signal | Action |
230|--------|--------|
231| Same class combo 3+ times | Extract component |
232| Complex state variants | Extract component |
233| Design system element | Extract + document |
234 
235### Extraction Methods
236 
237| Method | Use When |
238|--------|----------|
239| **React/Vue component** | Dynamic, JS needed |
240| **@apply in CSS** | Static, no JS needed |
241| **Design tokens** | Reusable values |
242 
243---
244 
245## 11. Anti-Patterns
246 
247| Don't | Do |
248|-------|-----|
249| Arbitrary values everywhere | Use design system scale |
250| `!important` | Fix specificity properly |
251| Inline `style=` | Use utilities |
252| Duplicate long class lists | Extract component |
253| Mix v3 config with v4 | Migrate fully to CSS-first |
254| Use `@apply` heavily | Prefer components |
255 
256---
257 
258## 12. Performance Principles
259 
260| Principle | Implementation |
261|-----------|----------------|
262| **Purge unused** | Automatic in v4 |
263| **Avoid dynamism** | No template string classes |
264| **Use Oxide** | Default in v4, 10x faster |
265| **Cache builds** | CI/CD caching |
266 
267---
268 
269> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.
270