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