orion/docs/frontend/tailwind-migration-plan.md

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

{
  "@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

# 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

# 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:

// 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:

/* 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

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

Phase 6: Update package.json Scripts

{
  "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):

<body class="theme-dark">
  <div class="bg-white dark:bg-gray-800">

New approach (Tailwind v3 native):

<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:

// 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)

<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:

<!-- 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

# 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:

# 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
• Tailwind CSS v3 Documentation
• @tailwindcss/forms Plugin
• Dark Mode in Tailwind v3