Add standardized HTMX conventions, interaction patterns, and migration guide for ThrillWiki UX

2025-12-23 21:31:10 -05:00 · 2025-12-22 16:56:27 -05:00
parent 2e35f8c5d9
commit ae31e889d7
144 changed files with 25792 additions and 4440 deletions
--- a/docs/ux/README.md
+++ b/docs/ux/README.md
@@ -0,0 +1,165 @@
+# 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