hyperframes/skills/hyperframes-animation/blueprints/demo-page-scroll-spotlight.md

id, role, duration_seconds, phases, visual_arc, uses_rules, element_roles, when_to_use, when_not_to_use, triggers

id	role	duration_seconds	phases	visual_arc	uses_rules	element_roles	when_to_use	when_not_to_use	triggers
demo-page-scroll-spotlight	demo	5 9	4	page-entry → scroll-to-feature → keyword-highlight → pop-out-emphasis	3d-page-scroll asr-keyword-glow	page_card scroll_content highlight_elements spotlight Full webpage recreation rendered as a tilted 3D card Page content that scrolls within the clipped card Specific page elements that glow and scale when mentioned in voiceover Radial gradient overlay that dims non-highlighted areas	Demonstrate a specific feature within its natural UI context Voiceover names features that should highlight in sync Show the product "in action" without a screen recording 3D perspective adds premium feel	Product has no webpage or UI to recreate Feature is best shown via actual screen recording Scene only needs a single static product image	show the feature product demo highlight on page webpage in 3D scroll to feature

Demo · Page Scroll Spotlight (HyperFrames)

A "this is the product, this is the part that matters" arc: the tilted page coasts in like a held-up phone, voiceover names a couple of features and those words flare on the header, then the page rolls upward to reveal the section being demoed, and one element finally lifts off the surface to claim the climax. Premium-demo register — never cuts, never screen-records.

One paused GSAP timeline drives all four phases. Phases 3 and 4 overlap on purpose; everything else has a small breath of buffer.

When to Use

• Feature demo where voiceover walks through capabilities by name and the headline words should react
• Product has a real DOM-rendered webpage component (a screenshot cannot be highlighted element-by-element)
• The demo should feel premium (3D depth + spotlight) rather than flat (a captured recording)
• Skip if no headline keywords need to glow (use plain 3d-page-scroll instead) or if only one static product shot is needed

Orchestration

Four phases, two rules plus two small inline patterns. The rules carry the bulk; the seams between them are the work.

• Phase 1 — page card entry: inline. The 3d-page-scroll rule starts the card already on screen — it doesn't speak to how the card arrives. We add a single scale: CARD_ENTRY_FROM_SCALE → 1.0 with power2.out on .page-card, plus staggered opacity fade-ins on navbar / title / CTA. Critical: the card's static tilt is already baked in by gsap.set() before the entry tween starts — see "Phase 1 Seam" below. A spring (back.out) here would look like a pop-up modal, not a phone held up to the camera, so power2.out is the only correct ease.
• Phase 2 — keyword glow on header: use asr-keyword-glow in its karaoke variation (the rest of the headline stays dim, attacked words pop bright). Default subtle glow reads as ambient on top of the tilted page and gets lost; karaoke gives the words enough contrast to feel narrated. We diverge from the rule on one mechanical point: each word's envelope is driven by two tl.fromTo/tl.to tweens on a CSS variable --glow instead of the rule's single-driver onUpdate over all words. See "Phase 2 Seam" for why.
• Phase 3 — scroll to the feature section: use 3d-page-scroll — the rule's main payload. One thing to override from the rule's default: ease is power2.inOut, not power3.out. Reason in this scene: the scroll is symmetrical — it has to start gently (we're already at a held-up frame, a hard onset reads as a jump cut) and decelerate symmetrically into where the pop will happen. The rule's power3.out is right when scroll is the climax; here the pop is the climax, so the scroll has to be a transit not a landing.
• Phase 4 — pop-out + spotlight: inline, but re-uses the --glow CSS variable mechanic from asr-keyword-glow, repurposed for a non-text element. A pair of attack + decay tweens drive .pop-target { --glow: 0 → 1 → POP_REST_LEVEL }; CSS calc() on that same element derives translateZ and scale from --glow, and a parallel opacity tween on .spotlight dims the surrounding card. This is the climax — one tween-pair per visual effect would split the source of truth across three timeline calls; one --glow driving everything via calc() keeps it monotonic and audit-able. See "Phase 4 Seam".

Phase Timing

All seconds, local to the scene.

Phase	Start ≥	Internal duration	Notes
1	0	CARD_ENTRY_DUR	Card scale + element fades; staggered offsets within
2	First keyword's ASR start (≥ Phase 1 end + ~0.1s)	per-word ASR windows	First glow attack starts ~0.1s after title fade finishes
3	Last keyword attack end + ~0.2s	SCROLL_DUR	Lets the last karaoke peak read before the page starts moving
4	SCROLL_AT + SCROLL_DUR * 0.6 (intentional overlap)	POP_ATTACK_DUR + POP_DECAY_DUR	Pop attacks during the scroll's tail — eye-leading handoff

Three of these gaps deserve a word each. Phase 1 → 2: ~0.1s after TITLE_FADE_AT + TITLE_FADE_DUR so the title is fully readable before the first word flares — start the glow on top of a still-rising opacity and the eye reads it as a fade-in artifact, not narrator emphasis. Phase 2 → 3: ~0.2s after the last word's attack peak (not its release end — karaoke rest is the held state and stays through the scroll, which is exactly the breadcrumb-trail effect we want). Phase 3 → 4: the pop deliberately overlaps the scroll's last ~40%. The rule normally puts pop-equivalent motions after a scroll lands; here we want the viewer's eye to be drawn to where the scroll is going to land before it arrives, so the pop attacks while the scroll is still moving. This is the only intentional overlap in the scene.

Initial DOM Nesting

The transform-style: preserve-3d chain is the only structural constraint, and it's already in the 3d-page-scroll rule. The one twist this blueprint adds: the pop target sits inside .scroll-content, not as a sibling — it has to translate with the page when Phase 3 scrolls, then independently translateZ when Phase 4 fires.

.perspective-wrap          ← perspective set here
  .page-card               ← static tilt via gsap.set(); transform-style: preserve-3d; overflow: hidden
    .scroll-content        ← Phase 3 tweens this element's y
      .page-navbar         ← Phase 1 fade
      .page-hero
        .hero-title
          .kw[data-glow-start data-glow-end] ← Phase 2 targets (one per glowable word)
      .page-features
      .page-carousel
        .pop-target        ← Phase 4 target; transform-style: preserve-3d required HERE too
    .spotlight             ← Phase 4 opacity fade; SIBLING to .scroll-content, NOT child

.spotlight must be a sibling of .scroll-content (not a child) — otherwise Phase 3's scroll translates the spotlight out of the card along with the content, and it dims the wrong region. Same transform-style: preserve-3d chain must reach .pop-target — .page-card sets it, but if any intermediate wrapper resets transform-style, .pop-target's translateZ flattens to zero.

Phase 1 Seam: Tilt Set via gsap.set(), Not CSS

The 3d-page-scroll rule's CSS sets tilt declaratively. That works only when no other tween touches .page-card's transform. In this blueprint Phase 1 tweens .page-card { scale: ... → 1.0 }, and GSAP's scale tween overwrites the full transform matrix — declared CSS rotation goes with it, and the card lands flat. Fix: own the entire transform in GSAP:

gsap.set(".page-card", {
  rotateY: CARD_TILT_Y,
  rotateX: CARD_TILT_X,
  scale: CARD_ENTRY_FROM_SCALE,
});
tl.to(".page-card", { scale: 1.0, duration: CARD_ENTRY_DUR, ease: "power2.out" }, 0);

GSAP composes subsequent scale tweens against the rotation it owns, so the tilt survives. Removing the gsap.set() and putting the rotation back in CSS is the single most common Phase 1 failure mode.

CARD_TILT_Y and CARD_TILT_X are set once here. Do not animate them in any later phase — the page is a camera setup, not a flip card. A tweened tilt makes the demo read as a UI animation rather than a held-up product.

Phase 2 Seam: Two-Tween Envelope per Word, Not Single Driver

The asr-keyword-glow rule recommends a single driver tween with an onUpdate callback iterating every word. That pattern is correct when the per-word envelope is purely runtime-derived; we use a two-tween variant here:

document.querySelectorAll(".kw").forEach((kw) => {
  const start = +kw.dataset.glowStart;
  const end = +kw.dataset.glowEnd;
  const peak = start + (end - start) / 2;
  const restAt = end + KEYWORD_SUSTAIN;
  tl.fromTo(
    kw,
    { "--glow": 0 },
    { "--glow": 1, duration: peak - start, ease: "power2.out" },
    start,
  );
  tl.to(kw, { "--glow": KEYWORD_REST_LEVEL, duration: restAt - peak, ease: "power2.out" }, peak);
});

Two reasons for the divergence. First, the glow timestamps live in DOM (data-glow-start / data-glow-end) rather than in a JS TIMINGS object — easier for the upstream script-to-DOM step to populate per-word and easier to audit by inspecting the page. Second, the climax pop in Phase 4 uses the same --glow CSS-variable mechanism, so keeping Phase 2 on --glow tweens means the whole scene shares one variable-driven mental model. The trade-off is more tweens on the timeline; with 4–8 keywords it's still well under the rule's "60+ words gets unwieldy" threshold.

Flagged rule gap: asr-keyword-glow documents the single-driver onUpdate pattern only. The --glow CSS-variable variant used here is not covered by the rule; we treat it as the rule's "karaoke" payload re-expressed on a CSS variable.

Phase 3 Seam: SCROLL_DISTANCE Comes From the Page, Not From a Range

SCROLL_DISTANCE is not a tunable — it's a measured geometric fact of the page layout. The target is the vertical center of .page-carousel (where .pop-target lives) landing at roughly 60–70% of the card's visible height (the position where the spotlight's gradient ellipse is centered — see Phase 4). Measure with a one-off getBoundingClientRect() at design time, bake the result as const SCROLL_DISTANCE = …, never recompute.

Why bake: at the 3D tilt the card uses, sub-pixel scroll drift looks like a vibration, not a scroll — every Math.random-free deterministic system has to land on the same pixel every play.

The rule's default ease for this property is power3.out. We override to power2.inOut here for the reason in Orchestration: the scroll isn't the climax. Keep the same ease across this single scroll — no second scroll in this blueprint, so the rule's "same ease across multi-phase scroll" caveat doesn't apply.

Phase 4 Seam: One Variable, Three Visual Effects

.pop-target carries a CSS variable --glow (initial value 0). Three CSS effects all key off it:

.pop-target {
  --glow: 0;
  transform-style: preserve-3d;
  transform:
    translateZ(calc(var(--glow) * var(--pop-translate-z)))
    scale(calc(1 + var(--glow) * var(--pop-scale-boost)));
  box-shadow:
    0 0 calc(var(--glow) * 25px) {accentColorRgba},
    0 calc(20px + var(--glow) * 40px) 60px rgba(0, 0, 0, 0.6);
  border: 3px solid {accentColorBorderRgba};
}

GSAP only tweens --glow; CSS does the derivation. Two tweens shape the envelope — attack to 1, decay to POP_REST_LEVEL:

tl.fromTo(
  ".pop-target",
  { "--glow": 0 },
  { "--glow": 1, duration: POP_ATTACK_DUR, ease: "power2.out" },
  POP_AT,
);
tl.to(
  ".pop-target",
  { "--glow": POP_REST_LEVEL, duration: POP_DECAY_DUR, ease: "power2.out" },
  POP_END - POP_DECAY_DUR,
);
tl.to(".spotlight", { opacity: 1, duration: SPOTLIGHT_FADE_DUR, ease: "power2.out" }, POP_AT);

The single-variable-many-effects pattern matters here because three separate tweens (one each for translateZ, scale, box-shadow) all racing the same window create round-off skew across CSS engines; one tween on a value the CSS reads through calc() is bit-exact across frames.

POP_REST_LEVEL is intentionally higher than KEYWORD_REST_LEVEL (0.3–0.7 vs 0.1–0.3) — the pop target stays in focus for the rest of the scene, whereas keywords are a breadcrumb. Letting the pop decay all the way back to --glow: 0 looks like the climax got walked back.

The spotlight gradient is centered roughly at the same screen position the pop target lands at after Phase 3's scroll — typically 40% 60% of the card. If you change SCROLL_DISTANCE, also re-center the radial-gradient(... at X% Y% ...) to match, otherwise the spotlight illuminates an empty region of the page.

Key Values to Choose (Not Already in the Rules)

Only parameters unique to this blueprint; for the standard ranges of MAX_BLUR, MAX_SCALE_BOOST, REST_LEVEL, SCROLL_DUR, tiltYDeg, etc., go to the linked rules.

• CARD_ENTRY_FROM_SCALE: 0.90–0.98. Lower reads as a punchier zoom-in; higher as a gentle settle. Must be < 1.0.
• CARD_ENTRY_DUR: 0.6–1.2s. Shorter feels tech-y; longer feels cinematic.
• NAVBAR_FADE_AT / TITLE_FADE_AT / CTA_FADE_AT: strict ordering 0 ≤ NAVBAR_FADE_AT < TITLE_FADE_AT < CTA_FADE_AT < SCROLL_AT, with ~0.15–0.35s stagger between each. Reads as "page settles into focus" rather than "everything lands at once."
• KEYWORD_SUSTAIN: 0.3–0.8s. Seconds after each word's ASR end before its decay completes. Tune by checking that the last-spoken word is still readably bright when the next word peaks.
• POP_AT: must satisfy POP_AT < SCROLL_AT + SCROLL_DUR — intentional overlap with the scroll tail.
• POP_ATTACK_DUR: 0.4–0.9s. The pop reads as deliberate at the long end, snappy at the short end.
• POP_END: must satisfy POP_END ≤ data-duration and POP_END > POP_AT + POP_ATTACK_DUR. Leave ≥0.8s after POP_END for visual dwell on the lit pop target — same "climax dwell" reasoning the keyword-glow rule names.
• POP_DECAY_DUR: 0.2–0.6s.
• POP_REST_LEVEL: 0.3–0.7. Higher than KEYWORD_REST_LEVEL because the pop target holds the frame.
• POP_TRANSLATE_Z: 40–120px peak Z translation. Above ~100 starts to feel like the element is detaching from the card.
• POP_SCALE_BOOST: 0.05–0.25 additive scale.
• SPOTLIGHT_FADE_DUR: 0.3–0.7s.

Critical Constraints (ordered by failure frequency)

• Tilt set via gsap.set(), not CSS (see Phase 1 Seam). The scale tween in Phase 1 erases CSS-declared rotation — this is the single highest-frequency bug in this blueprint.
• SCROLL_DISTANCE is measured, not tuned: derive from the actual page geometry at design time, bake as const. Don't compute per-frame from getBoundingClientRect().
• Spotlight gradient center matches .pop-target post-scroll position: change SCROLL_DISTANCE ⇒ re-center the gradient. Mismatch leaves the spotlight illuminating empty page.
• .spotlight is a sibling of .scroll-content, not a child: otherwise Phase 3 scrolls the spotlight out of the card with the content.
• transform-style: preserve-3d continues onto .pop-target: any intermediate wrapper that resets it flattens the Phase 4 translateZ to zero.
• Pop overlap is intentional, not a bug: POP_AT < SCROLL_AT + SCROLL_DUR. If a future review pulls POP_AT past the scroll end "to be safe," the eye-leading handoff is lost.
• Page must be DOM, not a screenshot: screenshots can't be element-highlighted (the rule already states this; restating because a tempting shortcut is to drop in a static image of the page).
• Shadow X-offset sign matches tilt sign (the 3d-page-scroll rule's principle). Negative tilt-Y ⇒ positive shadow X-offset.

Spring → Ease Selection

Four eases, four feels. Full mapping table lives in hyperframes-animation/SKILL.md; the picks for this blueprint:

• Phase 1 entry / fades → power2.out (settling)
• Phase 2 glow attack & decay → power2.out (fast onset, slow settle)
• Phase 3 scroll → power2.inOut (symmetrical transit, not power3.out — see Orchestration)
• Phase 4 pop attack & decay → power2.out

Golden Sample

• demo-page-scroll-spotlight.html — 4-phase, ~9-second scene with concrete values for every named constant above. Run this first, then change values — much faster than building from scratch.