tailwind-css-v4-mastery

What this skill does

# 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**
   - List all `tailwind.config.js` overrides
   - Identify custom utilities and components
   - Scan for deprecated utility usage (opacity, flex-shrink, etc.)
   - Check browser support requirements

2. **Installation Phase**
   ```bash
   npm install -D tailwindcss@latest
   npm install -D @tailwindcss/vite  # (or @tailwindcss/postcss or @tailwindcss/cli)
   ```

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

4. **Utility Refactoring**
   - `.shadow` → `.shadow-sm`
   - `.rounded` → `.rounded-sm`
   - `.outline-none` → `.outline-hidden`
   - `.bg-opacity-*` → `.bg-black/*` (slash syntax)

5. **Validation**
   - Test responsive breakpoints
   - Verify dark mode
   - Check custom components
   - 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**
   - List component primitives (Button, Card, Input, etc.)
   - Identify shared styling patterns
   - Plan for theme customization

2. **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;
   }
   ```

3. **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;
     }
   }
   ```

4. **Establish Modifier Conventions**
   - Size modifiers: `.btn-sm`, `.btn-lg`
   - State modifiers: `.btn-disabled`, `.btn-loading`
   - Variant modifiers: `.btn-primary`, `.btn-secondary`

5. **Document & Export**
   - Create component reference
   - Provide usage examples
   - 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**
   - Measure current build time
   - Check CSS file size
   - Monitor HMR speed

2. **Plugin Selection**
   - Use `@tailwindcss/vite` (fastest option)
   - Enable Lightning CSS if using PostCSS
   - Disable unnecessary optimizations

3. **Configuration Tuning**
   ```javascript
   // vite.config.ts
   import tailwindcss from "@tailwindcss/vite";
   
   export default defineConfig({
     plugins: [react(), tailwindcss()]
   });
   ```

4. **CSS Variable Optimization**
   - Use native CSS variables instead of computed values
   - Leverage cascade for scoped themes
   - Minimize `@theme` block duplication

5. **Validation**
   - Verify build time improvement
   - Check file size reduction
   - 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-p