harsh040506/timeline-choreographer

Timeline Choreographer

When multiple elements animate together, the difference between "everything flashed at once" and "beautifully sequenced" is choreography: the deliberate arrangement of when each element moves, for how long, and in what relationship to others.

Core principle: The eye follows the first thing that moves. Everything after should feel like a logical consequence.

---

The Three Choreography Rules

1. Lead with the most important element — primary content moves first. Secondary and decorative elements follow.
2. Stagger related siblings by 40–70ms — creates a readable wave. Below 30ms: imperceptible (might as well be simultaneous). Above 80ms: feels slow and disconnected.
3. Maximum 2–3 focal points per sequence — every additional concurrent animated element costs cognitive attention.

---

Framer Motion Variants — The Declarative Approach

Variants propagate from parent to children automatically. The parent's staggerChildren delays each child's entry sequentially.

const containerVariants = {
  hidden: {},
  visible: {
    transition: {
      staggerChildren: 0.06,    // 60ms between each child
      delayChildren: 0.1,       // Initial delay before first child
      when: "beforeChildren",   // Parent transitions first, then children
    },
  },
};

const itemVariants = {
  hidden: { opacity: 0, y: 16, filter: "blur(4px)" },
  visible: {
    opacity: 1,
    y: 0,
    filter: "blur(0px)",
    transition: { duration: 0.3, ease: [0, 0, 0.58, 1] },
  },
};

function StaggeredContent({ items }) {
  return (
    <motion.ul
      variants={containerVariants}
      initial="hidden"
      animate="visible"
    >
      {items.map((item, i) => (
        <motion.li key={i} variants={itemVariants}>
          {item}
        </motion.li>
      ))}
    </motion.ul>
  );
}

Dashboard grid stagger (diagonal pattern):

// Diagonal stagger — more interesting than row-by-row
const gridVariants = {
  visible: {
    transition: {
      staggerChildren: 0.04,
      delayChildren: 0.05,
    },
  },
};

// Items get delay based on their grid position for diagonal effect
const cardVariants = {
  hidden: { opacity: 0, scale: 0.96 },
  visible: (i) => ({
    opacity: 1,
    scale: 1,
    transition: {
      delay: (Math.floor(i / cols) + (i % cols)) * 0.04, // row + col diagonal
      duration: 0.28,
    },
  }),
};

---

GSAP Timeline — The Imperative Approach

Use GSAP when:

• You need precise overlap control (not just stagger)
• Mix of CSS, SVG, and DOM element animations
• Complex orchestration with conditional branches
• Scroll-linked choreography (with ScrollTrigger)

import gsap from "gsap";

const tl = gsap.timeline({
  defaults: { ease: "power2.out" },
  delay: 0.1,
});

// Position parameter controls overlap:
// ">-0.3"  = start 300ms before previous ends (overlap)
// "+=0.1"  = start 100ms after previous ends (gap)
// "<"      = start at same time as previous (concurrent)

tl.from(".hero-eyebrow",  { y: 20, opacity: 0, duration: 0.4 })
  .from(".hero-headline", { y: 30, opacity: 0, duration: 0.5 }, "-=0.2")
  .from(".hero-subhead",  { y: 20, opacity: 0, duration: 0.4 }, "-=0.2")
  .from(".hero-cta",      { y: 15, opacity: 0, duration: 0.35 }, "-=0.15")
  .from(".hero-image",    { scale: 0.95, opacity: 0, duration: 0.6 }, "<");
  // ← image starts at same time as CTA

Stagger with GSAP:

// Stagger a batch of elements
gsap.from(".card", {
  opacity: 0,
  y: 20,
  stagger: {
    each: 0.06,       // 60ms between each
    from: "start",    // or "center", "end", "random", "edges"
    ease: "power2.in" // Easing applied to the stagger distribution itself
  },
  duration: 0.3,
  ease: "power2.out",
  scrollTrigger: ".card-grid",
});

---

Stagger Timing Reference

| Stagger interval | Effect | |-----------------|--------| | < 30ms | Effectively simultaneous — imperceptible | | 40–60ms | Smooth wave — most common, natural | | 60–80ms | Readable cascade, each element distinct | | 80–120ms | Deliberate, each element gets full attention | | > 120ms | Slow — use only for < 4 items |

Longer stagger = more deliberate = higher hierarchy. Use generous stagger for onboarding, hero, and empty states. Use tight stagger for lists, grids, and content sections.

---

Hero Sequence Timing Template

Standard pattern for a 5-element hero section at feel-premium speed:

t=0ms:    Eyebrow / label (if present)             — fade + translateY(16px), 350ms
t=150ms:  Primary headline                         — fade + translateY(16px), 450ms
t=280ms:  Subheadline                              — fade + translateY(12px), 380ms
t=380ms:  CTA button(s)                            — fade + scale(0.97→1),   300ms
t=280ms:  Hero image (concurrent with subheadline) — fade + scale(0.97→1),   500ms

Total sequence: ~780ms from first element to fully rendered — short enough to not feel slow, long enough to feel crafted.

---

Exit Choreography

Exits are the reverse of entrances — but should run in reverse order and at ~70–80% of entrance duration. The last thing to enter is the first to leave.

const exitVariants = {
  visible: { opacity: 1, y: 0 },
  hidden: {
    opacity: 0,
    y: -8,
    transition: { duration: 0.2, ease: [0.4, 0, 1, 1] } // ease-in for exit
  },
};

// Use AnimatePresence with mode="wait" or mode="sync" to control exit/entry overlap
<AnimatePresence mode="wait">
  {isVisible && (
    <motion.div
      key="content"
      initial="hidden"
      animate="visible"
      exit="hidden"
      variants={containerVariants}
    >
      {children}
    </motion.div>
  )}
</AnimatePresence>

---

Common Mistakes

| Mistake | Consequence | Fix | |---------|-------------|-----| | Everything at t=0 | Visual explosion, no narrative | Add staggerChildren or explicit delays | | Stagger > 100ms for 8+ items | Sequence too slow to watch | Cap at 60ms for large sets | | Different easing per element | Incoherent feel | Use a shared defaults in GSAP or shared variant config | | Entrance without exit | Spatial confusion on unmount | Always pair AnimatePresence + exit variants | | Mixing simultaneous and staggered randomly | No clear read order | Define the visual hierarchy first, then assign delays accordingly |

---

Additional Resources

• references/choreography-patterns.md — Page transition choreography, tab switch sequences, modal open/close, loading → content reveal transitions, and a full library of named stagger patterns (cascade, wave, from-center, diagonal, random)