tailwind-patterns

name	tailwind-patterns
description	Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.
allowed-tools	Read, Write, Edit, Glob, Grep

Tailwind CSS Patterns (v4 - 2025)

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

1. Write mobile styles first (no prefix)
2. Add larger screen overrides with prefixes
3. 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.

Refer to resources/implementation-playbook.md for detailed v4 patterns and project-specific configuration rules.