mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-11 14:50:02 +00:00
feat(skills): c2v mining pass — 7 new blueprints, 10 new rules, compacted recipe corpus (#2680)
* feat(skills): c2v mining pass over animation blueprints and rules Compacts ~45 existing animation rules/blueprints into tighter recipe form (net -3.4k lines) and adds 17 mined from the c2v corpus: - 7 blueprints: agent-progress-theater, camera-journey, fixed-anchor-cycle, panel-edit-live-sync, prompt-type-submit-generate, transcript-scroll-artifact-reveal, zoom-out-workspace-reveal - 10 rules: 3d-camera-flight, anchored-layout-expand, chart-scrub-readout, chromatic-glitch, control-target-sync, cursor-drag, gradient-text-sweep, multi-cursor-choreography, particle-burst, theme-crossfade-morph Both indexes updated. * feat(skills): sync product-launch script bank with mined blueprint roles The role->blueprint script bank in product-launch-video/story-design.md is kept 1:1 with blueprints-index role declarations, which the c2v mining pass expanded. Adds the 25 missing entries (script-shape descriptor + example lines + pattern): 13 for the 7 new blueprints, 12 for role widenings on 7 existing ones (cursor-ui-demo, dataviz-countup, titlecard-reveal, et al.), and states the 1:1 sync contract in the bank's intro. * docs(skills): cover constellation-hub scatter-drift variant in the script bank Review follow-up on #2680: the SOCIAL_PROOF constellation-hub entry patterned only the orbit shape; the c2v pass added a scatter-drift end-card variant with the opposite geometry (no hub, no ring). Adds an example line and extends the pattern so a scatter-drift beat's VO isn't steered toward the orbit shape.
This commit is contained in:
WaterrrForever
@@ -7,145 +7,91 @@ metadata:
|
||||
|
||||
# 3D Page Scroll
|
||||
|
||||
A webpage (or long content) presented as a tilted 3D card. Spring-eased scroll reveals specific sections while the static 3D perspective adds physical depth.
|
||||
A webpage (or long content) presented as a tilted 3D card. Spring-eased scroll reveals specific sections while the static 3D perspective adds physical depth. (For a camera that actually travels/tilts, see [3d-camera-flight.md](3d-camera-flight.md) — this rule's tilt never moves.)
|
||||
|
||||
## How It Works
|
||||
|
||||
Two independent transforms combine:
|
||||
|
||||
1. **3D tilt** — Static `rotateY` + `rotateX` with `perspective` on the card. The angle does **not** change during the scene.
|
||||
2. **Scroll** — The content inside the card translates vertically (`translateY` / `y` in GSAP) within a clipped container, driven by a GSAP tween. Spring-like deceleration via `ease: "power3.out"` or `"power4.out"`.
|
||||
1. **3D tilt** — static `rotateY` + `rotateX` with `perspective` on the card. The angle does **not** change during the scene.
|
||||
2. **Scroll** — the content inside the card translates vertically (`y` in GSAP) within a clipped container; spring-like deceleration via `power3.out` / `power4.out`.
|
||||
|
||||
Optional layer:
|
||||
Optional: **spotlight overlay** — a radial-gradient mask dims everything except a focal region after the scroll lands. It sits above the scrolling content, fixed relative to the card, never inside `.page-content`.
|
||||
|
||||
3. **Spotlight overlay** — A radial-gradient mask dims everything except a focal region after the scroll lands. Use to draw attention to one section.
|
||||
|
||||
For multi-step scrolling (scroll → pause → scroll), use multiple `tl.to(".page-content", { y: -<distance>, ... }, <position>)` calls at different timeline positions.
|
||||
|
||||
## HTML
|
||||
## Recipe
|
||||
|
||||
```html
|
||||
<div
|
||||
class="scene"
|
||||
id="page-scroll-scene"
|
||||
data-composition-id="page-scroll-scene"
|
||||
data-start="0"
|
||||
data-duration="5"
|
||||
data-track-index="0"
|
||||
>
|
||||
<div class="tilt-card">
|
||||
<div class="page-content">
|
||||
<!-- Full {Brand} webpage recreation, taller than card height so
|
||||
scrolling matters. Each section is real DOM, not a screenshot. -->
|
||||
<section class="page-hero">{heroContents}</section>
|
||||
<section class="page-features">{featuresContents}</section>
|
||||
<section class="page-target" id="target-section">{targetContents}</section>
|
||||
<section class="page-cta">{ctaContents}</section>
|
||||
</div>
|
||||
|
||||
<div class="spotlight"></div>
|
||||
<div class="tilt-card">
|
||||
<div class="page-content">
|
||||
<!-- Full {Brand} webpage recreation, taller than the card so scrolling
|
||||
matters. Each section is REAL DOM, not a screenshot — screenshots
|
||||
can't be individually highlighted or scrolled-to with precision. -->
|
||||
<section class="page-hero">{heroContents}</section>
|
||||
<section class="page-features">{featuresContents}</section>
|
||||
<section class="page-target" id="target-section">{targetContents}</section>
|
||||
<section class="page-cta">{ctaContents}</section>
|
||||
</div>
|
||||
<div class="spotlight"></div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## CSS (hero-frame layout)
|
||||
|
||||
```css
|
||||
.scene {
|
||||
position: relative;
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
}
|
||||
|
||||
.tilt-card {
|
||||
position: absolute;
|
||||
left: 50%;
|
||||
top: 50%;
|
||||
/* tilt + perspective set in CSS only if no other transform tween touches
|
||||
this element. If GSAP also tweens scale on .tilt-card, set the tilt
|
||||
via gsap.set() to avoid matrix overwrites. */
|
||||
/* tilt + perspective in CSS only if no other transform tween touches this
|
||||
element — if GSAP also tweens scale on .tilt-card, set the tilt via
|
||||
gsap.set() instead to avoid matrix overwrites */
|
||||
transform: translate(-50%, -50%) perspective({perspectivePx}) rotateY({tiltYDeg}) rotateX({tiltXDeg});
|
||||
transform-style: preserve-3d;
|
||||
width: {cardWidth};
|
||||
height: {cardHeight};
|
||||
border-radius: 24px;
|
||||
background: {cardBackgroundColor};
|
||||
overflow: hidden; /* clip the scrolling content */
|
||||
overflow: hidden; /* clip the scrolling content at the rounded corners */
|
||||
/* shadow X-offset sign must match tiltY sign (negative tiltY ⇒ positive X) */
|
||||
box-shadow: 40px 30px 80px rgba(0, 0, 0, 0.45);
|
||||
}
|
||||
|
||||
.page-content {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
left: 0;
|
||||
width: 100%;
|
||||
/* height is intrinsic from sections — taller than .tilt-card.height */
|
||||
/* height intrinsic from sections — taller than the card */
|
||||
}
|
||||
|
||||
.page-content section {
|
||||
height: {sectionHeight}; /* sections sized so cumulative offset = target distance */
|
||||
padding: 64px;
|
||||
/* section-specific styling … */
|
||||
}
|
||||
|
||||
.spotlight {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
pointer-events: none;
|
||||
opacity: 0;
|
||||
background: radial-gradient(
|
||||
ellipse 60% 35% at 50% 50%,
|
||||
transparent 50%,
|
||||
{spotlightDimColor} 100%
|
||||
);
|
||||
background: radial-gradient(ellipse 60% 35% at 50% 50%, transparent 50%, {spotlightDimColor} 100%);
|
||||
}
|
||||
```
|
||||
|
||||
## GSAP Timeline
|
||||
```js
|
||||
// SCROLL_DISTANCE is measured at design time from the real page layout
|
||||
// (top of .page-content origin to vertical center of #target-section,
|
||||
// accounting for card height) — NOT a free tunable.
|
||||
tl.to(
|
||||
".page-content",
|
||||
{ y: -SCROLL_DISTANCE, duration: SCROLL_DUR, ease: "power3.out" },
|
||||
SCROLL_AT,
|
||||
);
|
||||
|
||||
```html
|
||||
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
|
||||
<script>
|
||||
window.__timelines = window.__timelines || {};
|
||||
const tl = gsap.timeline({ paused: true });
|
||||
|
||||
// Phase 1 — Card enters (optional, can skip if card is in from t=0)
|
||||
// Phase 2 — Scroll to the target section.
|
||||
// SCROLL_DISTANCE is measured at design time from the page layout
|
||||
// (top of .page-content origin to vertical center of #target-section,
|
||||
// accounting for card height).
|
||||
tl.to(
|
||||
".page-content",
|
||||
{
|
||||
y: -SCROLL_DISTANCE,
|
||||
duration: SCROLL_DUR,
|
||||
ease: "power3.out",
|
||||
},
|
||||
SCROLL_AT,
|
||||
);
|
||||
|
||||
// Phase 3 — Spotlight fades in on the target after scroll settles
|
||||
tl.to(
|
||||
".spotlight",
|
||||
{
|
||||
opacity: 1,
|
||||
duration: SPOTLIGHT_FADE_DUR,
|
||||
ease: "power1.inOut",
|
||||
},
|
||||
SPOTLIGHT_AT,
|
||||
);
|
||||
|
||||
window.__timelines["page-scroll-scene"] = tl;
|
||||
</script>
|
||||
// Spotlight fades in on the target after the scroll settles.
|
||||
tl.to(
|
||||
".spotlight",
|
||||
{ opacity: 1, duration: SPOTLIGHT_FADE_DUR, ease: "power1.inOut" },
|
||||
SPOTLIGHT_AT,
|
||||
);
|
||||
```
|
||||
|
||||
### Multi-phase scroll variant
|
||||
## Variations
|
||||
|
||||
**Multi-step scroll (scroll → pause → scroll)** — multiple `y:` tweens at different positions. Distances are both measured from the `.page-content` origin (NOT delta from the previous step); GSAP composes successive `y:` tweens on the same property, each starting from the value the previous one left:
|
||||
|
||||
```js
|
||||
// Scroll to section A → hold → scroll to section B.
|
||||
// SCROLL_DISTANCE_A and SCROLL_DISTANCE_B are both measured from the
|
||||
// .page-content origin (NOT delta from previous step).
|
||||
tl.to(
|
||||
".page-content",
|
||||
{ y: -SCROLL_DISTANCE_A, duration: SCROLL_DUR, ease: "power3.out" },
|
||||
@@ -156,72 +102,34 @@ tl.to(
|
||||
{ y: -SCROLL_DISTANCE_B, duration: SCROLL_DUR, ease: "power3.out" },
|
||||
SCROLL_AT_B,
|
||||
);
|
||||
// SCROLL_AT_A + SCROLL_DUR ≤ SCROLL_AT_B — the two scrolls must not fight for y
|
||||
```
|
||||
|
||||
GSAP composes successive `y:` tweens additively when targeting the same property — each tween starts from the value left by the previous tween.
|
||||
## Values
|
||||
|
||||
## How to Choose Values
|
||||
|
||||
- **tiltYDeg** — static Y rotation in CSS (or via `gsap.set()`).
|
||||
- Range: -12 to -4 (left-leaning) or 4 to 12 (right-leaning); 0 = no perspective rotation.
|
||||
- Effects: bigger magnitude = more dramatic 3D; near 0 collapses to a flat panel.
|
||||
- Constraints: shadow X-offset sign must match (negative tiltY ⇒ positive box-shadow X).
|
||||
- **tiltXDeg** — static X rotation.
|
||||
- Range: 0-6
|
||||
- Effects: positive tilts the top edge away from the viewer.
|
||||
- **perspectivePx** — perspective distance.
|
||||
- Range: 800-2000 px
|
||||
- Effects: smaller = more dramatic foreshortening; larger = nearly orthographic.
|
||||
- **cardWidth / cardHeight** — card frame size.
|
||||
- Constraints: card height < total content height, otherwise scroll has nothing to reveal.
|
||||
- **sectionHeight** — height of each scrolled section.
|
||||
- Constraints: sum of all section heights ≥ cardHeight + SCROLL_DISTANCE so the target section ends up within frame after scroll.
|
||||
- **SCROLL_AT** — timeline second at which the scroll tween begins.
|
||||
- Constraints: must be ≥ end of any prior fade-in tweens on `.page-content`.
|
||||
- **SCROLL_DUR** — duration of one scroll tween.
|
||||
- Range: 0.8-1.8 s
|
||||
- Effects: shorter feels like a hard cut; longer feels programmatic.
|
||||
- **SCROLL_DISTANCE** — pixels to translate `.page-content` upward.
|
||||
- Constraints: measured once at design time from the target section's offset; NOT a free tunable.
|
||||
- **SPOTLIGHT_AT** — timeline second at which the spotlight begins fading in.
|
||||
- Constraints: should be ≥ SCROLL_AT + SCROLL_DUR (or slightly earlier for overlapping handoff) so the spotlight reveals the freshly-arrived section.
|
||||
- **SPOTLIGHT_FADE_DUR** — spotlight opacity fade-in duration.
|
||||
- Range: 0.4-0.8 s
|
||||
- Multi-phase variant — **SCROLL_AT_A / SCROLL_AT_B**: must satisfy `SCROLL_AT_A + SCROLL_DUR ≤ SCROLL_AT_B` so the two scrolls don't fight for the y property.
|
||||
|
||||
Ease family — discrete choice:
|
||||
|
||||
- `power3.out` — heavy deceleration; reads as a programmatic scroll that "lands". Default.
|
||||
- `power4.out` — even heavier; reads as a momentum-driven scroll.
|
||||
- `power2.inOut` — symmetric; reads as a cinematic camera pan rather than UI scroll.
|
||||
|
||||
Pick one and use it across all scrolls in the scene — mixing easings within one scene reads as jerky.
|
||||
|
||||
## Key Principles
|
||||
|
||||
- **Tilt is static**, not animated. The card holds its angle the whole scene.
|
||||
- **Shadow direction matches tilt**: a left-leaning card casts shadow to the right (positive X shadow offset). Mismatch breaks the 3D illusion.
|
||||
- **Page content is real HTML**, not a screenshot. Screenshots can't be individually highlighted or scrolled-to with precision.
|
||||
- **Use real layout for distances**: scroll target distance comes from the actual cumulative section heights, not estimated pixel values.
|
||||
- **Spotlight as overlay**, not inside the page-content — overlay sits above scrolling content and stays fixed relative to the card.
|
||||
| token | range / rule | notes |
|
||||
| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| tiltYDeg | −12 to −4 (left-leaning) or 4 to 12 | bigger = more dramatic 3D; near 0 collapses to a flat panel |
|
||||
| tiltXDeg | 0–6 | positive tilts the top edge away |
|
||||
| perspectivePx | 800–2000 px | smaller = more foreshortening; larger = nearly orthographic |
|
||||
| cardWidth / Height | card height < total content height | otherwise the scroll has nothing to reveal |
|
||||
| sectionHeight | Σ heights ≥ cardHeight + SCROLL_DISTANCE | so the target section lands within frame |
|
||||
| SCROLL_AT | ≥ end of prior tweens on `.page-content` | |
|
||||
| SCROLL_DUR | 0.8–1.8 s | shorter feels like a hard cut; longer feels programmatic |
|
||||
| SCROLL_DISTANCE | measured from the layout | from actual cumulative section heights — never estimated; don't overshoot content end |
|
||||
| SPOTLIGHT_AT | ≥ SCROLL_AT + SCROLL_DUR (or slightly earlier) | spotlight reveals the freshly-arrived section |
|
||||
| SPOTLIGHT_FADE_DUR | 0.4–0.8 s | |
|
||||
| Ease | `power3.out` default; `power4.out` momentum; `power2.inOut` cinematic pan | pick ONE for all scrolls in the scene — mixing easings reads as jerky |
|
||||
|
||||
## Critical Constraints
|
||||
|
||||
- **`overflow: hidden` on `.tilt-card`** — scrolling content must clip at card boundaries, otherwise it leaks past the rounded corners
|
||||
- **`transform-style: preserve-3d`** on `.tilt-card` — required for any 3D children (or for combining `perspective` with rotations cleanly)
|
||||
- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never `tl.play()` — HF seeks frame-by-frame
|
||||
- **Registry key = `data-composition-id`**: `window.__timelines["page-scroll-scene"]` must match scene root's `data-composition-id`
|
||||
- **Finite scroll distance** — compute from actual content geometry; don't use arbitrary values that may overshoot the content end
|
||||
- **Same easing across multi-phase scroll** — mixing `power3.out` and `power1.inOut` looks jerky; pick one for the scene
|
||||
- **Tilt is static** — the card holds its angle the whole scene.
|
||||
- **Shadow direction matches tilt** — a left-leaning card casts shadow to the right (positive X offset); mismatch breaks the 3D illusion.
|
||||
- **Page content is real HTML, not a screenshot**; scroll distances come from the real layout geometry.
|
||||
- **`overflow: hidden` + `transform-style: preserve-3d` on `.tilt-card`** — clip at the rounded corners; preserve-3d for any 3D children / clean perspective composition.
|
||||
- **Spotlight is an overlay above the scrolling content**, never inside `.page-content`.
|
||||
- **Same easing across a multi-phase scroll**, and non-overlapping scroll windows.
|
||||
|
||||
## Combinations
|
||||
## See also
|
||||
|
||||
- [asr-keyword-glow.md](asr-keyword-glow.md) — highlight elements on the page synced to voiceover word timestamps
|
||||
- [multi-phase-camera.md](multi-phase-camera.md) — overall camera zoom while the page scrolls (zoom-in to target section as it lands)
|
||||
- [cursor-click-ripple.md](cursor-click-ripple.md) — cursor lands on a UI element within the scrolled-into-view section
|
||||
|
||||
## Pairs with HF skills
|
||||
|
||||
- `/hyperframes-animation` — timeline + ease reference; `y:` tween basics
|
||||
- `/hyperframes-core` — composition wiring, `data-*` attributes
|
||||
- `/hyperframes-cli` — `hyperframes lint` to verify the registry key + duration
|
||||
[asr-keyword-glow.md](asr-keyword-glow.md) (on-page keyword highlight synced to VO) · [multi-phase-camera.md](multi-phase-camera.md) (camera zoom while the page scrolls) · [cursor-click-ripple.md](cursor-click-ripple.md) (cursor lands in the scrolled-into-view section) · [3d-camera-flight.md](3d-camera-flight.md) (when the camera itself should travel).
|
||||
|
||||
Reference in New Issue
Block a user