3.5 KiB
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.jsonorSectionRenderer.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
-
Option 1: In-Place Wheel & Trackpad Translation + Floating Side Arrows (Selected)
- Translates
deltaYtoscrollLefton 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
ChevronLeftandChevronRightbuttons on the left and right flanks. - Trade-off: Retains clean layout flow without modifying page scroll height.
- Translates
-
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
useEffectwith 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.
- Attached via
- Arrow Navigation:
- Left button with
ChevronLefticon, right button withChevronRighticon. 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.
- Left button with
- Snap Polish:
- Uses
snap-x snap-proximityfor smooth wheel translation without abrasive snap fighting, locking neatly onto cards when resting.
- Uses