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 - Alpine.js stores, HTMX patterns, event handling
• HTMX Conventions - Standardized HTMX usage patterns
• CTA Guidelines - Button placement and action patterns

Components

• Component Library - Catalog of all reusable components
• Navigation Components
• Form Components
• HTMX Components

Developer Resources

• Developer Guidelines - Best practices for UX development
• Migration Guide - Updating existing templates

Quick Start

Using Breadcrumbs

# 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

// 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() }
});

# 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

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

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

Using Modals

<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