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

---
name: orbit-3d-entry
description: Elements flip in from 3D space then settle into continuous elliptical orbit around a focal point.
metadata:
  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

```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

```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

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

  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:

```js
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:

```css
.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](center-outward-expansion.md) — alternative entry pattern (burst, not orbit); also the reversed driver for an orbit-collapse finish
- [cursor-click-ripple.md](cursor-click-ripple.md) — pairs naturally when the center element is a CTA the user "clicks" to trigger the collapse
- [sine-wave-loop.md](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`