thrillwiki_django_no_react/docs/design-system/MIGRATION.md

# Design System Migration Guide

This guide helps migrate from the legacy frontend system to the unified design system.

## Overview

The ThrillWiki frontend was consolidated from two parallel systems:
- **Legacy System** (`/backend/templates/`, `/backend/static/css/`) - HSL-based variables, Font Awesome icons
- **Modern System** (`/templates/`, `/static/css/`) - RGB hex-based design tokens, SVG icons

The unified system uses `design-tokens.css` as the single source of truth.

## CSS Migration

### Color Variables

Replace HSL-based variables with design tokens:

```css
/* Before (legacy) */
background-color: hsl(var(--primary));
color: hsl(var(--primary-foreground));

/* After (design tokens) */
background-color: var(--color-primary);
color: var(--color-primary-foreground);
```

### Common Replacements

| Legacy | Design Token |
|--------|--------------|
| `hsl(var(--primary))` | `var(--color-primary)` |
| `hsl(var(--secondary))` | `var(--color-secondary)` |
| `hsl(var(--background))` | `var(--color-background)` |
| `hsl(var(--foreground))` | `var(--color-foreground)` |
| `hsl(var(--muted))` | `var(--color-muted)` |
| `hsl(var(--accent))` | `var(--color-accent)` |
| `hsl(var(--destructive))` | `var(--color-destructive)` |
| `hsl(var(--border))` | `var(--color-border)` |
| `hsl(var(--card))` | `var(--color-card)` |

### Font Variables

```css
/* Before */
font-family: var(--font-sans);

/* After */
font-family: var(--font-family-sans);
```

### Shadow Variables

```css
/* Before */
box-shadow: var(--shadow);

/* After */
box-shadow: var(--shadow-base);
```

## Icon Migration

Replace Font Awesome icons with the SVG icon component:

```html
<!-- Before (Font Awesome) -->
<i class="fa fa-search"></i>
<i class="fas fa-user"></i>
<i class="far fa-heart"></i>

<!-- After (SVG Icon Component) -->
{% include "components/ui/icon.html" with name="search" %}
{% include "components/ui/icon.html" with name="user" %}
{% include "components/ui/icon.html" with name="heart" %}
```

### Icon Name Mapping

| Font Awesome | SVG Icon |
|--------------|----------|
| `fa-search` | `search` |
| `fa-user` | `user` |
| `fa-users` | `users` |
| `fa-cog` | `settings` |
| `fa-heart` | `heart` |
| `fa-star` | `star` |
| `fa-home` | `home` |
| `fa-edit` | `edit` |
| `fa-trash` | `trash` |
| `fa-copy` | `copy` |
| `fa-external-link` | `external-link` |
| `fa-chevron-down` | `chevron-down` |
| `fa-chevron-up` | `chevron-up` |
| `fa-chevron-left` | `chevron-left` |
| `fa-chevron-right` | `chevron-right` |
| `fa-check` | `check` |
| `fa-times` | `close` |
| `fa-plus` | `plus` |
| `fa-minus` | `minus` |
| `fa-bars` | `menu` |

### Icon Sizes

```html
<!-- Before -->
<i class="fa fa-search fa-sm"></i>
<i class="fa fa-search fa-lg"></i>
<i class="fa fa-search fa-2x"></i>

<!-- After -->
{% include "components/ui/icon.html" with name="search" size="sm" %}
{% include "components/ui/icon.html" with name="search" size="lg" %}
{% include "components/ui/icon.html" with name="search" size="xl" %}
```

## Button Migration

### Basic Buttons

```html
<!-- Before -->
<button class="btn btn-primary">Click Me</button>
<button class="btn btn-secondary">Click Me</button>
<button class="btn btn-danger">Delete</button>
<button class="btn btn-outline">Outline</button>

<!-- After -->
{% include "components/ui/button.html" with text="Click Me" variant="default" %}
{% include "components/ui/button.html" with text="Click Me" variant="secondary" %}
{% include "components/ui/button.html" with text="Delete" variant="destructive" %}
{% include "components/ui/button.html" with text="Outline" variant="outline" %}
```

### Buttons with Icons

```html
<!-- Before -->
<button class="btn btn-primary">
    <i class="fa fa-search mr-2"></i>
    Search
</button>

<!-- After -->
{% include "components/ui/button.html" with text="Search" icon="search" %}
```

### Link Buttons

```html
<!-- Before -->
<a href="/url" class="btn btn-primary">Go</a>

<!-- After -->
{% include "components/ui/button.html" with text="Go" href="/url" %}
```

## Form Input Migration

```html
<!-- Before -->
<div class="form-group">
    <label for="email">Email</label>
    <input type="email" id="email" name="email" class="form-control" placeholder="Enter email">
    <small class="form-text text-muted">We'll never share your email.</small>
</div>

<!-- After -->
{% include "components/ui/input.html" with
    name="email"
    label="Email"
    type="email"
    placeholder="Enter email"
    hint="We'll never share your email."
%}
```

## Card Migration

```html
<!-- Before -->
<div class="card">
    <div class="card-header">
        <h3 class="card-title">Title</h3>
    </div>
    <div class="card-body">
        <p>Content here</p>
    </div>
    <div class="card-footer">
        <button class="btn">Action</button>
    </div>
</div>

<!-- After -->
{% include "components/ui/card.html" with
    title="Title"
    body_content="<p>Content here</p>"
    footer_content="<button class='btn'>Action</button>"
%}
```

## Modal Migration

```html
<!-- Before -->
<div class="modal" id="myModal">
    <div class="modal-dialog">
        <div class="modal-content">
            <div class="modal-header">
                <h5 class="modal-title">Title</h5>
                <button class="close">&times;</button>
            </div>
            <div class="modal-body">Content</div>
            <div class="modal-footer">
                <button class="btn">Close</button>
            </div>
        </div>
    </div>
</div>

<!-- After -->
{% include "components/ui/dialog.html" with
    id="myModal"
    title="Title"
    content="Content"
    footer="<button class='btn'>Close</button>"
%}
```

## Alpine.js Migration

### Store Definitions

Move inline store definitions to `stores/index.js`:

```javascript
// Before (inline in template)
<script>
document.addEventListener('alpine:init', () => {
    Alpine.store('theme', {
        isDark: false,
        toggle() { this.isDark = !this.isDark; }
    });
});
</script>

// After (use centralized store)
// Store is already defined in stores/index.js
// Access via $store.theme.toggle()
```

### Component Definitions

Move inline component definitions to `alpine-components.js`:

```javascript
// Before (inline in template)
<div x-data="{ open: false }">
    <button @click="open = !open">Toggle</button>
    <div x-show="open">Content</div>
</div>

// After (use registered component)
<div x-data="dropdown()">
    <button @click="toggle()">Toggle</button>
    <div x-show="open">Content</div>
</div>
```

## Alert/Toast Migration

```html
<!-- Before -->
<div class="alert alert-success">
    <strong>Success!</strong> Your action was completed.
</div>

<!-- After -->
<div class="alert alert-success" role="alert">
    <div class="alert-title">Success!</div>
    <div class="alert-description">Your action was completed.</div>
</div>

<!-- Or use toast store for dynamic notifications -->
<script>
    Alpine.store('toast').success('Your action was completed.');
</script>
```

## Responsive Classes Migration

```html
<!-- Before -->
<div class="d-none d-md-block">Hidden on mobile</div>
<div class="d-md-none">Only on mobile</div>
<div class="row">
    <div class="col-12 col-md-6">...</div>
</div>

<!-- After -->
<div class="hidden-mobile">Hidden on mobile</div>
<div class="show-mobile">Only on mobile</div>
<div class="grid-responsive-2">
    <div>...</div>
    <div>...</div>
</div>
```

## Checklist

Use this checklist when migrating a template:

- [ ] Replace HSL color variables with design tokens
- [ ] Replace Font Awesome icons with SVG icon component
- [ ] Update button markup to use button component
- [ ] Update form inputs to use input component
- [ ] Update cards to use card component
- [ ] Update modals to use dialog component
- [ ] Remove inline Alpine.js store definitions
- [ ] Update responsive classes
- [ ] Test dark mode appearance
- [ ] Test focus states for accessibility
- [ ] Test on mobile viewport

## Testing Migration

After migrating, visit `/design-system-test/` to compare your migrated components against the reference implementation.

## Getting Help

If you encounter issues during migration:

1. Check the design system README for component documentation
2. Review `design-tokens.css` for available tokens
3. Inspect the design system test page for examples