/flow

Parallax Effects Reference

Purpose: Implement depth-illusion via differential layer translation tied to scroll position. Covers multi-layer composition, performance budget for compositor-only execution, and mandatory prefers-reduced-motion handling — parallax is a documented vestibular trigger and is the most-abused motion pattern on the web.

Scope Boundary

• flow parallax: continuous-scrub depth-illusion via translate offsets. Layers move at different rates relative to scroll.
• flow scroll (sibling): discrete reveal triggers. Fires once/each-time at thresholds; not continuous scrubbing.
• flow transition (sibling): route/modal motion. Unrelated to scroll position.
• modern-css-animations.md (sibling reference): animation-timeline: scroll()/view() API — the modern, compositor-safe parallax mechanism.
• palette (elsewhere): UX critique of whether parallax serves the user. Parallax often hurts content comprehension; Palette owns the "should we?" decision.
• vision (elsewhere): creative direction calling for depth/atmosphere. Vision authors the brief; Flow scopes implementation.
• artisan (elsewhere): production component owning layer markup. Flow wires the scroll coupling.

Workflow

SURVEY   → confirm intent (atmospheric depth, hero only, not full-page)
         → confirm layer count (2-4 max), max translate range, viewport scope
         → confirm reduced-motion fallback (static, no parallax)

PLAN     → choose mechanism: scroll-driven CSS (preferred, Chrome 115+/Safari 26+)
           or rAF-throttled JS (universal fallback)
         → define rate per layer (background slowest, foreground fastest)
         → cap max translate offset to prevent layer escaping bounds

VERIFY   → confirm 60fps with DevTools Performance panel; check no layout/paint
         → verify prefers-reduced-motion disables parallax entirely
         → measure CLS — parallax-induced CLS is a common shipping blocker

PRESENT  → deliver code + reduced-motion branch + perf measurement

Mechanism Map

Code Pattern Table

Layer Rate Cheat Sheet

Rule: content layers stay still, decoration moves. Parallaxing text or primary CTAs is an accessibility regression.

Performance Budget

prefers-reduced-motion

Parallax is one of the highest-priority motion patterns to disable under reduced-motion — it is a documented vestibular trigger that causes nausea and dizziness in sensitive users.

@media (prefers-reduced-motion: reduce) {
  .parallax-layer {
    animation: none !important;
    transform: none !important;
  }
}

const reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (reduce) return; // skip useScroll/scrollTrigger entirely

This is non-negotiable: WCAG 2.3.3 (Animation from Interactions) and the EU Accessibility Act (effective June 2025) treat parallax disable under reduced-motion as a baseline requirement. Do not "soften" parallax for reduced-motion users — disable it completely.

Anti-Patterns

• Parallaxing primary content — breaks reading flow, hurts comprehension, is the #1 reason "parallax sites" rank low in usability studies.
• Animating background-position for parallax — forces paint on every frame; 30fps at best on mid-tier mobile. Use transform: translate3d() on a layer.
• Scroll listener without passive: true — blocks scroll, causes jank. addEventListener('scroll', fn, { passive: true }) always.
• Scroll listener without rAF throttling — fires 60+ times/second, recalculates layout each time, creates main-thread bottleneck.
• More than 4 parallax layers — perceptual depth caps at 3-4; additional layers just consume GPU memory and cause jitter.
• Parallax over the entire page height — full-page parallax is a top abandonment driver. Scope to hero or one feature section.
• No reduced-motion branch — parallax is the canonical vestibular trigger; shipping without disable violates WCAG 2.3.3.
• Animating layout-triggering properties (top, margin-top, height) — top CLS contributor; breaks Core Web Vitals immediately.
• Coupling parallax to wheel events instead of scroll — breaks touch, breaks keyboard scroll, breaks accessibility.
• Parallax inside a sticky/fixed container without view() ranges — layers escape bounds and float across unrelated sections.

Handoff

• To Radar: parallax FPS verification on mid-tier mobile (target device: ~$250 Android, throttled CPU 4× in DevTools); CLS regression check.
• To Bolt: if parallax causes CLS > 0.1 or INP > 200ms, escalate. Compositor refactor or section scope reduction may be needed.
• To Palette: if user research shows confusion or nausea reports, Palette re-evaluates whether parallax should exist at all — Flow does not own the "should we?" decision.
• To Vision: if parallax direction conflicts across pages, escalate for unified depth-system direction.
• To Canvas: multi-section parallax choreography needs depth-layer diagram.