hyperframes/skills/hyperframes-animation/rules/orbit-3d-entry.md

name, description, metadata

name	description	metadata
orbit-3d-entry	Elements flip in from 3D space then settle into continuous elliptical orbit around a focal point.	tags orbit, 3d, flip, ellipse, circular, icon, entry, continuous

Orbit with 3D Entry

Elements flip in from 3D space (rotateX + rotateY + translateZ) then transition into a continuous elliptical orbit around a focal point. Distinct from one-shot reveals — the orbit keeps running.

How It Works

Two phases per element:

1. Entry (per element): GSAP tween from hidden 3D orientation (rotateX, rotateY, negative z) to flat (rotateX: 0, rotateY: 0, z: 0). Spring-like ease (back.out) for the flip-in.
2. Orbit (after entry): Continuous trigonometric position around a center point. The element's x and y translate are driven by cos(t) and sin(t) at a slow angular speed.

The orbit runs inside the timeline — not via requestAnimationFrame — so HF seek-by-frame stays deterministic.

HTML

<div
  class="scene"
  id="orbit-scene"
  data-composition-id="orbit-scene"
  data-start="0"
  data-duration="5"
  data-track-index="0"
>
  <div class="orbit-stage">
    <div class="orbit-item" data-angle="0">{glyph1}</div>
    <div class="orbit-item" data-angle="60">{glyph2}</div>
    <div class="orbit-item" data-angle="120">{glyph3}</div>
    <div class="orbit-item" data-angle="180">{glyph4}</div>
    <div class="orbit-item" data-angle="240">{glyph5}</div>
    <div class="orbit-item" data-angle="300">{glyph6}</div>
    <div class="orbit-center">{centerLabel}</div>
  </div>
</div>

CSS

.scene {
  position: relative;
  width: 100%;
  height: 100%;
  display: grid;
  place-items: center;
  background: {sceneBackground};
  perspective: 1800px; /* REQUIRED — without perspective, rotateX/Y flatten */
}
.orbit-stage {
  position: relative;
  width: 1000px;
  height: 700px;
  display: grid;
  place-items: center;
  transform-style: preserve-3d;
}
.orbit-item {
  position: absolute;
  /* Items live at stage center; GSAP translates them along the orbit. */
  top: 50%;
  left: 50%;
  width: 140px;
  height: 140px;
  display: grid;
  place-items: center;
  background: {accentColor};
  border-radius: 50%;
  font-family: {font};
  font-weight: 900;
  font-size: 64px;
  color: {itemTextColor};
  transform-style: preserve-3d;
  will-change: transform;
  box-shadow: 0 12px 36px {accentShadowColor};
}
.orbit-center {
  position: relative;
  z-index: 5;
  font-family: {font};
  font-weight: 900;
  font-size: 96px;
  letter-spacing: 8px;
  color: {centerTextColor};
  text-transform: uppercase;
}

GSAP Timeline

<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 });

  const items = document.querySelectorAll(".orbit-item");
  // RADIUS_X, RADIUS_Y, ORBIT_DURATION, ENTRY_DUR, STAGGER, FLIP_BACK, CENTER_BACK
  // — all named constants; values per "How to Choose Values" below.
  const RADIUS_Y = RADIUS_X * Y_TO_X_RATIO; // perspective-flattened ellipse

  items.forEach((el, i) => {
    const initialAngleDeg = Number(el.dataset.angle);
    const initialAngleRad = (initialAngleDeg / 360) * Math.PI * 2;
    const startX = Math.cos(initialAngleRad) * RADIUS_X;
    const startY = Math.sin(initialAngleRad) * RADIUS_Y;

    // 1) Place at orbital position with opacity 0 — BEFORE any tween fires
    gsap.set(el, {
      xPercent: -50,
      yPercent: -50,
      x: startX,
      y: startY,
      rotateX: ROTATE_X_FROM,
      rotateY: ROTATE_Y_FROM,
      z: Z_FROM,
      opacity: 0,
      scale: SCALE_FROM,
    });

    // 2) Phase 1 — flip in IN PLACE at orbital position
    tl.to(
      el,
      {
        rotateX: 0,
        rotateY: 0,
        z: 0,
        opacity: 1,
        scale: 1,
        duration: ENTRY_DUR,
        ease: `back.out(${FLIP_BACK})`,
      },
      i * STAGGER,
    );

    // 3) Phase 2 — continuous orbit driven via a 0→1 progress tween
    const orbitState = { p: 0 };
    tl.to(
      orbitState,
      {
        p: 1,
        duration: ORBIT_DURATION,
        ease: "none",
        onUpdate: () => {
          const angle = initialAngleRad + orbitState.p * Math.PI * 2;
          const x = Math.cos(angle) * RADIUS_X;
          const y = Math.sin(angle) * RADIUS_Y;
          // z-index by orbit Y — see "Center label clearance" in Key Principles
          // for the capped-range form when a center label is present.
          el.style.zIndex = String(Math.round(y + RADIUS_Y));
          el.style.transform = `translate(-50%, -50%) translate(${x}px, ${y}px)`;
        },
      },
      i * STAGGER + ENTRY_DUR,
    );
  });

  // Center label fades in once a few orbit items have landed
  tl.from(
    ".orbit-center",
    { opacity: 0, scale: 0.6, duration: ENTRY_DUR, ease: `back.out(${CENTER_BACK})` },
    CENTER_FADE_AT,
  );

  window.__timelines["orbit-scene"] = tl;
</script>

How to Choose Values

• RADIUS_X — horizontal radius of the orbit ellipse, in px

  • Range: 300–900 px
  • Effects: small radius reads as a tight cluster; large radius spreads the ring across the frame and lets a large center element breathe
  • Constraints: must clear the center element horizontally at every angle — see Key Principles for the RADIUS_X * min(|cos(θ)|) ≥ L_w + I_w + breathing_room rule
  • Reference: examples/cta-orbit-collapse.html uses 480

• Y_TO_X_RATIO — RADIUS_Y / RADIUS_X, the orbit's perspective flattening

  • Range: 0.4–0.7
  • Effects: low values read as a near-horizontal disc seen from above; values approaching 1 read as a flat plane facing the camera
  • Constraints: keep < 1 — the orbit should look like a tilted ring, not a frontal halo
  • Reference: examples/cta-orbit-collapse.html uses ≈ 0.58

• ORBIT_DURATION — seconds for one full revolution

  • Range: 4–25 s (longer for ambient backdrop, shorter for active feature motion)
  • Effects: short durations look frenetic; long durations read as drifting / calm
  • Constraints: must be ≥ the time the orbit is on screen, otherwise the tween ends and items stop
  • Reference: examples/cta-orbit-collapse.html uses ~25 s effective (orbit speed 0.25 rad/s)

• ENTRY_DUR — per-element flip-in duration

  • Range: 0.4–0.8 s
  • Effects: short feels punchy; long feels stately
  • Constraints: must be ≤ the gap between the first and last element's start so the cascade doesn't overlap to incoherence
  • Reference: examples/cta-orbit-collapse.html uses 0.55 s

• STAGGER — delay between consecutive element entries

  • Range: 0.06–0.12 s
  • Effects: below ~0.06 s reads as "popcorn"; above ~0.12 s reads as plodding
  • Constraints: total cascade (n - 1) * STAGGER should still complete before the next scene phase begins
  • Reference: examples/cta-orbit-collapse.html uses 0.10 s

• FLIP_BACK — back.out(<n>) overshoot for the flip-in

  • Range: 1.2–2.0
  • Effects: low end is a soft arrive; high end snaps with visible overshoot
  • Constraints: pair with a calmer CENTER_BACK if both fire close together — competing overshoots cancel each other
  • Reference: examples/cta-orbit-collapse.html uses 1.4

• CENTER_BACK — back.out(<n>) overshoot for the center label fade-in

  • Range: 1.2–1.8
  • Effects: low end keeps the label calm under the busy orbit; high end gives it a small "pop" of arrival
  • Reference: examples/cta-orbit-collapse.html uses 1.4

• CENTER_FADE_AT — when the center label fades in, in seconds

  • Range: just after the first 2–4 elements have landed
  • Effects: too early competes with the cascade; too late leaves a hole at the center of the orbit
  • Reference: examples/cta-orbit-collapse.html starts the center brand near the front of the scene

• ROTATE_X_FROM / ROTATE_Y_FROM / Z_FROM / SCALE_FROM — initial 3D orientation

  • Range: rotateX ±60° to ±120°; rotateY ±45° to ±120°; z −200 to −400; scale 0.2–0.6
  • Effects: higher absolute rotation + deeper negative z = more dramatic "card flipping out of depth"; lower = subtle reorientation
  • Constraints: pick a direction consistent with the scene's perspective; mixing positive and negative rotateY across items reads as noise
  • Reference: examples/cta-orbit-collapse.html uses rotateX 90, rotateY −45, z −100, scale 0

Variations

Collapse to center

To reverse — orbit then collapse inward — interpolate RADIUS_X and RADIUS_Y to 0 in a final phase by multiplying both radii by a 1→0 driver:

const collapse = { r: 1 };
tl.to(
  collapse,
  {
    r: 0,
    duration: COLLAPSE_DUR,
    ease: "power3.inOut",
    onUpdate: () =>
      items.forEach((el) => {
        const a = (Number(el.dataset.angle) / 360) * Math.PI * 2;
        const x = Math.cos(a) * RADIUS_X * collapse.r;
        const y = Math.sin(a) * RADIUS_Y * collapse.r;
        el.style.transform = `translate(-50%,-50%) translate(${x}px,${y}px) scale(${collapse.r})`;
      }),
  },
  COLLAPSE_AT,
);

Tilted orbit plane

For a more dramatic 3D orbit, rotate the entire .orbit-stage on the X axis:

.orbit-stage {
  transform: rotateX(25deg);
}

Items rendered above/below the equator visually arc through the plane.

Key Principles

• perspective on scene root REQUIRED — without it, rotateX/Y read as 2D scale and the flip-in looks flat
• transform-style: preserve-3d on both the stage and each item — preserves the 3D context as items have their own transforms
• Stagger entries — cascade reads as "swarm forming," simultaneous reads as "popcorn." See STAGGER in How to Choose Values
• Element count 4-12 — fewer feels empty, more crowds the center
• ❗ Center label clearance — translateZ + capped item z-index — z-index ALONE is unreliable inside a transform-style: preserve-3d stage (paint order follows Z position, not stacking-context z-index). For the orbit to NEVER occlude the headline:
  1. Push the center label forward: transform: translateZ(220px); z-index: 9999;
  2. Cap orbit-item dynamic z-index in [1, 50] so bottom-of-orbit items still read as "in front of" top-of-orbit items, but never above the center label. e.g.: el.style.zIndex = String(1 + Math.round((y + RADIUS_Y) / (2 * RADIUS_Y) * 49));
  3. Choose RADIUS_X so items also clear the center label HORIZONTALLY at all angles. If the label's half-width is L_w and the item's half-width is I_w, then RADIUS_X must satisfy RADIUS_X * min(|cos(θ_minimum)|) ≥ L_w + I_w + breathing_room. For a 6-item orbit with 60° angular spacing, the worst case is cos(30°) ≈ 0.866 between items. Scale RADIUS_X with the center label's width — a heavier wordmark needs a wider ring.
• ❗ Center element is the headline — the orbit is ornamental motion around it. If the orbit dominates the eye, increase center element size or fade orbit items down

Critical Constraints

• No requestAnimationFrame — orbit must run inside the timeline so HF seeks frame-by-frame deterministically

• Timeline must be paused: gsap.timeline({ paused: true })

• Registry key = data-composition-id

• Each item gets its OWN orbit tween — don't share one tween with targets: '.orbit-item' because each starts at a different initialAngle

• will-change: transform — many simultaneous orbital transforms benefit from compositor hints

• Don't animate left/top — use translate() (composes with translate(-50%, -50%) centering)

• ❗ Entry must flip IN PLACE at orbital position, NOT at center — a fromTo whose "from" and "to" both have x: 0, y: 0 keeps the item at the stage center during phase 1, so it collides with the center label during flip-in (and then snaps to orbit on phase 2 start — a visible teleport).

  The correct pattern (see GSAP Timeline above) is to gsap.set() each item at (cos(initialAngle)*RADIUS_X, sin(initialAngle)*RADIUS_Y) with opacity: 0 BEFORE adding tweens, then have phase 1 animate only rotation/opacity/scale — NOT translate. The item fades in IN PLACE at its orbital starting point, and phase 2 picks up the orbit smoothly from there.

Combinations

• center-outward-expansion.md — alternative entry pattern (burst, not orbit); also the reversed driver for an orbit-collapse finish
• cursor-click-ripple.md — pairs naturally when the center element is a CTA the user "clicks" to trigger the collapse
• sine-wave-loop.md — per-item idle wobble layered on top of the orbit

Pairs with HF skills

• /hyperframes-animation — timeline + onUpdate API
• /hyperframes-core — composition wiring
• /hyperframes-cli — hyperframes lint