enviPy-bayer/MIGRATION_GUIDE.md

# Tailwind/DaisyUI Migration Guide

## Overview

This project is using the **Strangler Fig Pattern** to incrementally migrate from Bootstrap 3.3.7 to Tailwind CSS v4 + DaisyUI v5.

## Architecture

### Two Base Templates

1. **`framework.html`** - Legacy Bootstrap template (25 templates use this)
2. **`framework_modern.html`** - Modern Tailwind/DaisyUI template (clean, no Bootstrap)

### Migrated Templates

✅ **index/index.html** - First template migrated to modern framework

### Migration Status

- **Total templates**: 110
- **Templates extending framework**: 25
- **Migrated to modern**: 1 (index.html)
- **Remaining**: 24

## How to Migrate a Template

### Step 1: Change the extends statement

```django
{# Old #}
{% extends "framework.html" %}

{# New #}
{% extends "framework_modern.html" %}
```

### Step 2: Remove Bootstrap wrappers

```django
{# Old #}
<div class="legacy-bootstrap">
    <!-- content -->
</div>

{# New #}
<!-- content -->
```

### Step 3: Convert Bootstrap classes to Tailwind/DaisyUI

Common conversions:

**Bootstrap → Tailwind/DaisyUI**

| Bootstrap | Tailwind/DaisyUI |
|-----------|------------------|
| `btn btn-primary` | `btn btn-primary` (DaisyUI keeps similar naming) |
| `btn btn-default` | `btn` |
| `container` | `container mx-auto` |
| `row` | `flex flex-wrap` or `grid` |
| `col-md-6` | `w-full md:w-1/2` |
| `panel panel-default` | `card bg-base-100 shadow-xl` |
| `alert alert-info` | `alert alert-info` |
| `navbar navbar-default` | `navbar bg-neutral` |
| `modal fade` | `modal` (see DaisyUI modal docs) |

### Step 4: Test functionality

- Verify navigation works
- Test any JavaScript interactions
- Check responsive behavior
- Validate forms still submit correctly

### Step 5: Commit and deploy

Each template migration can be deployed independently since both frameworks coexist.

## Design System

### Color Tokens

Use semantic color tokens from the enviPath theme:

```css
/* Base backgrounds */
bg-base-100   /* Main background (very light blue-ish) */
bg-base-200   /* Secondary background */
bg-base-300   /* Tertiary background */

/* Brand colors */
bg-primary    /* Primary blue */
bg-secondary  /* Secondary teal */
bg-accent     /* Accent color */

/* Semantic colors */
bg-success    /* Green */
bg-warning    /* Yellow/Orange */
bg-error      /* Red */
bg-info       /* Blue */

/* Neutrals */
bg-neutral    /* Dark gray (used in navbar) */
```

### Components

DaisyUI provides ready-to-use components:

- **Navigation**: `navbar`, `menu`, `dropdown`
- **Content**: `card`, `collapse`, `badge`
- **Actions**: `btn`, `modal`, `drawer`
- **Forms**: `input`, `select`, `textarea`, `checkbox`, `radio`
- **Feedback**: `alert`, `toast`, `loading`

See: https://daisyui.com/components/

## Priority Order for Migration

Suggested order based on user visibility:

1. ✅ **index/index.html** (Homepage) - DONE
2. **search.html** (Search page)
3. **objects/pathway.html** (Pathway detail)
4. **objects/compound.html** (Compound detail)
5. **objects/package.html** (Package overview)
6. **collections/objects_list.html** (Generic list view)
7. Other object detail pages
8. Admin pages
9. Error pages

## Known Issues

### Modals Need Conversion

The modal templates (`modals/*.html`) still use Bootstrap markup. They need to be converted to DaisyUI modals:

**Bootstrap Modal:**
```html
<div class="modal fade" id="myModal">
    <div class="modal-dialog">
        <div class="modal-content">...</div>
    </div>
</div>
```

**DaisyUI Modal:**
```html
<dialog id="myModal" class="modal">
    <div class="modal-box">
        <h3 class="font-bold text-lg">Title</h3>
        <p class="py-4">Content</p>
        <div class="modal-action">
            <form method="dialog">
                <button class="btn">Close</button>
            </form>
        </div>
    </div>
</dialog>
```

### JavaScript Compatibility

- jQuery is still included for compatibility
- Bootstrap JavaScript is NOT loaded in modern framework
- Modal triggers will need updating from `data-toggle="modal"` to DaisyUI's approach

## CSS Build Process

After making changes to CSS files:

```bash
# Development (watch mode)
pnpm run dev

# Production build
pnpm run build
```

## Template Structure

### Base Templates
- **`framework.html`** - Legacy Bootstrap base (for unmigrated pages)
- **`framework_modern.html`** - Modern Tailwind/DaisyUI base (for new pages)

### Shared Includes
- **`includes/navbar.html`** - Modern DaisyUI navbar (used in framework_modern.html)
- **`includes/footer.html`** - Modern Tailwind footer (used in framework_modern.html)

These includes make it easy to maintain consistent navigation and footer across all migrated pages.

## Files Modified in Initial Migration

1. `static/css/daisyui-theme.css` - Fixed `--color-base-100: blue` bug
2. `templates/framework_modern.html` - New modern base template
3. `templates/includes/navbar.html` - Extracted navbar component
4. `templates/includes/footer.html` - Extracted footer component
5. `templates/index/index.html` - Migrated to use framework_modern.html
6. `static/css/output.css` - Rebuilt with fixed theme

## Resources

- [Tailwind CSS v4 Docs](https://tailwindcss.com/)
- [DaisyUI v5 Docs](https://daisyui.com/)
- [DaisyUI Components](https://daisyui.com/components/)
- [DaisyUI Themes](https://daisyui.com/docs/themes/)
- [Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html)

## Questions?

Check the existing modern templates for examples:
- `templates/framework_modern.html` - Base template structure
- `templates/index/index.html` - First migrated page with hero section, cards, etc.