Zoom & a11y

Desktop image viewers split into two families, depending on whether the surface is treated as a media viewer or a canvas / document:

• Media-viewer model (Google Photos, Lightroom, PhotoSwipe, OpenSeadragon): a bare scroll wheel zooms toward the cursor; drag pans.
• Canvas / document model (Figma, macOS Preview, Google Maps on trackpad): a bare scroll pans, and zoom is gated behind a modifier (Ctrl / ⌘) or a trackpad pinch — so it never hijacks the user’s scroll.

Regardless of family, four things are near-universal: drag pans when zoomed, wheel/pinch zoom is focal (zooms toward the pointer), double-click toggles zoom, and Ctrl/⌘+wheel and trackpad pinch always zoom. The only real disagreement is whether a bare wheel zooms or pans.

ramka defaults to the canvas model: Ctrl/⌘+wheel and trackpad pinch zoom to the cursor, a bare wheel is a no-op at 1× (and pans when zoomed), and scrollToZoom on Zoom opts into the media-viewer behavior. That is the more embed-friendly default — a lightbox often lives inside a scrollable page, so bare-wheel zoom risks trapping the user’s scroll.

The one intentional inconsistency: ZoomIn / ZoomOut zoom about the center rather than the cursor. That is standard — buttons have no pointer position — and matches Google Maps / OpenSeadragon button behavior.

Touch is far more uniform than desktop — every mainstream photo viewer converges on the same model, set by iOS Photos and Android’s Google Photos:

• Pinch to zoom, focal at the pinch midpoint — the image stays glued to the centroid, so spreading and sliding two fingers zoom and pan as one gesture — with a rubber-band overshoot past the min/max that snaps back on release.
• Double-tap toggles between fit and a zoomed level, centered on the tap point.
• One- or two-finger drag pans while zoomed, with inertia / momentum on release.
• At fit, a horizontal swipe navigates and a downward swipe dismisses the viewer.

The subtle-but-critical part is arbitration: pinch, pan, swipe-to-navigate, and swipe-to-dismiss all start from the same finger, so a viewer has to decide which gesture owns a given touch without misfiring.

ramka implements the full iOS/Android touch model, including the arbitration details that make it feel native — deferred double-tap commit (so a flick that starts near the last tap never zooms by mistake), elastic overscroll on both pinch and pan, momentum with bound-clamping, and a haptic tick on snap-back. Pull-to-dismiss and zoom/pan share a navigation lock so an in-flight Slides fling can’t be hijacked mid-scroll.

The touch model is where ramka is strongest — it matches the platform viewers point-for-point and adds haptics that most web lightboxes skip. Note that Instagram-style pinch-to-peek (zoom only holds while fingers are down, then springs back to fit) is a deliberate product choice, not the default; ramka keeps the zoom level after release like Photos, which is the right behavior for a general-purpose viewer.

• Zoom to the cursor. The single most important pointer-zoom heuristic. ramka honors it for wheel, pinch, and double-click.
• Don’t hijack bare scroll by default. Keeping scrollToZoom off is the safer default for embedded lightboxes; enable it for full-bleed, single-image viewers.
• Signal zoomability at rest. Consider a zoom-in cursor over the image at 1× so mouse-only users discover double-click / Ctrl-wheel zoom. ramka leaves this to your CSS — the Zoom surface exposes data-zoom only while scaled past 1×. Set cursor: zoom-in on your Zoom class — ramka’s inline cursor (grab / grabbing) wins once scaled:

/* .my-zoom is the className you pass to Lightbox.Zoom */
.my-zoom {
  cursor: zoom-in;
}

• Never steal swipe-to-dismiss. On touch, pan must only take over after the image is zoomed; at fit, the vertical swipe belongs to pull-to-dismiss and the horizontal swipe to navigation. ramka gates this with touch-action and the navigation lock.
• Rubber-band, don’t hard-stop. Elastic overscroll on pinch and pan (plus a haptic tick on snap-back) is what makes zoom feel native rather than mechanical.
• Size touch controls for fingers. Give ZoomIn / ZoomOut and Close a hit area of at least 44×44 px on touch (WCAG 2.5.8 asks ≥24 px; 44 px is the platform norm).

These are the WCAG 2.2 success criteria that govern zoom & pan. ramka ships the pointer and keyboard alternatives the criteria expect:

Note on 2.5.7. Pan-by-drag has a keyboard alternative (arrows), which satisfies 2.1.1 Keyboard, but 2.5.7 specifically wants a single-pointer, non-drag alternative — keyboard does not count for it. If you must meet AA strictly, add pointer pan controls (e.g. edge/arrow buttons) alongside ZoomIn / ZoomOut. Many shipping viewers do not either, but for enterprise targets it is worth flagging.