# Tailwind CSS Migration Plan: v1.4/v2.2 → v3.4

**Created:** December 2024
**Status:** Planned
**Estimated Time:** 2-3 hours

---

## Current State

### Two Tailwind Setups

| Component | Version | Source | Purpose |
|-----------|---------|--------|---------|
| Base styles | 2.2.19 | CDN + local fallback | Core Tailwind utilities for all frontends |
| Custom overrides | 1.4.6 | npm build | Windmill Dashboard theme (admin/vendor) |

### Current Files

```
package.json                           # tailwindcss: 1.4.6
tailwind.config.js                     # v1.4 format config
static/shared/css/tailwind.min.css     # CDN fallback (v2.2.19)
static/admin/css/tailwind.output.css   # Built overrides
static/vendor/css/tailwind.output.css  # Built overrides
```

### Current Plugins

```json
{
  "@tailwindcss/custom-forms": "0.2.1",    // DEPRECATED in v3
  "tailwindcss-multi-theme": "1.0.3"       // May not work with v3
}
```

---

## Migration Goals

1. Upgrade npm Tailwind to v3.4.x (latest stable)
2. Upgrade CDN Tailwind to v3.4.x
3. Update local fallback file
4. Replace deprecated plugins
5. Update config to v3 format
6. Verify all frontends work correctly

---

## Step-by-Step Migration

### Phase 1: Backup Current State

```bash
# Create backup branch
git checkout -b backup/tailwind-v1.4
git add -A
git commit -m "Backup before Tailwind v3 migration"
git checkout master

# Create migration branch
git checkout -b feat/tailwind-v3-upgrade
```

### Phase 2: Update npm Dependencies

```bash
# Remove old packages
npm uninstall tailwindcss tailwindcss-multi-theme @tailwindcss/custom-forms

# Install new packages
npm install -D tailwindcss@latest postcss@latest autoprefixer@latest
npm install -D @tailwindcss/forms @tailwindcss/typography

# Verify versions
npm list tailwindcss
```

**Expected versions:**
- tailwindcss: ^3.4.x
- postcss: ^8.4.x
- autoprefixer: ^10.4.x

### Phase 3: Update tailwind.config.js

Replace the entire config file:

```javascript
// tailwind.config.js - Tailwind CSS v3.4
/** @type {import('tailwindcss').Config} */
module.exports = {
  // v3: 'content' replaces 'purge'
  content: [
    'app/templates/**/*.html',
    'static/**/*.js',
  ],

  // v3: safelist for dynamic classes
  safelist: [
    'bg-orange-600',
    'bg-green-600',
    'bg-red-600',
    'hover:bg-orange-700',
    'hover:bg-green-700',
    'hover:bg-red-700',
    // Add any other dynamic classes used in Alpine.js
  ],

  // v3: darkMode replaces tailwindcss-multi-theme
  darkMode: 'class', // or 'media' for OS preference

  theme: {
    extend: {
      // Custom colors from Windmill Dashboard
      colors: {
        gray: {
          50: '#f9fafb',
          100: '#f4f5f7',
          200: '#e5e7eb',
          300: '#d5d6d7',
          400: '#9e9e9e',
          500: '#707275',
          600: '#4c4f52',
          700: '#24262d',
          800: '#1a1c23',
          900: '#121317',
        },
        purple: {
          50: '#f6f5ff',
          100: '#edebfe',
          200: '#dcd7fe',
          300: '#cabffd',
          400: '#ac94fa',
          500: '#9061f9',
          600: '#7e3af2',
          700: '#6c2bd9',
          800: '#5521b5',
          900: '#4a1d96',
        },
        // Add other custom colors as needed
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', '-apple-system', 'sans-serif'],
      },
      maxHeight: {
        'xl': '36rem',
      },
    },
  },

  plugins: [
    require('@tailwindcss/forms'),      // Replaces @tailwindcss/custom-forms
    require('@tailwindcss/typography'), // Optional: for prose content
  ],
}
```

### Phase 4: Update CSS Source File

Update `static/admin/css/tailwind.css`:

```css
/* Tailwind CSS v3 directives */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Custom component classes if needed */
@layer components {
  .form-input {
    @apply block w-full rounded-md border-gray-300 shadow-sm
           focus:border-purple-500 focus:ring-purple-500;
  }

  .form-select {
    @apply block w-full rounded-md border-gray-300 shadow-sm
           focus:border-purple-500 focus:ring-purple-500;
  }

  .form-checkbox {
    @apply rounded border-gray-300 text-purple-600
           focus:ring-purple-500;
  }
}
```

### Phase 5: Update postcss.config.js

```javascript
// postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    ...(process.env.NODE_ENV === 'production' ? { cssnano: {} } : {})
  }
}
```

### Phase 6: Update package.json Scripts

```json
{
  "scripts": {
    "tailwind:admin": "npx tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css",
    "tailwind:vendor": "npx tailwindcss -i static/admin/css/tailwind.css -o static/vendor/css/tailwind.output.css",
    "tailwind:watch": "npx tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css --watch",
    "build:admin": "npx tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css --minify",
    "build:vendor": "npx tailwindcss -i static/admin/css/tailwind.css -o static/vendor/css/tailwind.output.css --minify",
    "build": "npm run build:admin && npm run build:vendor"
  }
}
```

### Phase 7: Update Dark Mode Implementation

**Old approach (tailwindcss-multi-theme):**
```html
<body class="theme-dark">
  <div class="bg-white dark:bg-gray-800">
```

**New approach (Tailwind v3 native):**
```html
<body class="dark">
  <div class="bg-white dark:bg-gray-800">
```

**Files to update:**
1. `app/templates/admin/base.html` - Change `theme-dark` to `dark`
2. `app/templates/vendor/base.html` - Change `theme-dark` to `dark`
3. `static/admin/js/init-alpine.js` - Update dark mode toggle logic
4. `static/vendor/js/init-alpine.js` - Update dark mode toggle logic

**JavaScript update example:**
```javascript
// Old
document.body.classList.toggle('theme-dark');

// New
document.documentElement.classList.toggle('dark');
```

### Phase 8: Update CDN and Local Fallback

**Option A: Use Tailwind Play CDN (development only)**
```html
<script src="https://cdn.tailwindcss.com"></script>
```

**Option B: Build and serve locally (recommended for production)**

Since Tailwind v3 doesn't have a pre-built CDN CSS file (it's JIT-only), the recommended approach is:

1. Remove CDN loading from templates
2. Load only the built `tailwind.output.css`
3. Include all needed utilities in your build

**Update base templates:**
```html
<!-- OLD: CDN with fallback -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css"
      onerror="this.onerror=null; this.href='{{ url_for('static', path='shared/css/tailwind.min.css') }}';">
<link rel="stylesheet" href="{{ url_for('static', path='admin/css/tailwind.output.css') }}" />

<!-- NEW: Local only (v3) -->
<link rel="stylesheet" href="{{ url_for('static', path='admin/css/tailwind.output.css') }}" />
```

### Phase 9: Build and Test

```bash
# Install dependencies
npm install

# Build CSS
npm run tailwind:admin
npm run tailwind:vendor

# Start development server
make dev

# Test all frontends:
# - http://localhost:8000/admin/dashboard
# - http://localhost:8000/vendor/{code}/dashboard
# - http://localhost:8000/ (shop)
```

### Phase 10: Verify Checklist

- [ ] Admin dashboard loads correctly
- [ ] Vendor dashboard loads correctly
- [ ] Shop frontend loads correctly
- [ ] Dark mode toggle works
- [ ] All buttons have correct colors
- [ ] Forms display correctly (inputs, selects, checkboxes)
- [ ] Responsive design works (mobile/tablet/desktop)
- [ ] No console errors
- [ ] Production build works (`npm run build`)

---

## Breaking Changes Reference

### Class Name Changes (v2 → v3)

| v2.x | v3.x | Notes |
|------|------|-------|
| `overflow-ellipsis` | `text-ellipsis` | Renamed |
| `flex-grow-0` | `grow-0` | Shortened |
| `flex-shrink-0` | `shrink-0` | Shortened |
| `decoration-clone` | `box-decoration-clone` | Renamed |

### Plugin Changes

| Old Plugin | New Plugin | Notes |
|------------|------------|-------|
| `@tailwindcss/custom-forms` | `@tailwindcss/forms` | Complete rewrite |
| `tailwindcss-multi-theme` | Built-in `darkMode: 'class'` | Native support |

### Config Changes

| v1.x/v2.x | v3.x |
|-----------|------|
| `purge: [...]` | `content: [...]` |
| `variants: {...}` | Removed (JIT generates all) |
| `mode: 'jit'` | Default (not needed) |

---

## Rollback Plan

If issues arise:

```bash
# Switch back to backup branch
git checkout backup/tailwind-v1.4

# Or reset changes
git checkout master
git reset --hard HEAD~1
```

---

## Post-Migration Tasks

1. Update `docs/frontend/tailwind-css.md` with v3 information
2. Update `docs/frontend/cdn-fallback-strategy.md` (or remove CDN references)
3. Remove `static/shared/css/tailwind.min.css` if no longer needed
4. Update any documentation referencing old class names
5. Consider adding Tailwind IntelliSense VS Code extension config

---

## Resources

- [Tailwind CSS v3 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
- [Tailwind CSS v3 Documentation](https://tailwindcss.com/docs)
- [@tailwindcss/forms Plugin](https://github.com/tailwindlabs/tailwindcss-forms)
- [Dark Mode in Tailwind v3](https://tailwindcss.com/docs/dark-mode)