# Bootstrap 5 Migration Reference

This document provides a quick reference for developers working with the BuyerKiosk CSS design system.

## Overview

BuyerKiosk uses **Bootstrap 5.3.3** as its CSS framework with custom brand overrides via CSS custom properties. Bootstrap 3 has been completely removed (hard cutover).

## Key Files

| File | Purpose |
|------|---------|
| `public_html/css/vendor/bootstrap.min.css` | Bootstrap 5.3.3 base (227KB) |
| `public_html/css/admin/tokens.css` | Design tokens (colors, spacing, typography) |
| `public_html/css/admin/admin-theme.css` | Custom component styles |
| `public_html/css/admin/modules/*.css` | Page-specific styles |
| `public_html/css/admin/admin-theme.min.css` | Production bundle |
| `public_html/css/admin/version.txt` | Cache-busting hash |

## Style Guide Reference Page

**URL**: `/admin/style-guide`

A live reference page with all design system components. Use it to:
- See rendered component examples
- Copy HTML code snippets
- Verify your implementations match the design system

## Class Migration Reference

### Components

| Bootstrap 3 | Bootstrap 5 |
|-------------|-------------|
| `.panel` | `.card` |
| `.panel-heading` | `.card-header` |
| `.panel-body` | `.card-body` |
| `.panel-footer` | `.card-footer` |
| `.well` | `.bg-light.border.rounded.p-3` |

### Labels/Badges

| Bootstrap 3 | Bootstrap 5 |
|-------------|-------------|
| `.label` | `.badge` |
| `.label-default` | `.badge.bg-secondary` |
| `.label-primary` | `.badge.bg-primary` |
| `.label-success` | `.badge.bg-success` |
| `.label-warning` | `.badge.bg-warning` |
| `.label-danger` | `.badge.bg-danger` |
| `.label-info` | `.badge.bg-info` |

### Buttons

| Bootstrap 3 | Bootstrap 5 |
|-------------|-------------|
| `.btn-default` | `.btn-secondary` or `.btn-outline-secondary` |

### Layout

| Bootstrap 3 | Bootstrap 5 |
|-------------|-------------|
| `.form-group` | `.mb-3` |
| `.pull-left` | `.float-start` |
| `.pull-right` | `.float-end` |
| `.hidden` | `.d-none` |
| `.show` | `.d-block` |

### Data Attributes

| Bootstrap 3 | Bootstrap 5 |
|-------------|-------------|
| `data-toggle` | `data-bs-toggle` |
| `data-dismiss` | `data-bs-dismiss` |
| `data-target` | `data-bs-target` |
| `data-parent` | `data-bs-parent` |

## CSS Variables

All brand colors and design tokens are defined in `tokens.css`. Use CSS variables instead of hardcoded values:

### Colors

```css
/* Primary (Purple) */
var(--primary-600)      /* Main brand color: #7c3aed */
var(--primary-500)      /* Lighter: #8b5cf6 */
var(--primary-700)      /* Darker: #6d28d9 */

/* Gradients */
var(--gradient-primary) /* linear-gradient(135deg, #667eea 0%, #764ba2 100%) */

/* Semantic */
var(--status-success)   /* Green: #22c55e */
var(--status-warning)   /* Amber: #f59e0b */
var(--status-danger)    /* Rose: #f43f5e */
var(--status-info)      /* Blue: #3b82f6 */

/* Bootstrap overrides (auto-applied to BS5 components) */
var(--bs-primary)       /* #7c3aed */
var(--bs-success)       /* #22c55e */
var(--bs-warning)       /* #f59e0b */
var(--bs-danger)        /* #f43f5e */
```

### Spacing

```css
var(--space-1)   /* 0.25rem (4px) */
var(--space-2)   /* 0.5rem (8px) */
var(--space-3)   /* 0.75rem (12px) */
var(--space-4)   /* 1rem (16px) */
var(--space-6)   /* 1.5rem (24px) */
var(--space-8)   /* 2rem (32px) */
```

### Typography

```css
var(--font-family)       /* Inter with fallbacks */
var(--font-size-sm)      /* 0.875rem (14px) */
var(--font-size-base)    /* 1rem (16px) */
var(--font-size-lg)      /* 1.125rem (18px) */
var(--font-weight-medium)    /* 500 */
var(--font-weight-semibold)  /* 600 */
```

### Shadows & Transitions

```css
var(--shadow-sm)         /* Subtle shadow */
var(--shadow-md)         /* Medium shadow */
var(--shadow-lg)         /* Large shadow */
var(--transition-fast)   /* 150ms ease */
var(--transition-normal) /* 250ms ease */
```

## Common Patterns

### Card with Gradient Header

```html
<div class="card">
    <div class="card-header bg-gradient-primary text-white">
        <h5 class="mb-0">Card Title</h5>
    </div>
    <div class="card-body">
        Content here
    </div>
</div>
```

### Stat Card

```html
<div class="stat-card stat-card--primary">
    <div class="stat-card__icon">
        <i class="fas fa-chart-line"></i>
    </div>
    <div class="stat-card__content">
        <div class="stat-card__value">1,234</div>
        <div class="stat-card__label">Total Sales</div>
    </div>
</div>
```

### Modal (Bootstrap 5)

```html
<button type="button" class="btn btn-primary" data-bs-toggle="modal" data-bs-target="#exampleModal">
    Open Modal
</button>

<div class="modal fade" id="exampleModal" tabindex="-1">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header bg-gradient-primary text-white">
                <h5 class="modal-title">Modal Title</h5>
                <button type="button" class="btn-close btn-close-white" data-bs-dismiss="modal"></button>
            </div>
            <div class="modal-body">
                Content here
            </div>
            <div class="modal-footer">
                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
                <button type="button" class="btn btn-primary">Save</button>
            </div>
        </div>
    </div>
</div>
```

### Masonry Grid

For variable-height cards:

```html
<div class="row" data-masonry='{"percentPosition": true}'>
    <div class="col-md-4 mb-4">
        <div class="card">...</div>
    </div>
    <div class="col-md-4 mb-4">
        <div class="card">...</div>
    </div>
</div>

{% include 'partials/masonry-init.html' %}
```

## Build Commands

```bash
# Development build
php userfrosting/conductor build-css

# Production build (minified + version hash)
php userfrosting/conductor build-css --minify

# Watch mode
php userfrosting/conductor build-css --watch
```

## Icons

Font Awesome 6 is the only icon library. Legacy FA4/FA5 class names are supported via v4-shims.

```html
<!-- FA6 classes -->
<i class="fas fa-check"></i>      <!-- Solid -->
<i class="far fa-check"></i>      <!-- Regular -->
<i class="fab fa-github"></i>     <!-- Brands -->

<!-- Sizing -->
<i class="fas fa-check fa-lg"></i>
<i class="fas fa-check fa-2x"></i>

<!-- Colors (use CSS variables) -->
<i class="fas fa-check" style="color: var(--status-success);"></i>
```

## Troubleshooting

### Modal not opening?
- Check `data-bs-toggle="modal"` (not `data-toggle`)
- Check `data-bs-target="#modalId"` (not `data-target`)
- Ensure Bootstrap 5 JS is loaded

### Dropdown not working?
- Use `data-bs-toggle="dropdown"` (not `data-toggle`)
- Ensure parent has `.dropdown` class

### Colors don't match?
- Use CSS variables: `var(--primary-600)` instead of hardcoded `#7c3aed`
- Check if Bootstrap 5 overrides are loaded (`--bs-primary` etc.)

### After CSS changes?
- Run `php userfrosting/conductor build-css --minify`
- Hard refresh browser (Cmd+Shift+R)