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.
Overview
Expertise in modern Tailwind CSS v4 practices, avoiding bloated markup and utilizing robust configuration.
Core Process
- Map design requirements to existing Tailwind theme variables.
- Construct responsive layouts using official breakpoints and container queries.
- Refactor repetitive inline classes into component structures (not
@apply).
- Validate that the CSS bundle size remains optimized.
Common Rationalizations
| Rationalization |
Reality |
| I'll use a custom class name instead of utility classes for this complex layout. |
Breaks the utility-first paradigm and increases the CSS bundle size. |
| I'll hardcode the breakpoint pixels instead of using the Tailwind theme. |
Hardcoded breakpoints break responsiveness if the design system changes. |
| I don't need to use arbitrary values, I'll just add a new config entry for this one-off. |
Clutters the Tailwind config; arbitrary values are designed for one-offs. |
Red Flags
- Overuse of
@apply in CSS files instead of utility classes in HTML/JSX.
- Hardcoded color hex codes instead of semantic Tailwind theme colors.
- Unnecessary nesting or deeply complex CSS files bypassing Tailwind.
Verification
1---2name: tailwind-patterns3description: Use when styling components with Tailwind CSS v4, managing CSS-first configurations, writing container queries, or implementing design token architecture.4---56# Tailwind CSS Patterns (v4 - 2025)78> Modern utility-first CSS with CSS-native configuration.910## When to Use11Use this skill when configuring Tailwind v4, using CSS-first theme and design tokens, or implementing container queries and modern Tailwind patterns.1213---1415## 1. Tailwind v4 Architecture1617### What Changed from v31819| 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 |2627### v4 Core Concepts2829| 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 |3536---3738## 2. CSS-Based Configuration3940### Theme Definition4142```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```6061### When to Extend vs Override6263| 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) |6869---7071## 3. Container Queries (v4 Native)7273### Breakpoint vs Container7475| Type | Responds To |76|------|-------------|77| **Breakpoint** (`md:`) | Viewport width |78| **Container** (`@container`) | Parent element width |7980### Container Query Usage8182| Pattern | Classes |83|---------|---------|84| Define container | `@container` on parent |85| Container breakpoint | `@sm:`, `@md:`, `@lg:` on children |86| Named containers | `@container/card` for specificity |8788### When to Use8990| Scenario | Use |91|----------|-----|92| Page-level layouts | Viewport breakpoints |93| Component-level responsive | Container queries |94| Reusable components | Container queries (context-independent) |9596---9798## 4. Responsive Design99100### Breakpoint System101102| 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 |110111### Mobile-First Principle1121131. Write mobile styles first (no prefix)1142. Add larger screen overrides with prefixes1153. Example: `w-full md:w-1/2 lg:w-1/3`116117---118119## 5. Dark Mode120121### Configuration Strategies122123| 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 |128129### Dark Mode Pattern130131| 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` |136137---138139## 6. Modern Layout Patterns140141### Flexbox Patterns142143| 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` |150151### Grid Patterns152153| 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]` |158159> **Note:** Prefer asymmetric/Bento layouts over symmetric 3-column grids.160161---162163## 7. Modern Color System164165### OKLCH vs RGB/HSL166167| Format | Advantage |168|--------|-----------|169| **OKLCH** | Perceptually uniform, better for design |170| **HSL** | Intuitive hue/saturation |171| **RGB** | Legacy compatibility |172173### Color Token Architecture174175| Layer | Example | Purpose |176|-------|---------|---------|177| **Primitive** | `--blue-500` | Raw color values |178| **Semantic** | `--color-primary` | Purpose-based naming |179| **Component** | `--button-bg` | Component-specific |180181---182183## 8. Typography System184185### Font Stack Pattern186187| 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` |192193### Type Scale194195| 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 |202203---204205## 9. Animation & Transitions206207### Built-in Animations208209| Class | Effect |210|-------|--------|211| `animate-spin` | Continuous rotation |212| `animate-ping` | Attention pulse |213| `animate-pulse` | Subtle opacity pulse |214| `animate-bounce` | Bouncing effect |215216### Transition Patterns217218| 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` |224225---226227## 10. Component Extraction228229### When to Extract230231| Signal | Action |232|--------|--------|233| Same class combo 3+ times | Extract component |234| Complex state variants | Extract component |235| Design system element | Extract + document |236237### Extraction Methods238239| Method | Use When |240|--------|----------|241| **React/Vue component** | Dynamic, JS needed |242| **@apply in CSS** | Static, no JS needed |243| **Design tokens** | Reusable values |244245---246247## 11. Anti-Patterns248249| 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 |257258---259260## 12. Performance Principles261262| 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 |268269---270271> **Remember:** Tailwind v4 is CSS-first. Embrace CSS variables, container queries, and native features. The config file is now optional.272273## Limitations274- 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.277278279## Overview280Expertise in modern Tailwind CSS v4 practices, avoiding bloated markup and utilizing robust configuration.281282## Core Process2831. Map design requirements to existing Tailwind theme variables.2842. Construct responsive layouts using official breakpoints and container queries.2853. Refactor repetitive inline classes into component structures (not `@apply`).2864. Validate that the CSS bundle size remains optimized.287288## Common Rationalizations289| Rationalization | Reality |290|---|---|291| I'll use a custom class name instead of utility classes for this complex layout. | Breaks the utility-first paradigm and increases the CSS bundle size. |292| I'll hardcode the breakpoint pixels instead of using the Tailwind theme. | Hardcoded breakpoints break responsiveness if the design system changes. |293| I don't need to use arbitrary values, I'll just add a new config entry for this one-off. | Clutters the Tailwind config; arbitrary values are designed for one-offs. |294295## Red Flags296- Overuse of `@apply` in CSS files instead of utility classes in HTML/JSX.297- Hardcoded color hex codes instead of semantic Tailwind theme colors.298- Unnecessary nesting or deeply complex CSS files bypassing Tailwind.299300## Verification301- [ ] Styling relies primarily on Tailwind utility classes.302- [ ] Responsive design uses official theme breakpoints.303- [ ] Tailwind config remains clean without unnecessary one-off values.
hybridlabor-api 