takomi 2.1.40 → 2.1.42

package/assets/.agent/skills/hyperframes-animation/rules/sine-wave-loop.md

@@ -0,0 +1,278 @@
+---
+name: sine-wave-loop
+description: Bounded sine-driven idle — subtle jitter or a single genuinely-needed bounded ambient breath on a held element. De-emphasized: circular breathing as "aliveness" is cheap; prefer sequential reveal timed to the VO, then subtle jitter, before reaching here.
+metadata:
+  tags: idle, jitter, bounded-ambient, sine, trigonometry, low-amplitude, post-entry
+---
+
+# Sine Wave Loop (subtle jitter / bounded ambient)
+
+> **Reach for this last.** Per the motion doctrine (`references/motion-language.md`): **circular breathing — scaling text/cards up and down to look "alive" — is cheap, the agent's reflexive cheat, and reads weak.** "I'd rather have NO motion than BAD motion." Before using this rule to keep a held frame alive, prefer (1) **sequential reveal timed to the voiceover** — reveal the next line/element when the VO says it, across the back ~50% of the scene; that, not ambient motion, is what fills a shot. If a frame has genuinely settled and still needs a touch of life, the **sanctioned move is subtle jitter** — a small, low-amplitude jitter (this rule, at the LOW end of its amplitude range). A full breathing loop is reserved for the rare case where a single held hero genuinely needs bounded ambient; keep it de-emphasized and small.
+
+Keeps a settled element from feeling dead — as **subtle jitter** or, rarely, a single bounded ambient breath — using `Math.sin` driven by a finite timeline tween. This is the implementation behind the "subtle jitter" move in the motion vocabulary; it is **not** a license to breathe every hero.
+
+## How It Works
+
+A long tween advances a `phase` value from 0 → 2π (or 0 → some multiple thereof). On every onUpdate, the phase feeds into `Math.sin()` to produce a small periodic offset added to the element's transform (`scale`, `translateY`, `rotate`).
+
+The trick to a "no jump" transition from entry to idle: at `phase = 0`, `sin(0) = 0` — the offset is zero, so the element starts at its post-entry resting state.
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="idle-scene"
+  data-composition-id="idle-scene"
+  data-start="0"
+  data-duration="6"
+  data-track-index="0"
+>
+  <div class="stack">
+    <div class="hero" id="hero">{HeroLabel}</div>
+    <div class="dot" id="dot"></div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgGradient};
+}
+.stack {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: STACK_GAP;
+}
+.hero {
+  font-family: {font};
+  font-weight: 900;
+  font-size: HERO_FONT_SIZE;
+  letter-spacing: HERO_LETTER_SPACING;
+  color: {textColor};
+  text-transform: uppercase;
+  /* Element gets its post-entry resting transform; idle only ADDS to it */
+  will-change: transform;
+}
+.dot {
+  width: DOT_SIZE;
+  height: DOT_SIZE;
+  border-radius: 50%;
+  background: {accentColor};
+  box-shadow: {accentGlow};
+}
+```
+
+## 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 hero = document.getElementById("hero");
+  const dot = document.getElementById("dot");
+
+  // Phase 1 — entry beat (e.g. headline fade-up)
+  tl.fromTo(
+    hero,
+    { opacity: 0, y: ENTRY_Y, scale: ENTRY_SCALE },
+    { opacity: 1, y: 0, scale: 1, duration: ENTRY_DUR, ease: "power3.out" },
+    0,
+  );
+  tl.fromTo(
+    dot,
+    { opacity: 0, scale: 0 },
+    { opacity: 1, scale: 1, duration: DOT_ENTRY_DUR, ease: `back.out(${BOUNCE_FACTOR})` },
+    DOT_ENTRY_START,
+  );
+
+  // Phase 2 — idle breathing. Starts at IDLE_START_TIME AFTER entry settles.
+  // Drive a phase 0 → 2π * CYCLES via a single tween, write sin() into transforms.
+
+  const phase = { p: 0 };
+  tl.to(
+    phase,
+    {
+      p: Math.PI * 2 * CYCLES,
+      duration: IDLE_DUR,
+      ease: "none",
+      onUpdate: () => {
+        // Hero: scale breathes ±SCALE_AMP, y bobs ±Y_AMP_PX
+        const scale = 1 + Math.sin(phase.p) * SCALE_AMP;
+        const y = Math.sin(phase.p) * Y_AMP_PX;
+        hero.style.transform = `translateY(${y}px) scale(${scale})`;
+
+        // Dot: out-of-phase scale (offset by π/2) — feels alive vs synced
+        const dotScale = 1 + Math.sin(phase.p + Math.PI / 2) * DOT_SCALE_AMP;
+        dot.style.transform = `scale(${dotScale})`;
+      },
+    },
+    IDLE_START_TIME,
+  );
+
+  window.__timelines["idle-scene"] = tl;
+</script>
+```
+
+## Variations
+
+### Multiple offset frequencies (organic multi-octave breathing)
+
+Combining frequencies feels more alive than pure sine:
+
+```js
+const primary = Math.sin(phase.p) * SCALE_AMP_PRIMARY;
+const secondary = Math.sin(phase.p * OCTAVE_RATIO) * SCALE_AMP_SECONDARY; // higher-frequency overlay
+const scale = 1 + primary + secondary;
+```
+
+### Conditional activation (only after entry settles)
+
+If entry is interactive or skippable, gate the idle:
+
+```js
+const idleActive = entryProgress >= GATE_THRESHOLD;
+const scale = idleActive ? 1 + Math.sin((time - IDLE_START_TIME) / PERIOD) * SCALE_AMP : 1;
+```
+
+### Settle and fade (long-idle gate — strongly recommended when `IDLE_DUR > 6s`)
+
+Drive amplitude through an envelope that fades to zero over the last ~20% of idle, so the scene visibly settles before the inter-scene transition lands:
+
+```js
+const phase = { p: 0 };
+const FADE_FRAC = 0.2; // last 20% of idle = amplitude ramps to 0
+tl.to(
+  phase,
+  {
+    p: Math.PI * 2 * CYCLES,
+    duration: IDLE_DUR,
+    ease: "none",
+    onUpdate: () => {
+      const t = phase.p / (Math.PI * 2 * CYCLES); // 0 → 1 across idle
+      const env = t < 1 - FADE_FRAC ? 1 : (1 - t) / FADE_FRAC; // 1 → 0 in tail
+      const scale = 1 + Math.sin(phase.p) * SCALE_AMP * env;
+      const y = Math.sin(phase.p) * Y_AMP_PX * env;
+      hero.style.transform = `translateY(${y}px) scale(${scale})`;
+    },
+  },
+  IDLE_START_TIME,
+);
+```
+
+The element is in motion for the first 80% of idle, then comes to rest in the last 20%. Pairs naturally with break-boundary Tier-B transitions (the outgoing visual is static when the crossfade/push begins).
+
+### Period vs cycle math
+
+For an exact cycle of N seconds:
+
+```js
+const divisor = (idleDurationSec * fps) / (Math.PI * 2);
+const value = Math.sin(frame / divisor) * amplitude;
+```
+
+For HF (`onUpdate` doesn't expose frame directly), use the tween's `phase` value: drive `p: Math.PI * 2 * cyclesWanted` over `duration: idleDurationSec`.
+
+## How to Choose Values
+
+### Layout / typography
+
+- **STACK_GAP** — vertical gap between hero and dot.
+  - Range: 0.2-0.4× `HERO_FONT_SIZE`
+- **HERO_FONT_SIZE / HERO_LETTER_SPACING** — typographic emphasis.
+  - Range: 100-240 px for full-bleed compositions; spacing 0.04-0.06em
+- **DOT_SIZE** — accent indicator size.
+  - Range: ~0.15-0.25× `HERO_FONT_SIZE` so the dot reads as accent, not a peer
+- **{accentGlow}** — `box-shadow` halo on the dot; typically `0 0 (DOT_SIZE) rgba(accentColor, 0.5-0.7)`
+
+### Entry phase
+
+- **ENTRY_Y / ENTRY_SCALE** — initial state before fade-up.
+  - Range: `ENTRY_Y` 16-32 px (subtle rise), `ENTRY_SCALE` 0.94-0.98 (subtle inflation)
+- **ENTRY_DUR** — hero fade-up duration.
+  - Range: 0.6-1.2s; bigger heroes want a longer settle
+- **DOT_ENTRY_START** — when the dot pops in relative to hero.
+  - Constraints: typically `≈ 0.4-0.6× ENTRY_DUR` so the dot lands while the hero is still settling, not after
+- **DOT_ENTRY_DUR** — dot back-out pop duration.
+  - Range: 0.4-0.7s
+- **BOUNCE_FACTOR** — `back.out(BOUNCE_FACTOR)` overshoot strength on the dot pop.
+  - Range: 1.4 (soft) → 2.0 (firm) → 2.8 (cartoony)
+
+### Idle phase
+
+- **IDLE_START_TIME** — when breathing begins.
+  - Constraints: `≥ ENTRY_DUR + small buffer (~0.1s)` so the breath doesn't fight the entry tail. `sin(0) = 0` at this moment, so the offset is exactly the entry's resting state — no jump
+- **IDLE_DUR** — breath tween length.
+  - Constraints: must equal `TOTAL_DURATION − IDLE_START_TIME` to fill the composition with motion
+- **CYCLES** — number of full breath cycles across `IDLE_DUR`.
+  - Range: `IDLE_DUR / 3s ≤ CYCLES ≤ IDLE_DUR / 1.5s` (cycle period 1.5-3s reads as natural breathing)
+- **SCALE_AMP** — sine amplitude on scale (hero).
+  - **Default: 0.008-0.015** (barely-perceptible breath — the right answer for most scenes)
+  - Push to 0.02-0.04 only when the element is **alone on canvas**, the scene is **short (< 6s)**, or the brief explicitly calls for **kinetic / playful** register
+  - See Key Principles for the long-idle / concurrent-element scaling rules
+- **Y_AMP_PX** — sine amplitude on y translation (hero).
+  - **Default: 2-3 px** (barely-perceptible — the right answer for most scenes)
+  - Push to 4-6 px only when isolated / short / kinetic — same gating as `SCALE_AMP`
+- **DOT_SCALE_AMP** — sine amplitude on dot scale (offset by π/2 for out-of-phase motion).
+  - Range: 0.04-0.12 — larger than hero amplitude is fine because the dot is a small accent
+- **PERIOD** (conditional-activation variation) — seconds per cycle when using the `(time - IDLE_START_TIME) / PERIOD` form.
+  - Range: 1.5-3s
+- **GATE_THRESHOLD** (conditional-activation variation) — entryProgress required to start idle.
+  - Range: 0.85-1.0; lower gates start idle slightly before entry completes for an overlap
+
+### Multi-octave variation
+
+- **SCALE_AMP_PRIMARY / SCALE_AMP_SECONDARY** — amplitudes of the two stacked sines.
+  - Constraints: `SCALE_AMP_PRIMARY > SCALE_AMP_SECONDARY` (secondary is a higher-frequency overlay, not a peer); combined max amplitude should stay within the SCALE_AMP range above
+- **OCTAVE_RATIO** — frequency multiplier of secondary relative to primary.
+  - Range: 2.0-4.0 (whole-number-ish ratios feel musical/coherent; non-integer ratios feel organic/unpredictable)
+
+### Color tokens
+
+- **{bgGradient}** — typically a dark radial gradient so the lit hero pops
+- **{textColor}** — high-contrast against `{bgGradient}`
+- **{accentColor}** — single accent reserved for the dot; the glow color in `{accentGlow}` is the same hue
+
+## Key Principles
+
+- **Prefer reveal, then jitter, then breath** — circular breathing as "aliveness" is cheap and reads weak; "no motion over bad motion." First fill the back of a shot with **sequential reveal timed to the VO**; if it's genuinely settled and still feels dead, use this rule at the **LOW end of its amplitude range as subtle jitter**; a full breathing loop is the rare last resort on a single held hero, never stamped on every element.
+- **`sin(0) = 0`** — at the moment idle begins, the offset must be zero so there's no visible jump from the entry's settled state to idle. Start the phase tween at `phase = 0`.
+- **Amplitude subtlety — default to the LOW end of the range.** Scale `0.008-0.015` (push to 0.02-0.04 only when isolated / short scene / kinetic brief), rotation `±0.3-0.8°` (rarely needed at all), translation `±2-3px` (push to 4-6px only when isolated). Bigger and idle reads as "still animating" instead of "alive but resting" — and a viewer watching 5+ consecutive scenes at the upper end will read the whole film as "shimmering."
+- **Cycle duration: 2.5-4s per breath when idle is long, 1.5-3s otherwise** — 2.5-3s is a comfortable breathing cadence; under 1.5s feels frantic in a long-idle window; over 4s feels lifeless in a short one.
+- **Long idle window (`IDLE_DUR > 6s` OR idle proportion > 30% of composition):** halve `SCALE_AMP` and `Y_AMP_PX`, slow `CYCLES` so each breath is 3-4s. Consider gating amplitude to fade to zero over the last ~20% of idle so the scene actually **settles before the transition**, instead of handing off mid-drift. This is the single biggest fix when finalize snapshots show "everything's still moving at the end."
+- **Concurrent idle on N elements** (triptych columns, card grid, multi-stat row, side-by-side panels): per-element amplitude ≤ default `/ √N`. Three columns each at `±6px` visually adds to `±18px+` of competing motion; three at `±2-3px` reads as one collective breath. Stagger the **period** between elements (2.1s / 1.9s / 2.4s) for organic feel — but the **amplitude** must also be smaller, not just the period.
+- **Different elements at different phases** — offset secondary elements by `Math.PI / 2` (90° offset) so they're not all moving in sync. Synced motion looks mechanical; out-of-phase looks alive.
+- **Compose, don't replace** — idle motion ADDS to the element's resting transform, not replace it. If the entry settled at `translateY(0)`, idle should produce `translateY(0 + sin*4)`. Don't overwrite the entry's final translation.
+- **❗ Don't use CSS `@keyframes` for the idle loop** — CSS animation runs on the browser's render clock, which is independent of the HF seek clock. HF seeks frame-by-frame and a CSS-driven idle will flicker/desync. Drive idle inside the GSAP timeline.
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No CSS `animation`** for idle — must be timeline-driven
+- **`will-change: transform`** if the idle compounds with other tweens on the same element
+- **Phase tween `ease: 'none'`** — sine itself provides the easing; tweening the phase non-linearly produces non-sinusoidal motion
+- **Don't restart the idle tween** — it's a single long tween from start to end of composition idle window
+
+## Combinations
+
+- After [press-release-spring.md](press-release-spring.md) — button idle-breathes after release settles
+- After [counting-dynamic-scale.md](counting-dynamic-scale.md) — final number breathes
+- After [card-morph-anchor.md](card-morph-anchor.md) — settled card idle-bobs
+- After [orbit-3d-entry.md](orbit-3d-entry.md) — center label idle-breathes while items orbit
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — `onUpdate` writing transform
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`

package/assets/.agent/skills/hyperframes-animation/rules/split-tilt-cards.md

@@ -0,0 +1,277 @@
+---
+name: split-tilt-cards
+description: Two cards side-by-side with opposing Y-rotation creating a symmetric 3D split-screen layout for comparisons or feature pairs.
+metadata:
+  tags: 3d, cards, split, tilt, comparison, symmetric, layout
+---
+
+# Split Tilt Cards
+
+Two cards positioned side-by-side, each rotated in opposite Y directions. Creates a symmetric "book-open" 3D effect — natural fit for comparisons, before/after, or feature pairs.
+
+## How It Works
+
+- Left card rotates `+Y` (faces toward the right viewer angle)
+- Right card rotates `-Y` (faces toward the left viewer angle)
+- Both share the same `perspective` parent → opposing rotations balance visually
+- Each card enters from outside (left card slides in from the left, right card from the right) to reinforce its identity
+- Idle phase: gentle counter-phase float (`Math.PI` offset on sine) — cards bob in opposition
+
+## HTML
+
+```html
+<div
+  class="scene"
+  id="split-scene"
+  data-composition-id="split-scene"
+  data-start="0"
+  data-duration="4"
+  data-track-index="0"
+>
+  <div class="split-stage">
+    <div class="card card-left">
+      <div class="card-eyebrow">{leftEyebrow}</div>
+      <div class="card-headline">{leftHeadline}</div>
+      <div class="card-body">{leftBody}</div>
+    </div>
+    <div class="card card-right">
+      <div class="card-eyebrow">{rightEyebrow}</div>
+      <div class="card-headline">{rightHeadline}</div>
+      <div class="card-body">{rightBody}</div>
+    </div>
+  </div>
+</div>
+```
+
+## CSS
+
+```css
+.scene {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  display: grid;
+  place-items: center;
+  background: {bgGradient};
+  perspective: SCENE_PERSPECTIVE; /* REQUIRED — without perspective rotateY flattens */
+}
+.split-stage {
+  display: flex;
+  gap: STAGE_GAP;
+  transform-style: preserve-3d;
+}
+.card {
+  width: CARD_WIDTH;
+  min-height: CARD_MIN_HEIGHT;
+  padding: CARD_PADDING;
+  display: flex;
+  flex-direction: column;
+  gap: CARD_INNER_GAP;
+  border-radius: CARD_RADIUS;
+  background: {cardSurface};
+  border: 1px solid {cardBorder};
+  color: {textColor};
+  font-family: {font};
+  transform-style: preserve-3d;
+  will-change: transform;
+}
+.card-left {
+  /* Faces right → shadow falls right */
+  box-shadow:
+    -CARD_SHADOW_OFFSET CARD_SHADOW_DROP CARD_SHADOW_BLUR {shadowColor},
+    0 0 CARD_GLOW_BLUR {accentGlowColor};
+}
+.card-right {
+  /* Faces left → shadow falls left */
+  box-shadow:
+    CARD_SHADOW_OFFSET CARD_SHADOW_DROP CARD_SHADOW_BLUR {shadowColor},
+    0 0 CARD_GLOW_BLUR {accentGlowColor};
+}
+.card-eyebrow {
+  font-size: EYEBROW_FONT_SIZE;
+  font-weight: 800;
+  letter-spacing: EYEBROW_LETTER_SPACING;
+  text-transform: uppercase;
+  color: {accentColor};
+}
+.card-headline {
+  font-size: HEADLINE_FONT_SIZE;
+  font-weight: 900;
+  line-height: 1;
+  letter-spacing: HEADLINE_LETTER_SPACING;
+}
+.card-body {
+  font-size: BODY_FONT_SIZE;
+  font-weight: 500;
+  line-height: 1.3;
+  color: {bodyColor};
+  opacity: BODY_OPACITY;
+}
+```
+
+## 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 });
+
+  // Phase 1 — entry from outside
+  tl.fromTo(
+    ".card-left",
+    { x: -ENTRY_SLIDE_DIST, rotateY: TILT + TILT_OVERSHOOT, opacity: 0 },
+    { x: 0, rotateY: TILT, opacity: 1, duration: ENTRY_DUR, ease: "power3.out" },
+    LEFT_AT,
+  );
+  tl.fromTo(
+    ".card-right",
+    { x: ENTRY_SLIDE_DIST, rotateY: -TILT - TILT_OVERSHOOT, opacity: 0 },
+    { x: 0, rotateY: -TILT, opacity: 1, duration: ENTRY_DUR, ease: "power3.out" },
+    RIGHT_AT,
+  );
+
+  // Phase 2 — counter-phase idle bob (cards move in opposition for dynamism)
+  tl.to(
+    ".card-left",
+    { y: -FLOAT_AMP, duration: FLOAT_DURATION / 2, ease: "sine.inOut", yoyo: true, repeat: 1 },
+    IDLE_START,
+  );
+  tl.to(
+    ".card-right",
+    { y: FLOAT_AMP, duration: FLOAT_DURATION / 2, ease: "sine.inOut", yoyo: true, repeat: 1 },
+    IDLE_START,
+  );
+
+  // Phase 3 — gentle copy reveal (body slides up + fades after cards arrive)
+  tl.from(
+    ".card-eyebrow, .card-headline, .card-body",
+    { opacity: 0, y: COPY_RISE, stagger: COPY_STAGGER, duration: COPY_DUR, ease: "power2.out" },
+    COPY_REVEAL_AT,
+  );
+
+  window.__timelines["split-scene"] = tl;
+</script>
+```
+
+## How to Choose Values
+
+### Layout / typography
+
+- **SCENE_PERSPECTIVE** — perspective on the scene root.
+  - Range: 1000-2400 px
+  - Effects: lower exaggerates the tilt (more cone-like); higher reads as a near-isometric, flatter rotation
+- **STAGE_GAP** — horizontal gap between the two cards.
+  - Range: 40-120 px (≈0.06-0.15× `CARD_WIDTH`)
+  - Effects: small gap reads "fused pair"; large gap reads "compared but separate"
+- **CARD_WIDTH** — width of each card.
+  - Range: 480-820 px at 1920×1080
+  - Constraints: `2 * CARD_WIDTH + STAGE_GAP ≤ 0.95 * stageWidth` so both cards stay on-screen at full tilt
+- **CARD_MIN_HEIGHT** — minimum card height.
+  - Range: ≈0.75-1.05× `CARD_WIDTH` (square-ish reads as balanced; very tall reads as poster)
+- **CARD_PADDING / CARD_INNER_GAP / CARD_RADIUS** — interior chrome.
+  - Range: padding 40-72 px; inner gap 24-48 px; radius 24-40 px
+- **CARD_SHADOW_OFFSET / CARD_SHADOW_DROP / CARD_SHADOW_BLUR** — drop-shadow geometry.
+  - Constraints: offset's sign matches tilt direction (see Key Principles); drop > 0 grounds the card on the scene
+  - Range: offset 16-28 px; drop 20-32 px; blur 40-80 px
+- **CARD_GLOW_BLUR** — secondary inner glow blur radius (`box-shadow` 0 0 blur).
+  - Range: 16-32 px (subtle accent rim; larger competes with the card content)
+- **EYEBROW_FONT_SIZE / EYEBROW_LETTER_SPACING** — small uppercase label.
+  - Range: 22-32 px; spacing 6-12 px (uppercase reads cleaner with positive letter-spacing)
+- **HEADLINE_FONT_SIZE / HEADLINE_LETTER_SPACING** — the main one-line punch.
+  - Range: 72-104 px at 1920×1080; spacing -1 to -3 px (tight tracking for display weight)
+- **BODY_FONT_SIZE / BODY_OPACITY** — supporting copy.
+  - Range: 28-40 px; opacity 0.8-0.92
+  - Constraints: body limited to ≤2 lines (see Critical Constraints — tilted long paragraphs blur)
+
+### Entry / tilt
+
+- **TILT** — static `rotateY` magnitude in degrees (left `+`, right `−`).
+  - Range: 10-18° (under 10 reads almost flat; over 18 the cards fold shut and body copy becomes hard to read)
+- **TILT_OVERSHOOT** — extra degrees added to the starting `rotateY` before settling to `TILT`.
+  - Range: 4-12°
+  - Effects: gives the entry a slight pivot-into-place feel
+- **ENTRY_SLIDE_DIST** — pixels each card slides from off-axis.
+  - Range: 200-500 px (≈0.3-0.6× `CARD_WIDTH`)
+- **ENTRY_DUR** — per-card slide-in duration.
+  - Range: 0.6-1.2 s
+- **LEFT_AT** — left card entry start.
+  - Range: 0.0-0.4 s
+- **RIGHT_AT** — right card entry start.
+  - Range: `LEFT_AT + 0.0` to `LEFT_AT + 0.3` s (zero stagger feels mechanical; large stagger fragments the pair)
+
+### Idle bob
+
+- **FLOAT_AMP** — sine amplitude on idle y bob (px).
+  - Range: 3-8 px (see sine-wave-loop rule — subtle is the point)
+- **FLOAT_DURATION** — full yoyo round-trip duration (one breath).
+  - Range: 1.6-3.2 s (≈breathing cadence)
+- **IDLE_START** — when idle bob begins.
+  - Constraints: `≥ max(LEFT_AT, RIGHT_AT) + ENTRY_DUR` so idle doesn't fight the entry tail
+
+### Copy reveal
+
+- **COPY_REVEAL_AT** — when eyebrow/headline/body fade in.
+  - Constraints: usually starts during the cards' settle (overlaps the entry tail) — content shouldn't pop in after the cards are already idle
+- **COPY_DUR / COPY_STAGGER / COPY_RISE** — fade-up shape.
+  - Range: duration 0.4-0.7 s; stagger 0.04-0.10 s; rise 12-24 px
+
+### Color / typography tokens
+
+- **{bgGradient}** — radial or linear gradient behind the cards; darker than `{cardSurface}` so cards lift
+- **{cardSurface}** — card background (typically a low-saturation gradient layered over the scene)
+- **{cardBorder}** — 1 px border color, usually `{accentColor}` at low alpha
+- **{shadowColor}** — drop-shadow color, typically near-black at 0.5-0.7 alpha
+- **{accentGlowColor}** — inner glow color, typically `{accentColor}` at low alpha
+- **{accentColor}** — eyebrow + accent rim color (single hue per scene)
+- **{textColor}** — primary headline color, high contrast against `{cardSurface}`
+- **{bodyColor}** — body copy color, slightly desaturated vs `{textColor}`
+- **{font}** — display font stack for all card copy
+
+## Variations
+
+### Mid-tilt zoom-through (combined with camera move)
+
+If a separate camera tween scales `.split-stage`, the cards' tilt reads as the viewer crossing through the gap between them.
+
+### Asymmetric content density (badge / label / icon)
+
+Add a floating badge near each card for additional context. Position absolutely on the parent — not inside the card, so the badge doesn't inherit the 3D rotation:
+
+```html
+<div class="badge badge-left">{leftBadge}</div>
+<div class="badge badge-right">{rightBadge}</div>
+```
+
+### Stacked variants (3+ cards)
+
+For 3 cards, the center card stays flat (`rotateY 0`) and the outer two tilt inward — useful for "your old way / nothing in between / our way" comparisons.
+
+## Key Principles
+
+- **`perspective` on scene root REQUIRED** — without it rotateY flattens and the split-tilt collapses to a flat side-by-side layout
+- **`transform-style: preserve-3d`** on both the stage and each card — preserves the 3D plane as cards have their own transforms
+- **Shadow direction must match tilt** — left card faces right, shadow falls right (positive X), and vice versa. Wrong shadow direction reads as "broken 3D"
+- **Symmetric content weight** — both cards same width, same vertical center, similar line counts. Asymmetric content breaks the comparison metaphor
+- **Counter-phase float (`Math.PI` offset)** — left bobs up while right bobs down. Synchronized bob looks like both cards are on the same conveyor belt; counter-phase looks alive
+- **Slide-in from the outside** — left card from left, right card from right — reinforces "they came from their own worlds and met here"
+- **❗ Tilt magnitude 10-15°** — under 10° looks like a slight perspective offset (almost flat), over 18° looks like the cards are folding shut and copy becomes hard to read
+
+## Critical Constraints
+
+- **Timeline must be paused**: `gsap.timeline({ paused: true })`
+- **Registry key = `data-composition-id`**
+- **No `requestAnimationFrame`** for the idle float — drive it inside the timeline so seek is deterministic
+- **Don't put badges inside the card divs** — they'd inherit the rotateY and tilt off-axis with the card. Float them on the parent
+- **Body copy ≤ 2 lines per card** — tilted text becomes hard to read; long paragraphs collapse into a perspective blur
+
+## Combinations
+
+- [card-morph-anchor.md](card-morph-anchor.md) — both cards could morph into a single unified shape afterward
+- [counting-dynamic-scale.md](counting-dynamic-scale.md) — numbers as the headline content for each side
+
+## Pairs with HF skills
+
+- `/hyperframes-animation` — timeline + `yoyo` for the idle bob
+- `/hyperframes-core` — composition wiring
+- `/hyperframes-cli` — `hyperframes lint`