orion/docs/frontend/tailwind-css.md

# Tailwind CSS Build Guide

**Version:** 1.0
**Last Updated:** December 2024
**Audience:** Frontend Developers

---

## Overview

The platform uses [Tailwind CSS](https://tailwindcss.com/) for styling with a **dual-layer architecture**:

1. **Base Layer (CDN):** Tailwind CSS v2.2.19 loaded via CDN with local fallback
2. **Override Layer (npm build):** Custom Windmill Dashboard theme built from Tailwind v1.4.6

This layered approach allows:
- Fast loading via CDN for base utilities
- Custom theme extensions (colors, dark mode, forms) via npm build
- Offline support via local fallback

> **Note:** A migration to Tailwind v3.4 is planned. See [Migration Plan](tailwind-migration-plan.md).

---

## Architecture

### How It Works

```
Browser loads:
1. CDN Tailwind 2.2.19 (base utilities)
   └── Fallback: static/shared/css/tailwind.min.css

2. Custom tailwind.output.css (overrides/extensions)
   └── Built from: static/admin/css/tailwind.css
   └── Contains: Windmill Dashboard theme, custom colors, dark mode
```

### Key Files

| File | Version | Purpose |
|------|---------|---------|
| CDN `tailwindcss@2.2.19` | 2.2.19 | Base Tailwind utilities |
| `static/shared/css/tailwind.min.css` | 2.2.19 | Local fallback for CDN |
| `tailwind.config.js` | 1.4.6 | Custom build configuration |
| `static/admin/css/tailwind.css` | - | Source file with directives |
| `static/admin/css/tailwind.output.css` | 1.4.6 | Compiled custom styles |
| `static/vendor/css/tailwind.output.css` | 1.4.6 | Compiled custom styles |

### Template Loading Order

```html
<!-- 1. Base Tailwind from 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='/static/shared/css/tailwind.min.css';">

<!-- 2. Custom overrides (built via npm) -->
<link rel="stylesheet" href="/static/admin/css/tailwind.output.css" />
```

See [CDN Fallback Strategy](cdn-fallback-strategy.md) for details on offline support.

---

## How Tailwind Purging Works

Tailwind generates thousands of utility classes. To keep the CSS file small, it "purges" (removes) unused classes by scanning your source files.

### Content Paths

The `purge.content` array in `tailwind.config.js` tells Tailwind where to look for class usage:

```javascript
purge: {
  content: [
    'public/**/*.html',
    'app/templates/**/*.html',  // Jinja2 templates
    'static/**/*.js',           // Alpine.js components
  ],
  // ...
}
```

### Safelist

Some classes are used dynamically in Alpine.js expressions and can't be detected by scanning. These must be added to the `safelist`:

```javascript
purge: {
  content: [...],
  safelist: [
    'bg-orange-600',
    'bg-green-600',
    'bg-red-600',
    'hover:bg-orange-700',
    'hover:bg-green-700',
    'hover:bg-red-700',
  ],
}
```

**When to add to safelist:**

- Classes used in Alpine.js `:class` bindings with dynamic conditions
- Classes constructed from variables (e.g., `bg-${color}-500`)
- Classes used only in JavaScript, not in HTML templates

---

## Building Tailwind CSS

### Prerequisites

Install Node.js dependencies (one-time setup):

```bash
npm install
```

Or using Make:

```bash
make npm-install
```

### Development Build

For development, build without purging (includes all classes, larger file):

```bash
# Build admin CSS
npm run tailwind:admin

# Build vendor CSS
npm run tailwind:vendor

# Or using Make
make tailwind-dev
```

### Production Build

For production, build with purging and minification (smaller file):

```bash
npm run build

# Or using Make
make tailwind-build
```

---

## Available npm Scripts

| Script | Command | Description |
|--------|---------|-------------|
| `npm run tailwind:admin` | Build admin CSS (dev) | Fast, includes all classes |
| `npm run tailwind:vendor` | Build vendor CSS (dev) | Fast, includes all classes |
| `npm run build:admin` | Build admin CSS (prod) | Purged and minified |
| `npm run build:vendor` | Build vendor CSS (prod) | Purged and minified |
| `npm run build` | Build all (prod) | Runs both production builds |

---

## Adding New Utility Classes

If you need a class that doesn't exist in the compiled CSS:

### Option 1: Check if it's being purged

The class might exist but is being removed. Add it to the `safelist` in `tailwind.config.js`:

```javascript
safelist: [
  'your-new-class',
  // ...
]
```

### Option 2: Extend the theme

Add custom values to `tailwind.config.js`:

```javascript
theme: {
  extend: {
    colors: {
      'brand': '#123456',
    },
    spacing: {
      '128': '32rem',
    },
  },
}
```

### Option 3: Rebuild CSS

After any config change, rebuild the CSS:

```bash
make tailwind-dev
```

---

## Troubleshooting

### Classes not appearing

1. **Check purge paths** - Ensure your file is in a scanned directory
2. **Check safelist** - Dynamic classes need to be safelisted
3. **Rebuild CSS** - Run `make tailwind-dev` after config changes

### Dynamic classes in Alpine.js

**Problem:** Classes in `:class` bindings may be purged.

```html
<!-- This class might be purged -->
<div :class="isActive ? 'bg-green-600' : 'bg-red-600'">
```

**Solution:** Add to safelist:

```javascript
safelist: ['bg-green-600', 'bg-red-600']
```

### Large CSS file in development

Development builds include all Tailwind classes (~1.2MB). This is normal.

Production builds purge unused classes, resulting in much smaller files (~50-100KB typically).

---

## Configuration Reference

### tailwind.config.js Structure

```javascript
module.exports = {
  // Where to scan for class usage
  purge: {
    content: [...],
    safelist: [...],
  },

  // Theme customization
  theme: {
    // Override defaults
    colors: {...},

    // Extend defaults
    extend: {
      fontFamily: {...},
      maxHeight: {...},
    },
  },

  // Variant configuration (hover, focus, dark mode, etc.)
  variants: {
    backgroundColor: ['hover', 'focus', 'dark', 'dark:hover'],
    textColor: ['hover', 'dark'],
    // ...
  },

  // Plugins
  plugins: [
    require('tailwindcss-multi-theme'),
    require('@tailwindcss/custom-forms'),
  ],
}
```

### Dark Mode

The platform uses `tailwindcss-multi-theme` for dark mode. Dark mode classes use the `.theme-dark` parent selector:

```css
/* Light mode */
.bg-white { ... }

/* Dark mode */
.theme-dark .dark\:bg-gray-800 { ... }
```

---

## Best Practices

1. **Always rebuild after config changes**
   ```bash
   make tailwind-dev
   ```

2. **Add dynamic classes to safelist** to prevent purging

3. **Use production builds for deployment** to minimize file size

4. **Check existing classes first** before adding custom ones - Tailwind likely has what you need

5. **Use consistent color scales** (e.g., `purple-600`, `purple-700`) for hover states

---

## Related Documentation

- [Frontend Overview](overview.md)
- [UI Components](shared/ui-components.md)
- [Tailwind CSS Official Docs](https://tailwindcss.com/docs)