tailwind-css-v4-mastery

Tailwind CSS V4 Mastery Skill

Philosophy: CSS-First Thinking

Tailwind V4 represents a philosophical shift from JavaScript-centric utility frameworks to CSS-native, declarative styling. This skill installs that mental model:

• Configuration is CSS — @theme {} replaces tailwind.config.js
• Speed is Architectural — Oxide engine (Rust) replaces JavaScript parser
• Modern Standards First — Leverages @property, color-mix(), CSS nesting
• Performance as a First-Class Citizen — 10-100x faster than v3

The correct mental model for V4: "CSS is the source of truth. JavaScript configuration is outdated."

Core Conceptual Landscape

1. The Oxide Engine Revolution

What Changed:

v3: JavaScript → JavaScript Parser → CSS Output
v4: CSS @theme → Rust/Oxide Engine → Optimized CSS Output

Why It Matters:

• Performance: 10-100x faster build times, 15-30x faster HMR
• Simplicity: One language (CSS) instead of two (JS + CSS)
• Future-Proofing: Aligned with native browser capabilities

Mental Model: Think of the Oxide engine as a compiler, not a preprocessor. It compiles CSS declarations into optimized output.

2. CSS-First Configuration Paradigm

The Core Shift:

| Aspect | v3 | v4 | |--------|-----|-----| | Config Format | JavaScript Object | CSS @theme {} Block | | Location | tailwind.config.js | styles.css | | Execution | Node.js at build time | Oxide engine | | Debugging | Console logs, file inspection | CSS DevTools | | Scope | Global import | CSS cascade-aware |

Why This Matters: CSS-first configuration is more maintainable, debuggable, and aligned with how browsers actually work. You're no longer fighting a layer of abstraction.

3. Browser Requirements & Modern CSS Features

Tailwind V4 requires modern browser capabilities:

• Safari 16.4+ (OKLch color space, @property)
• Chrome 111+ (color-mix())
• Firefox 128+ (CSS nesting)

This is intentional. V4 assumes modern CSS and optimizes around it. Legacy support requires v3.4.x.

Procedural Workflows

Workflow 1: Migration from V3 to V4

Trigger: User wants to upgrade existing Tailwind project from v3 to v4

Steps:

1. Audit Phase
2. List all tailwind.config.js overrides
3. Identify custom utilities and components
4. Scan for deprecated utility usage (opacity, flex-shrink, etc.)
5. Check browser support requirements

1. Installation Phase

``bash npm install -D tailwindcss@latest npm install -D @tailwindcss/vite # (or @tailwindcss/postcss or @tailwindcss/cli) ``

1. Configuration Migration
2. Convert theme: {} → @theme { --var: value; }
3. Convert extend: {} → Additional --var in @theme
4. Replace @tailwind base/components/utilities → @import "tailwindcss"

1. Utility Refactoring
2. .shadow → .shadow-sm
3. .rounded → .rounded-sm
4. .outline-none → .outline-hidden
5. .bg-opacity- → .bg-black/ (slash syntax)

1. Validation
2. Test responsive breakpoints
3. Verify dark mode
4. Check custom components
5. Performance baseline

Decision Tree:

Is this a new project?
  ├─ YES → Use V4 directly with @theme config
  └─ NO → Execute migration workflow above
     ├─ Does v3 use custom config extensively?
     │  ├─ YES → Allocate migration time, go step-by-step
     │  └─ NO → Quick migration, 30 mins
     └─ Are you on legacy browsers?
        ├─ YES → Stay on v3.4
        └─ NO → Proceed with v4

Workflow 2: Component System Design

Trigger: User wants to build reusable component library with Tailwind V4

Steps:

1. Define Component Scope
2. List component primitives (Button, Card, Input, etc.)
3. Identify shared styling patterns
4. Plan for theme customization

1. Create Base Theme

```css @import "tailwindcss";

@theme { / Color system / --color-primary-: oklch(...); --color-neutral-: oklch(...);

/ Spacing scale / --spacing-xs: 0.25rem; --spacing-sm: 0.5rem; --spacing-md: 1rem;

/ Typography / --font-display: "Custom", sans-serif; --font-body: "System", sans-serif; } ```

1. Build Component Classes

```css @layer components { .btn-primary { @apply px-4 py-2 rounded-sm bg-primary text-white font-semibold transition-all hover:opacity-90; }

.card { @apply p-6 rounded-lg bg-white shadow-md border border-gray-200; } } ```

1. Establish Modifier Conventions
2. Size modifiers: .btn-sm, .btn-lg
3. State modifiers: .btn-disabled, .btn-loading
4. Variant modifiers: .btn-primary, .btn-secondary

1. Document & Export
2. Create component reference
3. Provide usage examples
4. Document theme variables

Output: Production-ready component library CSS file

Workflow 3: Performance Optimization

Trigger: User needs to optimize Tailwind V4 performance

Steps:

1. Baseline Measurement
2. Measure current build time
3. Check CSS file size
4. Monitor HMR speed

1. Plugin Selection
2. Use @tailwindcss/vite (fastest option)
3. Enable Lightning CSS if using PostCSS
4. Disable unnecessary optimizations

1. Configuration Tuning

```javascript // vite.config.ts import tailwindcss from "@tailwindcss/vite";

export default defineConfig({ plugins: [react(), tailwindcss()] }); ```

1. CSS Variable Optimization
2. Use native CSS variables instead of computed values
3. Leverage cascade for scoped themes
4. Minimize @theme block duplication

1. Validation
2. Verify build time improvement
3. Check file size reduction
4. Confirm visual consistency

Expected Outcomes:

• Build time: 100-500ms (vs 5-10s in v3)
• Hot reload: 50-200ms (vs 3s in v3)
• CSS size: -15-20% reduction

Critical Decision Trees

Decision 1: Plugin Selection

What build tool do you use?
├─ Vite (React, Vue, Svelte)
│  └─ Use @tailwindcss/vite (fastest, recommended)
├─ Webpack (NextJS, CRA)
│  └─ Use @tailwindcss/postcss
├─ Standalone/No bundler
│  └─ Use @tailwindcss/cli
└─ PostCSS pipeline
   └─ Use @tailwindcss/postcss

Decision 2: Configuration Approach

How complex is your theme?
├─ Simple (5-10 color overrides)
│  └─ Use inline @theme block in styles.css
├─ Moderate (custom colors, spacing, fonts)
│  └─ Use single @theme block with organization
├─ Complex (multi-theme, extensive customization)
│  └─ Split into @layer base blocks with [data-theme] selectors
└─ Enterprise (multiple brands)
   └─ Use CSS variable strategy with fallbacks

Decision 3: Component Extraction

When should I use @layer components?
├─ Recurring utility combinations
│  └─ YES → Extract to .btn-primary, .card, etc.
├─ One-off layouts
│  └─ NO → Use utilities directly in HTML
├─ Design system compliance needed
│  └─ YES → Extract as component class
└─ User will customize per instance
   └─ NO → Leave as utility composition

Common Gotchas & Solutions

Gotcha 1: Expecting tailwind.config.js to Still Work

Problem: File is ignored in v4. Solution: Use @theme {} in CSS instead. Prevention: Delete tailwind.config.js early in migration.

Gotcha 2: Default Border Color Breaking Layouts

Problem: v3 used currentColor (inherits text), v4 uses #e5e7eb. Solution: Use .border-current if you need inherited color. Prevention: Test all border utilities during migration.

Gotcha 3: Ring Width Changed (3px → 1px)

Problem: Existing .ring classes now have thinner outlines. Solution: Use .ring-3 for old 3px behavior, .ring-1 for new default. Prevention: Find/replace .ring → .ring-1 during migration.

Gotcha 4: CSS Variables Must Have -- Prefix

Problem: @theme { color-primary: value; } is ignored. Solution: Use `@theme { --color-pr