thrillwiki_django_no_react/docs/ux/README.md

# ThrillWiki UX Documentation

This directory contains comprehensive UX documentation for the ThrillWiki Django application.

## Overview

ThrillWiki uses a modern stack combining:
- **Django Templates** for server-side rendering
- **HTMX** for seamless AJAX interactions
- **Alpine.js** for client-side state management
- **Tailwind CSS** for styling

## Documentation Index

### Core Patterns

- [Interaction Patterns](./interaction-patterns.md) - Alpine.js stores, HTMX patterns, event handling
- [HTMX Conventions](./htmx-conventions.md) - Standardized HTMX usage patterns
- [CTA Guidelines](./cta-guidelines.md) - Button placement and action patterns

### Components

- [Component Library](./component-library.md) - Catalog of all reusable components
- [Navigation Components](../backend/templates/components/navigation/README.md)
- [Form Components](../backend/templates/forms/README.md)
- [HTMX Components](../backend/templates/htmx/components/README.md)

### Developer Resources

- [Developer Guidelines](./developer-guidelines.md) - Best practices for UX development
- [Migration Guide](./migration-guide.md) - Updating existing templates

## Quick Start

### Using Breadcrumbs

```python
# In your view
from apps.core.utils.breadcrumbs import build_breadcrumb

def park_detail(request, slug):
    park = get_object_or_404(Park, slug=slug)
    request.breadcrumbs = [
        build_breadcrumb('Home', '/', icon='fas fa-home'),
        build_breadcrumb('Parks', reverse('parks:list')),
        build_breadcrumb(park.name, is_current=True),
    ]
    return render(request, 'parks/detail.html', {'park': park})
```

### Using Toast Notifications

```javascript
// From JavaScript
Alpine.store('toast').success('Item saved successfully!');
Alpine.store('toast').error('Something went wrong');

// With action
Alpine.store('toast').success('Item deleted', 5000, {
    action: { label: 'Undo', onClick: () => undoDelete() }
});
```

```python
# From Django view
from apps.core.htmx_utils import htmx_success

def save_item(request):
    # ... save logic ...
    return htmx_success('Item saved successfully!')
```

### Using Skeleton Screens

```django
{# Show skeleton while loading #}
<div id="parks-list"
     hx-get="/parks/"
     hx-trigger="load"
     hx-swap="innerHTML">
    {% include 'components/skeletons/card_grid_skeleton.html' with cards=6 %}
</div>
```

### Using Page Headers

```django
{% include 'components/layout/page_header.html' with
    title='Parks'
    subtitle='Browse theme parks worldwide'
    icon='fas fa-map-marker-alt'
%}
```

### Using Modals

```django
<div x-data="{ showModal: false }">
    <button @click="showModal = true" class="btn btn-primary">Open Modal</button>

    {% include 'components/modals/modal_base.html' with
        modal_id='my-modal'
        title='Modal Title'
        show_var='showModal'
    %}
</div>
```

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                      Django Templates                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Pages     │  │  Partials   │  │     Components      │ │
│  │             │  │             │  │                     │ │
│  │ - parks/    │  │ - _list.html│  │ - navigation/       │ │
│  │ - rides/    │  │ - _form.html│  │ - forms/            │ │
│  │ - auth/     │  │ - _card.html│  │ - modals/           │ │
│  └─────────────┘  └─────────────┘  │ - skeletons/        │ │
│                                     │ - ui/               │ │
│                                     └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Client-Side Layer                         │
│  ┌─────────────────────┐  ┌────────────────────────────┐   │
│  │       HTMX          │  │        Alpine.js           │   │
│  │                     │  │                            │   │
│  │ - Partial updates   │  │ - UI state management     │   │
│  │ - Form validation   │  │ - Toast notifications     │   │
│  │ - Infinite scroll   │  │ - Search components       │   │
│  │ - Modal loading     │  │ - Theme switching         │   │
│  └─────────────────────┘  └────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

## Key Concepts

### 1. Progressive Enhancement

All interactions work without JavaScript, with HTMX and Alpine.js enhancing the experience.

### 2. Consistent Feedback

Every user action provides immediate feedback:
- Loading states during HTMX requests
- Toast notifications for success/error
- Inline validation for forms

### 3. Accessibility First

All components include:
- Proper ARIA attributes
- Keyboard navigation
- Screen reader support
- Focus management

### 4. Responsive Design

Components adapt to screen size:
- Mobile-first approach
- Stacked layouts on small screens
- Collapsed navigation on mobile