docs: correct scroll-snap guidance (native CSS Snap over JS scroll-jacking)

[brunogbv]

Context

docs/interaction-gotchas.md (added in #165) steered readers toward driving a full-viewport section
"deck" with JavaScript — intercept wheel/touch, animate scrollTop to the next index. The 003
prototype proved that inverts the right answer. A hand-rolled scroll-jacker inescapably fights the
platform's own scroll momentum, most visibly a macOS trackpad (one two-finger swipe emits ~40+
inertial, not-reliably-cancelable wheel events with no momentum-phase signal), producing a
sluggish/flickering start that no amount of tuning removes. Switching to native CSS Scroll Snap
fixed it in less code, and the owner confirmed it "works perfectly."

Left as-is, the doc would actively mislead the next interaction-heavy change (incl. the pending 003
re-spec) into rebuilding the scroll-jacker.

What changed

• Rewrote "Scroll-snap ↔ programmatic scroll" with a headline rule (use native snap; do not
  hand-roll wheel/touch scroll-jacking) and a working native-deck CSS snippet.
• Clarified that native snap gives one-panel-per-flick for wheel/trackpad/touch by itself
  (mandatory + scroll-snap-stop: always on uniform viewport-height panels); JS is needed only
  for the keyboard — a thin scrollIntoView layer that coexists with mandatory snap (they don't
  fight). The "hiccup" is specifically JS-animated scroll vs mandatory snap: an argument to stop
  animating the scroll yourself, not to abandon snap.
• Added the library findings from the discovery (fullPage.js GPLv3 + Mac trackpad bug; Swiper
  MIT but Mac "jumps 2 slides") and why none is warranted here.
• Converted single-asterisk italics → underscores in this file (markdownlint MD049; the prior lint
  run had skipped the rule on a re2 module load error).

Scope / safety

Documentation only; guidance is screen-only and the PDF/print flow is unaffected. Verified locally:
make lint green (Super-Linter, real exit 0); technical claims + internal/architecture.md
consistency reviewed (all citations from the 003 discovery's primary sources — caniuse, vendor
license pages, upstream issue trackers).

References

• Supersedes the now-inverted guidance from Document scroll-snap / interaction-feel gotchas (avoid the snapping thrash) #161 / Document scroll-snap / interaction-feel gotchas #165.
• Emerged from the 003 interactive-CV prototype (branch 003-proto, PR [PROTOTYPE — do not merge] Reference restyle + section-snap + summary/detail #156) trackpad-feel work.

[github-actions]

🔺 Vercel preview: https://cv-qwv8fu759-bruno-valerios-projects.vercel.app

_{commit 1f712f5 · updated 2026-07-04 15:26 UTC}