WebUI Navigation Refactor: A Progressive Disclosure Approach

Nov 17, 2025 by Alex Johnson 61 views

🎯 Summary

This article discusses the refactoring of the WebUI navigation from a single /webui/gallery page to a progressive disclosure pattern featuring four distinct pages. This redesign introduces smooth morphing animations, a clear information hierarchy, and a mobile-first responsive design with bottom sheets and swipe gestures. The primary goal is to separate concerns—sessions versus gallery—and provide a more intuitive and user-friendly navigation experience.

📋 Problem Statement

The current /webui/gallery page presents several challenges by combining multiple elements into one view. These challenges include:

Sessions sidebar (left column)
Image gallery (main area)
Filters for both sessions and images
Lack of clear separation between "exploring a session" and "browsing liked images"

Key pain points resulting from this design include cognitive overload due to the excessive information presented at once, an unclear navigation hierarchy, a subpar mobile experience due to cramped columns, and the absence of progressive disclosure, meaning there is no preview before diving into a full gallery.

In detail, the cognitive overload is a significant issue. Users are bombarded with information from multiple sources, making it difficult to focus on the task at hand. The lack of a clear navigation hierarchy further complicates matters, as users struggle to understand the relationship between different elements and how to navigate effectively. The mobile experience suffers from cramped columns, making it challenging to view and interact with content on smaller screens. Finally, the absence of progressive disclosure means users must commit to a full gallery view without a preview, potentially wasting time if the content is not relevant. Addressing these pain points is crucial for creating a more efficient and enjoyable user experience, and this refactoring aims to do just that.

🎨 Proposed Solution

To address these issues, a four-level progressive disclosure navigation pattern will be implemented. This approach adds information incrementally while maintaining access to previous levels, ensuring users are not overwhelmed and can easily navigate the system.

Page 1: `/webui/sessions` - Sessions Grid

The initial page presents a full-screen grid displaying all sessions (1163 items). It includes search and filter options specifically for sessions. Clicking on a session will navigate the user to Page 2, providing a seamless transition to more detailed information. The grid layout offers a visually appealing and efficient way to scan available sessions, while the search and filter options allow users to quickly locate specific sessions of interest. This design ensures that users are not overwhelmed with information upfront and can focus on selecting a session to explore further. The emphasis on session discovery is crucial for users who are looking for specific content or wish to browse through their history.

Page 2: `/webui/sessions/:name` - Session Details

This page offers a more detailed view of the selected session, with a layout comprising of two main sections. The left column displays a compact list of sessions, morphed from the grid view of Page 1, providing easy access to other sessions. The right column presents session details, including statistics, metadata, and tags. Additionally, a preview gallery showcases the first 12 images in a grid format. A "View Gallery" button navigates the user to Page 3, allowing for a deeper dive into the session's images. This page strikes a balance between providing detailed information and maintaining an overview of the session. The compact session list on the left ensures users can quickly switch between sessions without losing context, while the session details on the right offer a comprehensive understanding of the selected session. The preview gallery serves as a teaser, encouraging users to explore the full gallery if they find the initial images appealing. This level of detail is essential for users who need specific information about a session before diving into the images.

Page 3: `/webui/sessions/:name/images` - Full Gallery

Page 3 is dedicated to displaying the full image gallery of the selected session. The layout consists of three sections: the left column presents a mini mode of the sessions list, further reducing its footprint. The middle column displays a shrunk version of the session details, showing only key information. The main area features the full image gallery with lazy loading to optimize performance. A toggleable right drawer houses filters, allowing users to refine their view of the gallery. This page is designed for users who want to immerse themselves in the images of a session while still having access to key session details and filter options. The lazy loading of images ensures that the gallery remains responsive, even with a large number of images. The toggleable filter drawer allows users to focus on specific images based on their criteria. The full gallery view is a crucial step for users who are looking for specific images within a session.

Page 4: `/webui/sessions/:name/images/:imageId` - Image Viewer

This page presents a fullscreen overlay pop-in with an image viewer. Keyboard navigation (←→ for images, Esc to close) is supported for easy browsing. An image metadata panel provides additional information about the image. Users can navigate between images, and the URL updates dynamically to reflect the current image. This page provides an immersive experience for viewing individual images, with a focus on detail and ease of navigation. The fullscreen overlay ensures that the image is the center of attention, while the keyboard navigation allows for quick and efficient browsing. The image metadata panel offers valuable context for each image, and the dynamic URL updates enable easy sharing and deep linking. The image viewer is the final step in the progressive disclosure, allowing users to focus on individual images with all the necessary details.

Refocused Gallery: `/webui/gallery`

This gallery is specifically designed to showcase cross-session liked images without the distraction of a sessions sidebar. It is divided into two sections: "Showcase" (favorites) and "Last 20 images." Global filters (tags, date range, liked/disliked) are available to further refine the view. This gallery is intended for users who want to quickly access their favorite images or the most recent ones, without being tied to a specific session. The absence of the sessions sidebar allows for a cleaner and more focused browsing experience. The global filters provide powerful tools for narrowing down the images based on specific criteria. This refocused gallery offers a streamlined way to access liked images across all sessions.

✨ Key Features

Progressive Disclosure

Each page reveals one additional level of detail.
Clear left-to-right navigation hierarchy.
Breadcrumb navigation at all levels.
Click parent columns to navigate back.

Progressive disclosure is a core principle of this redesign. By revealing information in stages, users are less likely to feel overwhelmed and can focus on the details that matter most to them. The clear left-to-right navigation hierarchy provides a consistent mental model for users to follow, making it easy to understand where they are in the system and how to get to other areas. Breadcrumb navigation at all levels further enhances this clarity, allowing users to quickly jump back to previous levels. The ability to click parent columns to navigate back offers an intuitive way to move up the hierarchy, reinforcing the progressive nature of the design. This feature ensures that users always have a clear path through the interface and can easily access the information they need.

Smooth Animations

Grid → List morph: Cards scale and slide left (400ms).
Slide transitions: Pages slide in from right (forward) or left (backward).
Fade transitions: Image viewer overlay fades in.
GPU-accelerated only: transform + opacity (60fps on all devices).

Animations play a crucial role in providing a seamless and engaging user experience. The smooth transitions between pages help maintain context and prevent jarring shifts in the interface. The grid-to-list morph, slide transitions, and fade transitions all contribute to a sense of continuity and fluidity. By using GPU-accelerated animations, the design ensures optimal performance across a wide range of devices, maintaining a consistent 60fps for smooth interactions. These animations enhance the user's perception of the system's responsiveness and make the navigation feel more natural and intuitive.

Mobile-First Responsive

Desktop: Multi-column layout with animations.
Mobile: Separate pages (no columns), bottom sheets for filters.
Touch targets: ≥ 48×48px (Material Design guideline).
Swipe gestures: Right edge swipe to go back, swipe in viewer to change images.

A mobile-first approach ensures that the design is optimized for smaller screens, providing a consistent experience across devices. On desktop, the multi-column layout leverages the available screen space, while animations add visual interest. On mobile, the design adapts by using separate pages without columns, simplifying the layout for smaller screens. Bottom sheets are used for filters, allowing for a clean and uncluttered interface. Touch targets are sized according to Material Design guidelines (≥ 48×48px) to ensure ease of interaction on touchscreens. Swipe gestures provide intuitive navigation, such as swiping from the right edge to go back or swiping within the image viewer to change images. This responsiveness is crucial for accommodating users on various devices and screen sizes.

Keyboard Shortcuts

← / → : Navigate images (Page 4).
Esc : Go back / close viewer.
/ : Focus search.
f : Toggle filters drawer.

Keyboard shortcuts enhance efficiency and accessibility for power users. The ability to navigate images with the arrow keys, close the viewer with the Esc key, focus the search input with the / key, and toggle the filters drawer with the f key provides quick and convenient alternatives to mouse-based interactions. These shortcuts cater to users who prefer keyboard navigation or need assistive technology support.

Accessibility

WCAG AA compliant (Vuetify 3 defaults).
Focus management (trap focus in viewer, restore on close).
ARIA labels on all interactive elements.
Screen reader support (NVDA, VoiceOver tested).

Accessibility is a critical consideration in this redesign. Adherence to WCAG AA standards ensures that the interface is usable by people with disabilities. Focus management prevents keyboard traps and ensures that interactive elements are easily accessible. ARIA labels provide semantic information to screen readers, making the content accessible to visually impaired users. Testing with NVDA and VoiceOver ensures compatibility with popular screen readers. Accessibility features are integral to creating an inclusive and user-friendly experience for everyone.

📐 Architecture

Design & TDD Documentation

UX Design Spec: .claude/20251117_195500-webui-navigation-redesign.md
TDD Plan: .claude/20251117_navigation-refactor-tdd-plan.md

The design and development process is supported by comprehensive documentation. The UX Design Spec outlines the visual and interaction design of the new navigation system. The TDD Plan details the Test-Driven Development approach, ensuring that tests are written before code implementation. These documents serve as a roadmap for the development team, ensuring consistency and quality throughout the process.

Component Tree

App.vue
├── ProgressiveBreadcrumb.vue (persistent)
└── Router View (transition-group)
    ├── Page 1: Sessions.vue (Grid)
    │   └── SessionCard.vue (×N, grid mode)
    ├── Page 2: SessionDetail.vue (List + Details)
    │   ├── SessionList.vue (compact mode)
    │   └── SessionPreview.vue (12 images)
    ├── Page 3: SessionImages.vue (Gallery)
    │   ├── SessionList.vue (mini mode)
    │   ├── ImageGallery.vue (full grid)
    │   └── FilterDrawer.vue (right drawer)
    ├── Page 4: ImageDetail.vue (Popin)
    │   └── ImageViewer.vue (fullscreen overlay)
    └── Gallery.vue (Liked images only)
        └── ImageGallery.vue (cross-session)

The component tree provides a clear overview of the application's structure. It illustrates the hierarchy of components and their relationships, making it easier to understand the application's architecture. The use of Vue.js components promotes reusability and maintainability. This structured approach simplifies development and ensures a well-organized codebase.

New Components

SessionList.vue - Compact/mini list modes
SessionPreview.vue - Preview grid (N images)
ImageGallery.vue - Reusable lazy-loaded gallery
ImageViewer.vue - Fullscreen image popin
ProgressiveBreadcrumb.vue - Route-depth-based breadcrumb

Several new components are introduced to support the new navigation system. SessionList.vue handles the display of sessions in compact and mini list modes. SessionPreview.vue provides a preview grid of images. ImageGallery.vue is a reusable component for displaying lazy-loaded image galleries. ImageViewer.vue implements the fullscreen image pop-in. ProgressiveBreadcrumb.vue displays a breadcrumb navigation based on the route depth. These components are designed to be modular and reusable, enhancing the application's flexibility and maintainability.

New Composables

useKeyboardNav.js - Keyboard shortcut management
usePageTransition.js - Route depth → transition direction
useResponsive.js - Breakpoint detection (mobile/tablet/desktop)
useImageLoader.js - IntersectionObserver for lazy loading

New composables are introduced to encapsulate reusable logic. useKeyboardNav.js manages keyboard shortcuts. usePageTransition.js determines the transition direction based on route depth. useResponsive.js handles breakpoint detection for responsive design. useImageLoader.js implements lazy loading using IntersectionObserver. Composables promote code reuse and make it easier to manage complex logic.

Router Configuration

Routes with meta: { depth: 1-4, transition: 'slide-left' | 'fade', isModal: true }
Navigation guards detect forward/backward based on depth
Backward compatibility redirects for old routes

The router configuration defines the application's navigation structure. Routes include meta properties such as depth, transition, and isModal. Navigation guards detect forward and backward navigation based on depth. Backward compatibility redirects ensure that old routes still function correctly. Proper router configuration is essential for a smooth and predictable navigation experience.

✅ Acceptance Criteria

The acceptance criteria define the standards that must be met for the refactor to be considered successful. These criteria cover user flows, performance, testing, accessibility, and mobile usability, ensuring a comprehensive evaluation of the new navigation system.

User Flows (Given/When/Then)

[ ] As a user, when I navigate to /webui/sessions, I see a full-screen grid of all sessions
[ ] As a user, when I click a session card, the grid morphs into a compact list (left column) and session details appear (right column)
[ ] As a user, when I click "View Gallery" in session details, I see all session images in a full gallery with filters
[ ] As a user, when I click an image in the gallery, a fullscreen viewer opens with keyboard navigation (←→ Esc)
[ ] As a user on mobile, I see separate pages with back buttons (no multi-column layout)
[ ] As a user on mobile, filters appear as a bottom sheet (swipe up to open)
[ ] As a user, I can navigate back by clicking parent columns (Sessions, Details) or using browser back button
[ ] As a user, when I share an image URL, the recipient sees the same image in the viewer (deep linking works)

These user flows ensure that the key interactions within the application are intuitive and seamless. They cover the main navigation paths and actions that users will take, providing a clear set of requirements for the refactor.

Performance

[ ] All animations complete in < 400ms
[ ] 60fps on low-end devices (GPU-accelerated only)
[ ] Lighthouse Performance score > 90
[ ] First Contentful Paint (FCP) < 1.5s
[ ] Largest Contentful Paint (LCP) < 2.5s
[ ] Cumulative Layout Shift (CLS) < 0.1

Performance metrics are crucial for ensuring a smooth and responsive user experience. These criteria set specific targets for animation speed, frame rate, and various Lighthouse performance scores, ensuring that the refactored navigation system performs optimally.

Testing

[ ] Unit test coverage > 95% (components, composables, utils)
[ ] Integration test coverage > 85% (routing, transitions, filters)
[ ] E2E test coverage > 80% (user flows, mobile gestures)
[ ] Overall test coverage > 90%

Testing is a critical aspect of the refactor, and these criteria set high standards for test coverage across different types of tests, including unit, integration, and end-to-end tests. This ensures that the new navigation system is thoroughly tested and free of defects.

Accessibility

[ ] Lighthouse Accessibility score = 100
[ ] WCAG AA compliance (color contrast, keyboard nav, ARIA labels)
[ ] Screen reader support (all content accessible)
[ ] Focus management (visible focus, no keyboard traps)

Accessibility criteria ensure that the refactored navigation system is usable by people with disabilities. These criteria cover various aspects of accessibility, including Lighthouse scores, WCAG compliance, screen reader support, and focus management.

Mobile Usability

[ ] Touch targets ≥ 48×48px
[ ] Bottom sheets open/close smoothly (< 200ms)
[ ] Swipe gestures work reliably (right edge swipe to go back)
[ ] No horizontal scroll on mobile

Mobile usability criteria ensure that the refactored navigation system provides a smooth and intuitive experience on mobile devices. These criteria cover touch target sizes, bottom sheet animations, swipe gestures, and the absence of horizontal scrolling.

🧪 Testing Strategy

This refactor follows a Test-Driven Development (TDD) approach:

Write tests FIRST before implementing components
Red → Green → Refactor cycle for all components
Incremental rollout (7 phases) to avoid breaking existing functionality

The TDD approach ensures that tests are written before the implementation, driving the development process and ensuring high-quality code. The incremental rollout minimizes the risk of breaking existing functionality by introducing changes in phases.

Test Structure

/tests/
├── unit/
│   ├── components/ (SessionList, ImageGallery, ImageViewer, etc.)
│   ├── composables/ (useKeyboardNav, useResponsive, useImageLoader, etc.)
│   ├── stores/ (sessions, images)
│   └── utils/ (transitions.js)
├── integration/
│   ├── SessionsFlow.spec.js (Page 1 ↔ Page 2 navigation)
│   ├── NavigationFlow.spec.js (Complete Page 1 → 2 → 3 → 4 flow)
│   ├── GalleryFlow.spec.js (Filters + gallery)
│   └── KeyboardShortcuts.spec.js (←→ Esc / f)
└── e2e/ (Playwright)
    ├── sessions-navigation.spec.js (Full user flow)
    ├── mobile-navigation.spec.js (Bottom sheets, gestures)
    ├── image-viewer.spec.js (Keyboard nav, sharing)
    └── filters.spec.js (URL persistence, deep linking)

The test structure outlines the organization of tests across unit, integration, and end-to-end levels. This structured approach ensures that all aspects of the navigation system are thoroughly tested.

Testing Tools

Vitest + @vue/test-utils (unit & integration)
Playwright (E2E, mobile emulation, a11y auditing)
axe-core (accessibility violations)
Istanbul (nyc) (coverage reporting)

The testing tools used in this refactor include Vitest for unit and integration tests, Playwright for end-to-end tests, axe-core for accessibility auditing, and Istanbul (nyc) for coverage reporting. These tools provide a comprehensive suite of testing capabilities.

📅 Implementation Phases

The implementation is divided into seven phases, each with specific goals and deliverables. This phased approach allows for incremental development and testing, minimizing risk and ensuring a smooth rollout.

Phase 1: Foundation (Week 1-2) - 60-70h

Create composables (useKeyboardNav, useResponsive, useImageLoader, usePageTransition)
Create base components (SessionList, SessionPreview, ImageGallery, ImageViewer)
Write unit tests (95%+ coverage)
Deliverable: All foundation components tested and working

Phase 2: Page 1 Enhancement (Week 3) - 20-25h

Add transition hooks to Sessions.vue
Implement grid → list morph animation
Integration tests (grid ↔ list)
Deliverable: Page 1 animations working

Phase 3: Page 2 Enhancement (Week 4) - 25-30h

Add responsive columns to SessionDetail.vue
Integrate SessionPreview (12 images)
Integration tests (Page 1 ↔ Page 2)
Deliverable: Page 2 complete, responsive

Phase 4: Page 3 Implementation (Week 5) - 30-35h

Implement SessionImages.vue (full gallery)
Integrate FilterDrawer
Integration tests (filters + gallery)
Deliverable: Page 3 complete, filters working

Phase 5: Page 4 & Popin (Week 6) - 20-25h

Enhance ImageDetail.vue with keyboard nav
Implement ImageViewer popin overlay
Integration tests (viewer + navigation)
Deliverable: Page 4 complete, keyboard nav working

Phase 6: Gallery Refactor (Week 7) - 25-30h

Refactor Gallery.vue (liked images only, no sidebar)
Add backward compatibility redirects
Update navigation links app-wide
Deliverable: Gallery refactored, redirects working

Phase 7: Mobile & Polish (Week 8) - 30-40h

Implement bottom sheets (filters on mobile)
Add swipe gestures (back navigation, image navigation)
E2E tests (mobile flows, gestures)
Performance optimization (bundle size, animations)
Deliverable: Mobile UX complete, all tests passing

Estimated Total

Time: 8 weeks (210-255 hours)
Buffer: +20% for unforeseen issues (42-51h)
Total with buffer: 10 weeks (252-306 hours)
Effort: Large

The estimated timeline and effort provide a clear picture of the scope and complexity of the refactor. The buffer ensures that there is sufficient time to address any unforeseen issues.

🎯 Success Metrics

Success metrics provide quantifiable measures of the refactor's success. These metrics cover test coverage, performance, accessibility, mobile usability, and user experience.

Test Coverage

Unit tests: 95%+
Integration tests: 85%+
E2E tests: 80%+
Overall: 90%+

Performance Budget

Lighthouse Performance: > 90
Animations: < 400ms, 60fps
Initial bundle: < 300KB gzipped
Page load on 3G: < 2s

Accessibility

Lighthouse Accessibility: = 100
WCAG 2.1 Level AA: 100% compliant
Screen reader: All content accessible

Mobile Usability

Touch targets: ≥ 48×48px
Mobile-Friendly Test: Pass
Bottom sheet animation: < 200ms

User Experience

Task completion rate: > 95%
SUS (System Usability Scale): > 80

📊 Business Value

Priority: High

Impact: Major UX improvement with significant benefits:

Clearer information hierarchy - Users understand what they're looking at
Better separation of concerns - Sessions vs Gallery are distinct use cases
Improved mobile experience - Native-app-like UX with gestures and bottom sheets
Foundation for future features - Comparison mode, smart collections, export
Reduced cognitive load - Progressive disclosure reduces overwhelm

Risk: Medium (major refactor but with backward compatibility)

Effort: Large (8 weeks, 210-255 hours)

The business value highlights the importance of the refactor, its impact on user experience, and the associated risks and effort. The high priority and significant benefits justify the investment in this project.

🔗 Related Issues

(To be filled after issue creation)

📝 Notes

Backward Compatibility

All old routes redirect to new routes (/gallery/:sessionName → /sessions/:name/images)
No breaking API changes
Feature flag for gradual rollout (10% → 50% → 100%)
Rollback plan ready (instant revert via feature flag)

Backward compatibility measures ensure that existing functionality is not broken during the refactor. The use of redirects, feature flags, and a rollback plan minimizes the risk of disruption.

Migration Plan

Week 9: Beta rollout (staging, internal testing)
Week 10: 10% production rollout with A/B testing
Week 11: 50% rollout, monitor performance
Week 12: 100% rollout, archive old code

The migration plan outlines the steps for rolling out the refactored navigation system to production. The gradual rollout and A/B testing ensure that the changes are introduced smoothly and any issues are identified and addressed promptly.

Key Technical Decisions (ADRs)

Progressive disclosure pattern (4 levels: grid → details → gallery → viewer)
Vue Router for state (URL as single source of truth, deep linking)
GPU-accelerated animations only (transform + opacity, no layout-triggering properties)
IntersectionObserver for lazy loading (memory-efficient, fast initial render)
Playwright for E2E (cross-browser, mobile emulation, a11y auditing)

Key technical decisions document the major architectural choices made during the refactor. These decisions are crucial for ensuring the long-term maintainability and scalability of the system.

Documentation

Full UX spec: .claude/20251117_195500-webui-navigation-redesign.md
Complete TDD plan: .claude/20251117_navigation-refactor-tdd-plan.md
Component contracts, test scenarios, risk assessment, ADRs included

The comprehensive documentation ensures that all aspects of the refactor are well-documented, providing a valuable resource for future development and maintenance.

This refactor is well-planned and comprehensive, with a clear problem statement, detailed architecture, TDD approach, incremental rollout, and a focus on performance, accessibility, and mobile responsiveness. It is poised for successful implementation.

For further reading on web application architecture and best practices, check out this resource on Mozilla Developer Network. This external link provides additional information and insights into web development principles.

🎯 Summary

📋 Problem Statement

🎨 Proposed Solution

Page 1: /webui/sessions - Sessions Grid

Page 2: /webui/sessions/:name - Session Details

Page 3: /webui/sessions/:name/images - Full Gallery

Page 4: /webui/sessions/:name/images/:imageId - Image Viewer

Refocused Gallery: /webui/gallery

✨ Key Features

Progressive Disclosure

Smooth Animations

Mobile-First Responsive

Keyboard Shortcuts

Accessibility

📐 Architecture

Design & TDD Documentation

Component Tree

New Components

New Composables

Router Configuration

✅ Acceptance Criteria

User Flows (Given/When/Then)

Performance

Testing

Accessibility

Mobile Usability

🧪 Testing Strategy

Test Structure

Testing Tools

📅 Implementation Phases

Phase 1: Foundation (Week 1-2) - 60-70h

Phase 2: Page 1 Enhancement (Week 3) - 20-25h

Phase 3: Page 2 Enhancement (Week 4) - 25-30h

Phase 4: Page 3 Implementation (Week 5) - 30-35h

Phase 5: Page 4 & Popin (Week 6) - 20-25h

Phase 6: Gallery Refactor (Week 7) - 25-30h

Phase 7: Mobile & Polish (Week 8) - 30-40h

Estimated Total

🎯 Success Metrics

Test Coverage

Performance Budget

Accessibility

Mobile Usability

User Experience

📊 Business Value

🔗 Related Issues

📝 Notes

Backward Compatibility

Migration Plan

Key Technical Decisions (ADRs)

Documentation

Page 1: `/webui/sessions` - Sessions Grid

Page 2: `/webui/sessions/:name` - Session Details

Page 3: `/webui/sessions/:name/images` - Full Gallery

Page 4: `/webui/sessions/:name/images/:imageId` - Image Viewer

Refocused Gallery: `/webui/gallery`