Tailwind CSS Patterns (v4 - 2025)
Selective Reading Rule
Start with:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.
Modern utility-first CSS with CSS-native configuration.
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.
1---2name: tailwind-patterns3description: ALWAYS use this when the user mentions Tailwind Patterns, asks to build, debug, review, document, automate, test, configure, migrate, or make decisions in this domain, or the task clearly depends on Tailwind Patterns; scope: Tailwind CSS v4 principles. Apply the bundled workflow, references, scripts, Senior Master standard, and Codex strict review gate before final output.4---56# Tailwind CSS Patterns (v4 - 2025)78## Selective Reading Rule910Start with:1112- `references/senior-master-standard.md`13- `references/usage-routing.md`14- `references/quality-checklist.md`1516Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.1718> Modern utility-first CSS with CSS-native configuration.1920---2122## 1. Tailwind v4 Architecture2324### What Changed from v32526| v3 (Legacy) | v4 (Current) |27|-------------|--------------|28| `tailwind.config.js` | CSS-based `@theme` directive |29| PostCSS plugin | Oxide engine (10x faster) |30| JIT mode | Native, always-on |31| Plugin system | CSS-native features |32| `@apply` directive | Still works, discouraged |3334### v4 Core Concepts3536| Concept | Description |37|---------|-------------|38| **CSS-first** | Configuration in CSS, not JavaScript |39| **Oxide Engine** | Rust-based compiler, much faster |40| **Native Nesting** | CSS nesting without PostCSS |41| **CSS Variables** | All tokens exposed as `--*` vars |4243---4445## 2. CSS-Based Configuration4647### Theme Definition4849```50@theme {51 /* Colors - use semantic names */52 --color-primary: oklch(0.7 0.15 250);53 --color-surface: oklch(0.98 0 0);54 --color-surface-dark: oklch(0.15 0 0);55 56 /* Spacing scale */57 --spacing-xs: 0.25rem;58 --spacing-sm: 0.5rem;59 --spacing-md: 1rem;60 --spacing-lg: 2rem;61 62 /* Typography */63 --font-sans: 'Inter', system-ui, sans-serif;64 --font-mono: 'JetBrains Mono', monospace;65}66```6768### When to Extend vs Override6970| Action | Use When |71|--------|----------|72| **Extend** | Adding new values alongside defaults |73| **Override** | Replacing default scale entirely |74| **Semantic tokens** | Project-specific naming (primary, surface) |7576---7778## 3. Container Queries (v4 Native)7980### Breakpoint vs Container8182| Type | Responds To |83|------|-------------|84| **Breakpoint** (`md:`) | Viewport width |85| **Container** (`@container`) | Parent element width |8687### Container Query Usage8889| Pattern | Classes |90|---------|---------|91| Define container | `@container` on parent |92| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |93| Named containers | `@container/card` for specificity |9495### When to Use9697| Scenario | Use |98|----------|-----|99| Page-level layouts | Viewport breakpoints |100| Component-level responsive | Container queries |101| Reusable components | Container queries (context-independent) |102103---104105## 4. Responsive Design106107### Breakpoint System108109| Prefix | Min Width | Target |110|--------|-----------|--------|111| (none) | 0px | Mobile-first base |112| `sm:` | 640px | Large phone / small tablet |113| `md:` | 768px | Tablet |114| `lg:` | 1024px | Laptop |115| `xl:` | 1280px | Desktop |116| `2xl:` | 1536px | Large desktop |117118### Mobile-First Principle1191201. Write mobile styles first (no prefix)1212. Add larger screen overrides with prefixes1223. Example: `w-full md:w-1/2 lg:w-1/3`123124---125126## 5. Dark Mode127128### Configuration Strategies129130| Method | Behavior | Use When |131|--------|----------|----------|132| `class` | `.dark` class toggles | Manual theme switcher |133| `media` | Follows system preference | No user control |134| `selector` | Custom selector (v4) | Complex theming |135136### Dark Mode Pattern137138| Element | Light | Dark |139|---------|-------|------|140| Background | `bg-white` | `dark:bg-zinc-900` |141| Text | `text-zinc-900` | `dark:text-zinc-100` |142| Borders | `border-zinc-200` | `dark:border-zinc-700` |143144---145146## 6. Modern Layout Patterns147148### Flexbox Patterns149150| Pattern | Classes |151|---------|---------|152| Center (both axes) | `flex items-center justify-center` |153| Vertical stack | `flex flex-col gap-4` |154| Horizontal row | `flex gap-4` |155| Space between | `flex justify-between items-center` |156| Wrap grid | `flex flex-wrap gap-4` |157158### Grid Patterns159160| Pattern | Classes |161|---------|---------|162| Auto-fit responsive | `grid grid-cols-[repeat(auto-fit,minmax(250px,1fr))]` |163| Asymmetric (Bento) | `grid grid-cols-3 grid-rows-2` with spans |164| Sidebar layout | `grid grid-cols-[auto_1fr]` |165166> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.167168---169170## 7. Modern Color System171172### OKLCH vs RGB/HSL173174| Format | Advantage |175|--------|-----------|176| **OKLCH** | Perceptually uniform, better for design |177| **HSL** | Intuitive hue/saturation |178| **RGB** | Legacy compatibility |179180### Color Token Architecture181182| Layer | Example | Purpose |183|-------|---------|---------|184| **Primitive** | `--blue-500` | Raw color values |185| **Semantic** | `--color-primary` | Purpose-based naming |186| **Component** | `--button-bg` | Component-specific |187188---189190## 8. Typography System191192### Font Stack Pattern193194| Type | Recommended |195|------|-------------|196| Sans | `'Inter', 'SF Pro', system-ui, sans-serif` |197| Mono | `'JetBrains Mono', 'Fira Code', monospace` |198| Display | `'Outfit', 'Poppins', sans-serif` |199200### Type Scale201202| Class | Size | Use |203|-------|------|-----|204| `text-xs` | 0.75rem | Labels, captions |205| `text-sm` | 0.875rem | Secondary text |206| `text-base` | 1rem | Body text |207| `text-lg` | 1.125rem | Lead text |208| `text-xl`+ | 1.25rem+ | Headings |209210---211212## 9. Animation & Transitions213214### Built-in Animations215216| Class | Effect |217|-------|--------|218| `animate-spin` | Continuous rotation |219| `animate-ping` | Attention pulse |220| `animate-pulse` | Subtle opacity pulse |221| `animate-bounce` | Bouncing effect |222223### Transition Patterns224225| Pattern | Classes |226|---------|---------|227| All properties | `transition-all duration-200` |228| Specific | `transition-colors duration-150` |229| With easing | `ease-out` or `ease-in-out` |230| Hover effect | `hover:scale-105 transition-transform` |231232---233234## 10. Component Extraction235236### When to Extract237238| Signal | Action |239|--------|--------|240| Same class combo 3+ times | Extract component |241| Complex state variants | Extract component |242| Design system element | Extract + document |243244### Extraction Methods245246| Method | Use When |247|--------|----------|248| **React/Vue component** | Dynamic, JS needed |249| **@apply in CSS** | Static, no JS needed |250| **Design tokens** | Reusable values |251252---253254## 11. Anti-Patterns255256| Don't | Do |257|-------|-----|258| Arbitrary values everywhere | Use design system scale |259| `!important` | Fix specificity properly |260| Inline `style=` | Use utilities |261| Duplicate long class lists | Extract component |262| Mix v3 config with v4 | Migrate fully to CSS-first |263| Use `@apply` heavily | Prefer components |264265---266267## 12. Performance Principles268269| Principle | Implementation |270|-----------|----------------|271| **Purge unused** | Automatic in v4 |272| **Avoid dynamism** | No template string classes |273| **Use Oxide** | Default in v4, 10x faster |274| **Cache builds** | CI/CD caching |275276---277278> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.
anhvu1107