Files
webb/docs/superpowers/specs/2026-11-04-showcase-vertical-wheel-and-arrows-design.md
T

3.5 KiB

Design: Interactive Model Showcase Vertical Scroll Translation & Side Navigation Arrows

Date: 2026-11-04
Status: Approved (Option 1 selected by user)
Target File: src/components/sections/CinematicHorizontalScrollSection.tsx


1. Intent & Purpose

Enable visitors to navigate the flagship transformation models in the Interactive Model Showcase using natural vertical wheel/trackpad scrolling and dedicated tactile Left/Right side arrow buttons, making horizontal exploration effortless on both desktop and mobile.


2. Goals, Non-Goals, and Anti-Goals

Goals

  • Vertical-to-Horizontal Translation: Vertical mouse wheel and trackpad scroll gestures (deltaY) over the showcase rail directly translate into horizontal scrolling.
  • Natural Boundary Pass-Through: When the rail reaches its horizontal start (scrolling up) or end (scrolling down), vertical page scrolling naturally resumes so users never get trapped.
  • Side Navigation Arrows: Sleek, accessible, liquid-glass Left and Right arrow buttons floating on either side of the rail that slide card-by-card on click.
  • Dynamic State: Arrow buttons automatically update their disabled/opacity state based on current scroll position.
  • Zero Regressions: Maintain high-contrast light creamy theme, mobile touch-swipe, and WCAG AA accessibility standards.

Non-Goals

  • Full viewport height pinning (Option 2 was declined in favor of in-place wheel translation).
  • Modifying the underlying data schemas in content/pages/home.json or SectionRenderer.tsx.

Anti-Goals

  • Trapping vertical scroll permanently or blocking scroll when at the edges.
  • Obscuring before/after comparison interactive sliders with arrow buttons.

3. Approaches Considered

  1. Option 1: In-Place Wheel & Trackpad Translation + Floating Side Arrows (Selected)

    • Translates deltaY to scrollLeft on non-passive wheel events when hovering the showcase section.
    • Bails out when at the boundary edges to allow standard vertical document scroll.
    • Adds floating, accessible ChevronLeft and ChevronRight buttons on the left and right flanks.
    • Trade-off: Retains clean layout flow without modifying page scroll height.
  2. Option 2: Sticky Pinned Viewport Track (Rejected)

    • Pins the section to the viewport for 300vh of vertical scroll distance.
    • Trade-off: High layout footprint, can feel disruptive on shorter viewports.

4. Implementation Details

  • File: src/components/sections/CinematicHorizontalScrollSection.tsx
  • State & Refs:
    • railRef = useRef<HTMLDivElement>(null): Reference to the horizontal scrolling rail.
    • canScrollLeft: boolean state, default false.
    • canScrollRight: boolean state, default true.
  • Wheel Listener (passive: false):
    • Attached via useEffect with clean cleanup.
    • Only intercepts when vertical delta is dominant (Math.abs(e.deltaY) > Math.abs(e.deltaX)).
    • Calls e.preventDefault() only if the rail has remaining scroll distance in the scroll direction.
  • Arrow Navigation:
    • Left button with ChevronLeft icon, right button with ChevronRight icon.
    • scrollBy({ left: +/- scrollDistance, behavior: 'smooth' }), calculating step based on card width + gap.
    • High z-index, styled with bg-white/90, backdrop-blur-md, shadow-cream-md, and smooth hover scale.
    • Hidden or opacity-0 when disabled to maintain a clean aesthetic at boundaries.
  • Snap Polish:
    • Uses snap-x snap-proximity for smooth wheel translation without abrasive snap fighting, locking neatly onto cards when resting.