Tailwind CSS Patterns (v4)
Modern utility-first CSS with CSS-native configuration.
1. Tailwind v4 Architecture
What Changed from v3
| v3 (Legacy) |
v4 (Current) |
@tailwind base/components/utilities |
Single @import "tailwindcss"; |
tailwind.config.js (required) |
CSS-first @theme; JS config optional via @config (compat) |
content: [...] globs |
Automatic source detection (+ @source for extras) |
tailwindcss PostCSS plugin |
@tailwindcss/postcss (PostCSS) or @tailwindcss/vite (Vite) |
plugins: [...] in config |
@plugin "pkg"; in CSS (compat for JS plugins) |
addUtilities() in a plugin |
@utility name { ... } in CSS |
darkMode: 'class' |
@custom-variant dark (...) in CSS |
@container-queries plugin |
Container queries built in |
@apply directive |
Still works; prefer components |
v4 Core Concepts
| Concept |
Description |
| CSS-first |
Configuration in CSS, not JavaScript |
| New engine |
Ground-up rewrite; much faster full and incremental builds |
| Build integrations |
Vite plugin (@tailwindcss/vite), PostCSS plugin (@tailwindcss/postcss), or CLI |
| CSS Variables |
All theme tokens exposed as --* vars |
Core Directives
| Directive |
Purpose |
@import "tailwindcss"; |
Load Tailwind (replaces the three @tailwind lines) |
@theme { ... } |
Define design tokens (colors, fonts, breakpoints) |
@source "../path"; |
Add sources automatic detection misses |
@utility name { ... } |
Custom utility that works with variants (hover:, lg:) |
@custom-variant name (...); |
Custom variant (e.g. class-based dark:) |
@variant dark { ... } |
Apply a variant inside your own CSS |
@reference "../app.css"; |
Use @apply in CSS modules / component <style> without duplicating output |
@plugin "pkg"; / @config "file"; |
Load legacy JS plugins / config (v3 compatibility) |
Setup
/* app.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@utility tab-4 {
tab-size: 4;
}
- Vite: add
tailwindcss() from @tailwindcss/vite to plugins
- PostCSS (Next.js, etc.):
postcss.config.mjs → plugins: { "@tailwindcss/postcss": {} }
2. CSS-Based Configuration
Theme Definition
@import "tailwindcss";
@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 |
Default (prefers-color-scheme) |
Follows system preference, no config |
No user control |
| Class |
@custom-variant dark (&:where(.dark, .dark *)); |
Manual theme switcher (<html class="dark">) |
| Data attribute |
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *)); |
Multi-theme setups |
v4 has no darkMode config key: override the dark variant in CSS with @custom-variant (after @import "tailwindcss";).
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 |
@tailwind directives / darkMode config in v4 |
@import "tailwindcss" + @custom-variant dark |
| Mix v3 config with v4 |
Migrate to CSS-first (@config/@plugin only as a bridge) |
Use @apply heavily |
Prefer components |
12. Performance Principles
| Principle |
Implementation |
| Purge unused |
Automatic source detection in v4 (@source for extras) |
| Avoid dynamism |
No template string classes |
| Use the native integration |
@tailwindcss/vite for Vite; @tailwindcss/postcss elsewhere |
| 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.
1---2name: tailwind-patterns3description: "Tailwind CSS v4 with @theme tokens, container queries and dark mode. Use when writing Tailwind styles, migrating from v3 or setting up a Tailwind design system."4allowed-tools: Read Write Edit Glob Grep5metadata:6 source: https://skillmd.com/skills/jeffersonvalente/tailwind-patterns7---89# Tailwind CSS Patterns (v4)1011> Modern utility-first CSS with CSS-native configuration.1213---1415## 1. Tailwind v4 Architecture1617### What Changed from v31819| v3 (Legacy) | v4 (Current) |20|-------------|--------------|21| `@tailwind base/components/utilities` | Single `@import "tailwindcss";` |22| `tailwind.config.js` (required) | CSS-first `@theme`; JS config optional via `@config` (compat) |23| `content: [...]` globs | Automatic source detection (+ `@source` for extras) |24| `tailwindcss` PostCSS plugin | `@tailwindcss/postcss` (PostCSS) or `@tailwindcss/vite` (Vite) |25| `plugins: [...]` in config | `@plugin "pkg";` in CSS (compat for JS plugins) |26| `addUtilities()` in a plugin | `@utility name { ... }` in CSS |27| `darkMode: 'class'` | `@custom-variant dark (...)` in CSS |28| `@container-queries` plugin | Container queries built in |29| `@apply` directive | Still works; prefer components |3031### v4 Core Concepts3233| Concept | Description |34|---------|-------------|35| **CSS-first** | Configuration in CSS, not JavaScript |36| **New engine** | Ground-up rewrite; much faster full and incremental builds |37| **Build integrations** | Vite plugin (`@tailwindcss/vite`), PostCSS plugin (`@tailwindcss/postcss`), or CLI |38| **CSS Variables** | All theme tokens exposed as `--*` vars |3940### Core Directives4142| Directive | Purpose |43|-----------|---------|44| `@import "tailwindcss";` | Load Tailwind (replaces the three `@tailwind` lines) |45| `@theme { ... }` | Define design tokens (colors, fonts, breakpoints) |46| `@source "../path";` | Add sources automatic detection misses |47| `@utility name { ... }` | Custom utility that works with variants (`hover:`, `lg:`) |48| `@custom-variant name (...);` | Custom variant (e.g. class-based `dark:`) |49| `@variant dark { ... }` | Apply a variant inside your own CSS |50| `@reference "../app.css";` | Use `@apply` in CSS modules / component `<style>` without duplicating output |51| `@plugin "pkg";` / `@config "file";` | Load legacy JS plugins / config (v3 compatibility) |5253### Setup5455```56/* app.css */57@import "tailwindcss";58@plugin "@tailwindcss/typography";5960@utility tab-4 {61 tab-size: 4;62}63```6465- **Vite:** add `tailwindcss()` from `@tailwindcss/vite` to `plugins`66- **PostCSS** (Next.js, etc.): `postcss.config.mjs` → `plugins: { "@tailwindcss/postcss": {} }`6768---6970## 2. CSS-Based Configuration7172### Theme Definition7374```75@import "tailwindcss";7677@theme {78 /* Colors - use semantic names */79 --color-primary: oklch(0.7 0.15 250);80 --color-surface: oklch(0.98 0 0);81 --color-surface-dark: oklch(0.15 0 0);82 83 /* Spacing scale */84 --spacing-xs: 0.25rem;85 --spacing-sm: 0.5rem;86 --spacing-md: 1rem;87 --spacing-lg: 2rem;88 89 /* Typography */90 --font-sans: 'Inter', system-ui, sans-serif;91 --font-mono: 'JetBrains Mono', monospace;92}93```9495### When to Extend vs Override9697| Action | Use When |98|--------|----------|99| **Extend** | Adding new values alongside defaults |100| **Override** | Replacing default scale entirely |101| **Semantic tokens** | Project-specific naming (primary, surface) |102103---104105## 3. Container Queries (v4 Native)106107### Breakpoint vs Container108109| Type | Responds To |110|------|-------------|111| **Breakpoint** (`md:`) | Viewport width |112| **Container** (`@container`) | Parent element width |113114### Container Query Usage115116| Pattern | Classes |117|---------|---------|118| Define container | `@container` on parent |119| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |120| Named containers | `@container/card` for specificity |121122### When to Use123124| Scenario | Use |125|----------|-----|126| Page-level layouts | Viewport breakpoints |127| Component-level responsive | Container queries |128| Reusable components | Container queries (context-independent) |129130---131132## 4. Responsive Design133134### Breakpoint System135136| Prefix | Min Width | Target |137|--------|-----------|--------|138| (none) | 0px | Mobile-first base |139| `sm:` | 640px | Large phone / small tablet |140| `md:` | 768px | Tablet |141| `lg:` | 1024px | Laptop |142| `xl:` | 1280px | Desktop |143| `2xl:` | 1536px | Large desktop |144145### Mobile-First Principle1461471. Write mobile styles first (no prefix)1482. Add larger screen overrides with prefixes1493. Example: `w-full md:w-1/2 lg:w-1/3`150151---152153## 5. Dark Mode154155### Configuration Strategies156157| Method | Behavior | Use When |158|--------|----------|----------|159| Default (`prefers-color-scheme`) | Follows system preference, no config | No user control |160| Class | `@custom-variant dark (&:where(.dark, .dark *));` | Manual theme switcher (`<html class="dark">`) |161| Data attribute | `@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));` | Multi-theme setups |162163> v4 has no `darkMode` config key: override the `dark` variant in CSS with `@custom-variant` (after `@import "tailwindcss";`).164165### Dark Mode Pattern166167| Element | Light | Dark |168|---------|-------|------|169| Background | `bg-white` | `dark:bg-zinc-900` |170| Text | `text-zinc-900` | `dark:text-zinc-100` |171| Borders | `border-zinc-200` | `dark:border-zinc-700` |172173---174175## 6. Modern Layout Patterns176177### Flexbox Patterns178179| Pattern | Classes |180|---------|---------|181| Center (both axes) | `flex items-center justify-center` |182| Vertical stack | `flex flex-col gap-4` |183| Horizontal row | `flex gap-4` |184| Space between | `flex justify-between items-center` |185| Wrap grid | `flex flex-wrap gap-4` |186187### Grid Patterns188189| Pattern | Classes |190|---------|---------|191| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |192| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |193| Sidebar layout | `grid grid-cols-[auto_1fr]` |194195> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.196197---198199## 7. Modern Color System200201### OKLCH vs RGB/HSL202203| Format | Advantage |204|--------|-----------|205| **OKLCH** | Perceptually uniform, better for design |206| **HSL** | Intuitive hue/saturation |207| **RGB** | Legacy compatibility |208209### Color Token Architecture210211| Layer | Example | Purpose |212|-------|---------|---------|213| **Primitive** | `--blue-500` | Raw color values |214| **Semantic** | `--color-primary` | Purpose-based naming |215| **Component** | `--button-bg` | Component-specific |216217---218219## 8. Typography System220221### Font Stack Pattern222223| Type | Recommended |224|------|-------------|225| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |226| Mono | `'JetBrains Mono', 'Fira Code', monospace` |227| Display | `'Outfit', 'Poppins', sans-serif` |228229### Type Scale230231| Class | Size | Use |232|-------|------|-----|233| `text-xs` | 0.75rem | Labels, captions |234| `text-sm` | 0.875rem | Secondary text |235| `text-base` | 1rem | Body text |236| `text-lg` | 1.125rem | Lead text |237| `text-xl`+ | 1.25rem+ | Headings |238239---240241## 9. Animation & Transitions242243### Built-in Animations244245| Class | Effect |246|-------|--------|247| `animate-spin` | Continuous rotation |248| `animate-ping` | Attention pulse |249| `animate-pulse` | Subtle opacity pulse |250| `animate-bounce` | Bouncing effect |251252### Transition Patterns253254| Pattern | Classes |255|---------|---------|256| All properties | `transition-all duration-200` |257| Specific | `transition-colors duration-150` |258| With easing | `ease-out` or `ease-in-out` |259| Hover effect | `hover:scale-105 transition-transform` |260261---262263## 10. Component Extraction264265### When to Extract266267| Signal | Action |268|--------|--------|269| Same class combo 3+ times | Extract component |270| Complex state variants | Extract component |271| Design system element | Extract + document |272273### Extraction Methods274275| Method | Use When |276|--------|----------|277| **React/Vue component** | Dynamic, JS needed |278| **@apply in CSS** | Static, no JS needed |279| **Design tokens** | Reusable values |280281---282283## 11. Anti-Patterns284285| Don't | Do |286|-------|-----|287| Arbitrary values everywhere | Use design system scale |288| `!important` | Fix specificity properly |289| Inline `style=` | Use utilities |290| Duplicate long class lists | Extract component |291| `@tailwind` directives / `darkMode` config in v4 | `@import "tailwindcss"` + `@custom-variant dark` |292| Mix v3 config with v4 | Migrate to CSS-first (`@config`/`@plugin` only as a bridge) |293| Use `@apply` heavily | Prefer components |294295---296297## 12. Performance Principles298299| Principle | Implementation |300|-----------|----------------|301| **Purge unused** | Automatic source detection in v4 (`@source` for extras) |302| **Avoid dynamism** | No template string classes |303| **Use the native integration** | `@tailwindcss/vite` for Vite; `@tailwindcss/postcss` elsewhere |304| **Cache builds** | CI/CD caching |305306---307308> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.