dtourolle/jellytau
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
jellytau/UX-ImplementationGaps.md

7.3 KiB
Raw Blame History

UX Implementation Gaps

This document tracks inconsistencies between the documented UX flows (UXFlows.md) and the actual implementation.

Last Updated: 2026-01-03

Recently Resolved ✅

1. Route Structure Mismatch ✅ RESOLVED

Was Documented:

  • Login screen at /
  • Home/Library landing at /library (after login)

Actual Implementation:

  • Login screen at /login
  • Home page with carousels at /
  • Library selector at /library

Resolution: Updated UXFlows.md Sections 1.1, 2.1, 2.2, 8.2 to reflect actual routes

3. Audio Player Back Button Navigation ✅ RESOLVED

Issue:

  • Audio player close button simply closed the modal without respecting browser history
  • Users expected back button to return to previous page (e.g., album view)

Resolution:

  • Updated AudioPlayer onClose handler to call window.history.back() (library/+layout.svelte:212-215)
  • Back button now returns user to the page they were on before opening full player
  • Updated UXFlows.md Section 3.3 to document browser history navigation

Impact: Better UX - natural back button behavior matches user expectations

4. Video Player Touch Gestures ✅ RESOLVED

Was Documented:

  • Double tap left: Rewind 10 seconds
  • Double tap right: Forward 10 seconds
  • Swipe up/down: Adjust brightness (left) or volume (right)

Implementation:

  • ✅ Double-tap detection on left/right sides of screen (VideoPlayer.svelte:228-319)
  • ✅ Animated visual feedback showing "-10" or "+10" with fade-out animation
  • ✅ Swipe gesture detection for vertical swipes (>50px minimum)
  • ✅ Left side swipe: Brightness control (0.3-1.7x) with CSS filter
  • ✅ Right side swipe: Volume control (0-100%) with real-time adjustment
  • ✅ Visual indicators showing current brightness/volume level during swipe
  • ✅ Updated UXFlows.md Section 4.2 to document all gestures

Impact: Excellent mobile video UX - touch-optimized controls match YouTube/Netflix patterns

Remaining Issues

Critical Issues

None! All critical UX issues have been resolved. 🎉

Low Priority Issues

1. MiniPlayer Shows More Controls Than Documented

Documented:

  • Shows: artwork, title, artist, play/pause, next, favorite

Actual Implementation:

  • Shows: artwork, title, artist, play/pause, next, previous, shuffle, repeat, volume (desktop), cast button, favorite (desktop)
  • Much richer control set than documented

Impact: Low - This is actually better than documented

Fix Required: Update UXFlows.md Section 3.1 to document full control set

2. Search Results Display Simplified

Documented (Section 6.1):

  • Results grouped by type: Songs, Albums, Artists, Movies, Episodes
  • "See all (23)" expandable sections

Actual Implementation:

  • Search page uses LibraryGrid component
  • No visual grouping by type shown in code
  • Simplified single-list results

Impact: Low - Functional but less organized than documented

Fix Required:

  • Option A: Implement grouped results display
  • Option B: Update documentation to match simplified implementation

Undocumented Features

3. Sessions/Remote Control Feature

Not in UXFlows.md:

  • Route exists: /sessions
  • Appears to be for remote session control
  • Cast button visible in MiniPlayer

Impact: None - Feature exists but isn't documented

Fix Required: Document sessions feature in UXFlows.md (Section 8.2 exists in SoftwareArchitecture.md but not in UX flows)

4. URL Query Parameters for Queue Context

Not in UXFlows.md:

  • Uses ?queue=parent:{id}&shuffle=true in URLs
  • Enables queue restoration and context tracking

Impact: None - Implementation detail

Fix Required: Optional - add technical note in UXFlows.md about queue URL params

Consistent Implementations ✅

These areas match the documentation exactly:

  • ✅ Resume Dialog - Correctly implements 30s/90% threshold (player/[id]/+page.svelte:84-86)
  • ✅ Audio Playback - Uses player_play_queue command as documented
  • ✅ MiniPlayer Hiding - Correctly hides for video content
  • ✅ Keyboard Shortcuts - Video player keyboard controls work as documented
  • ✅ Music Library Structure - Category pages match documentation

Recommendations by Priority

High Priority

  1. Update UXFlows.md Route Structure ✅ COMPLETED

    • ✅ Corrected login route to /login
    • ✅ Clarified / is home page, /library is library selector
    • ✅ Updated Sections 1.1, 2.1, 2.2, 7.2, 8.1, 8.2

  2. Add Downloads Navigation ✅ COMPLETED

    • ✅ Added Downloads link to header navigation (desktop)
    • ✅ Added Downloads icon button to header (all screen sizes)
    • ✅ Updated UXFlows.md to document navigation paths

Medium Priority

  1. Add Settings Navigation Link ✅ COMPLETED

    • ✅ Added Settings link to desktop header navigation
    • ✅ Added Settings to mobile overflow menu
    • ✅ Updated UXFlows.md Section 8.1

  2. Implement Video Player Touch Gestures ✅ COMPLETED

    • ✅ Implemented double-tap detection (left/right sides)
    • ✅ Implemented swipe gestures (brightness + volume control)
    • ✅ Added visual feedback animations
    • ✅ Updated UXFlows.md Section 4.2

Low Priority

  1. Document MiniPlayer Full Feature Set (#4)

    • Update Section 3.1 to show all controls
    • Document desktop vs mobile differences

  2. Document Sessions Feature (#7)

    • Add UX flow for remote session selection
    • Explain cast button behavior
    • Link to architecture documentation

  3. Enhance Search Results Display (#5)

    • Consider implementing grouped results as documented
    • Or update docs to match current implementation

Quick Fix Checklist

For immediate documentation updates:

  • Fix login route in UXFlows.md (Section 2.1): / → /login ✅
  • Fix home route in UXFlows.md (Section 2.1): /library → / ✅
  • Document actual navigation structure (Section 1.1) ✅
  • Update Downloads navigation (Section 7.2) ✅
  • Update Settings navigation (Section 8.1) ✅
  • Update logout flow (Section 8.2) ✅
  • Update video controls documentation (Section 4.2) to match keyboard implementation
  • Document MiniPlayer cast button (Section 3.1)
  • Add Sessions feature UX flow (new section)

For code implementation:

  • Add Downloads link to header navigation (desktop) ✅
  • Add Downloads icon button to header (all screen sizes) ✅
  • Add Settings link to header navigation ✅
  • Implement mobile overflow menu (Android-style) ✅
  • Fix audio player back button to use browser history ✅
  • (Optional) Implement video player touch gestures
  • (Optional) Implement grouped search results

Notes

  • The actual implementation is generally more feature-rich than documented (MiniPlayer controls, keyboard shortcuts)
  • Main gaps are in mobile navigation accessibility (missing More tab)
  • Most core functionality matches or exceeds documentation
  • Video player touch gestures are the only missing feature that was explicitly documented