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.

Layout Architecture

Paper-over-Background Design

The modern framework uses a "paper hovering over background" design:

• Background: bg-base-300 (slightly darker gray)
• Content Area: bg-base-100 (white/light) with shadow and rounded corners on medium+ screens
• Responsive: Full width on mobile, centered with visible background on larger screens

Two Layout Modes

1. Standard Paper Layout (default)

{% block content %}
    <!-- Your content here with NO enforced styles -->
    <!-- Automatically wrapped in paper container -->
{% endblock content %}

2. Full-Width Layout (for landing pages, special layouts)

{% block main_content %}
    <!-- Complete control over layout -->
    <!-- Overrides paper container entirely -->
{% endblock main_content %}

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

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

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

Step 2: Remove Bootstrap wrappers

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

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

<div class="modal fade" id="myModal">
    <div class="modal-dialog">
        <div class="modal-content">...</div>
    </div>
</div>

DaisyUI Modal:

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

# 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
• DaisyUI v5 Docs
• DaisyUI Components
• DaisyUI Themes
• Strangler Fig Pattern

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.