hyperframes/skills/hyperframes-animation/rules/avatar-cloud-network.md

name, description, metadata

name	description	metadata
avatar-cloud-network	Avatars distributed on an elliptical ring connected by SVG dashed lines to a center hub — social proof "community" reveal with staggered entry.	tags avatar, cloud, network, social-proof, ellipse, connection, stagger

Avatar Cloud Network

Avatars arranged on an elliptical ring around a central element (logo / counter / brand). SVG dashed connection lines from center to each avatar. Staggered spring entry on avatars, then connection lines draw outward — communicates "community" or "social proof." Distinct from orbit-3d-entry (which continuously orbits) — avatar-cloud is a static composed reveal.

How It Works

Three rendering layers:

1. SVG connection lines (z-index 1, behind everything) — line from center hub to each avatar's position
2. Avatars (z-index 2) — <div> circles on elliptical positions
3. Center hub (z-index 5) — brand counter or logo (sits ABOVE the lines that converge on it)

Animation phases:

• HUB_FADE_START → HUB_FADE_START + HUB_FADE_DUR: hub fades in
• AVATAR_ENTRY_START → AVATAR_ENTRY_START + (AVATAR_COUNT − 1) × AVATAR_STAGGER + AVATAR_ENTRY_DUR: avatars cascade in
• LINES_START → LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER + LINES_DUR: connection lines draw outward
• climax dwell: optional idle breathing on avatars (see Variations / sine-wave-loop)

HTML

<div
  class="scene"
  id="cloud-scene"
  data-composition-id="cloud-scene"
  data-start="0"
  data-duration="4"
  data-track-index="0"
>
  <!-- Connection lines layer -->
  <svg class="lines" viewBox="0 0 1920 1080" xmlns="http://www.w3.org/2000/svg">
    <!-- Lines injected by script — center to each avatar -->
  </svg>

  <!-- Avatars + center hub -->
  <div class="hub-wrap">
    <div class="hub" id="hub">
      <div class="hub-num" id="hub-num">{counterValue}</div>
      <div class="hub-label">{counterLabel}</div>
    </div>
    <!-- Avatars injected by script — AVATAR_COUNT around the ellipse -->
  </div>

  <div class="brand">{footerLine}</div>
</div>

Placeholder tokens:

• {counterValue} / {counterLabel} — the hub copy (numeric proof + category)
• {footerLine} — optional attribution line under the cloud
• {avatar[i]} — per-avatar image source (or emoji glyph if using the emoji variation below)

CSS

.scene {
  position: relative;
  width: 100%;
  height: 100%;
  background: {bgColor};
  font-family: {font};
  overflow: hidden;
}
.lines {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  pointer-events: none;
  z-index: 1;
}
.hub-wrap {
  position: absolute;
  inset: 0;
  display: grid;
  place-items: center;
}
.hub {
  position: relative;
  z-index: 5;
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 12px;
  padding: 48px 64px;
  border-radius: 28px;
  background: {hubBg};
  border: 1px solid {hubBorder};
}
.hub-num {
  font-size: HUB_NUM_FONT_SIZE;
  font-weight: 900;
  color: {textColor};
  letter-spacing: -4px;
  line-height: 1;
  font-variant-numeric: tabular-nums;
}
.hub-label {
  font-size: HUB_LABEL_FONT_SIZE;
  font-weight: 800;
  letter-spacing: 12px;
  color: {accentColor};
  text-transform: uppercase;
}
.avatar {
  position: absolute;
  z-index: 2;
  width: AVATAR_SIZE;
  height: AVATAR_SIZE;
  border-radius: 50%;
  border: 3px solid {avatarBorder};
  box-shadow:
    0 12px 32px rgba(0, 0, 0, 0.5),
    0 0 24px {avatarGlow};
  display: grid;
  place-items: center;
  font-size: AVATAR_GLYPH_SIZE;
  background: {avatarBg};
  will-change: transform, opacity;
  /* Top-left positioned by script; transform centers via -50% trick */
  transform: translate(-50%, -50%);
}
.brand {
  position: absolute;
  bottom: 80px;
  left: 50%;
  transform: translateX(-50%);
  font-size: BRAND_FONT_SIZE;
  font-weight: 900;
  letter-spacing: 14px;
  color: {accentColor};
  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 });

  // CENTER_X / CENTER_Y must match the hub's rendered center exactly.
  // For a hub-wrap with place-items:center on a 1920×1080 canvas these are
  // (compositionWidth/2, compositionHeight × CENTER_Y_FACTOR).
  const SCREEN_CENTER = { x: CENTER_X, y: CENTER_Y };

  const hubWrap = document.querySelector(".hub-wrap");
  const linesSvg = document.querySelector(".lines");

  // Build avatars + lines
  const avatarPositions = [];
  for (let i = 0; i < AVATAR_COUNT; i++) {
    const angle = (i / AVATAR_COUNT) * Math.PI * 2 - Math.PI / 2; // start at top
    const x = SCREEN_CENTER.x + Math.cos(angle) * RADIUS_X;
    const y = SCREEN_CENTER.y + Math.sin(angle) * RADIUS_Y;
    avatarPositions.push({ x, y, angle });

    // Avatar
    const av = document.createElement("div");
    av.className = "avatar";
    av.style.left = `${x}px`;
    av.style.top = `${y}px`;
    // assign avatar image / glyph from your authoring data (see {avatar[i]})
    hubWrap.appendChild(av);

    // Line from hub to avatar
    const line = document.createElementNS("http://www.w3.org/2000/svg", "line");
    line.setAttribute("x1", SCREEN_CENTER.x);
    line.setAttribute("y1", SCREEN_CENTER.y);
    line.setAttribute("x2", x);
    line.setAttribute("y2", y);
    line.setAttribute("stroke", "{lineColor}");
    line.setAttribute("stroke-width", "2");
    line.setAttribute("stroke-dasharray", "6 8");
    const len = Math.hypot(x - SCREEN_CENTER.x, y - SCREEN_CENTER.y);
    line.style.strokeDashoffset = String(len);
    line.dataset.length = String(len);
    line.dataset.index = String(i);
    linesSvg.appendChild(line);
  }

  // Phase 1 — hub fade in
  tl.from(
    ".hub",
    { opacity: 0, scale: 0.8, duration: HUB_FADE_DUR, ease: `back.out(${HUB_BOUNCE})` },
    HUB_FADE_START,
  );

  // Phase 2 — avatars cascade-in (staggered spring)
  const avatars = document.querySelectorAll(".avatar");
  avatars.forEach((av, i) => {
    tl.from(
      av,
      {
        opacity: 0,
        scale: 0,
        duration: AVATAR_ENTRY_DUR,
        ease: `back.out(${AVATAR_BOUNCE})`,
      },
      AVATAR_ENTRY_START + i * AVATAR_STAGGER,
    );
  });

  // Phase 3 — connection lines draw outward (staggered) — starts after most avatars land
  const lines = linesSvg.querySelectorAll("line");
  lines.forEach((line, i) => {
    tl.to(
      line,
      {
        strokeDashoffset: 0,
        duration: LINES_DUR,
        ease: "power2.out",
      },
      LINES_START + i * LINE_STAGGER,
    );
  });

  // Phase 4 — climax dwell (network fully formed), idle breathing on avatars
  // (see sine-wave-loop.md for the multiplicative onUpdate form)
  const breathDriver = { p: 0 };
  tl.to(
    breathDriver,
    {
      p: Math.PI * 2 * BREATH_CYCLES,
      duration: BREATH_DUR,
      ease: "none",
      onUpdate: () => {
        avatars.forEach((av, i) => {
          const phase = breathDriver.p + (i / avatars.length) * Math.PI * 2;
          const s = 1 + Math.sin(phase) * BREATH_AMP;
          av.style.transform = `translate(-50%, -50%) scale(${s})`;
        });
      },
    },
    BREATH_START,
  );

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

How to Choose Values

Geometry

• CENTER_X / CENTER_Y — px coordinates of the hub center; lines and avatar positions derive from these.
  • Constraints: must equal the hub's actual rendered center — when this rule is composed with another scene (e.g. a logo that has been recentered), CENTER_X / CENTER_Y must be baked from the same source as the hub's final position
  • Reference: examples/proof-logo-chain.html uses (W/2, H × 0.47) so the cloud sits slightly above the canvas midline
• RADIUS_X / RADIUS_Y — ellipse radii in px (RADIUS_X ≥ RADIUS_Y reads as perspective).
  • Range: RADIUS_X ~ 20-30% of viewport width; RADIUS_Y ~ 18-25% of viewport height
  • Constraints: RADIUS_X / RADIUS_Y ratio between 1.5 and 3.0 reads as natural depth; ratio = 1 (circle) reads as a flat 2D layout
  • Reference: examples/proof-logo-chain.html uses W * 0.25 (480px) and H * 0.22 (237.6px)
• AVATAR_COUNT — number of avatars distributed around the ring.
  • Range: 8-12; fewer feels sparse, more clutters the ellipse
  • Reference: examples/proof-logo-chain.html uses 10
• AVATAR_SIZE / AVATAR_GLYPH_SIZE — px diameter of each avatar circle and (optional) inner glyph size.
  • Range: AVATAR_SIZE ~ 80-120 px at 1920 wide; small enough that 10+ avatars fit the ring without overlap
• HUB_NUM_FONT_SIZE / HUB_LABEL_FONT_SIZE / BRAND_FONT_SIZE — hub typography.
  • Constraints: hub-num is the focal beat, sized 2-4× the label

Hub fade

• HUB_FADE_START — when the hub fades in.
  • Range: usually 0 (the hub establishes the focal point); offset if the scene precedes with another beat
• HUB_FADE_DUR — hub fade-in duration.
  • Range: 0.4-0.6s
• HUB_BOUNCE — back.out(HUB_BOUNCE) coefficient on the hub's scale entry.
  • Range: 1.4 (subtle) → 1.8 (firm)

Avatar cascade

• AVATAR_ENTRY_START — when the first avatar pops in.
  • Constraints: ≥ HUB_FADE_START + HUB_FADE_DUR × 0.6 so the hub is established before satellites arrive
• AVATAR_ENTRY_DUR — per-avatar scale-up duration.
  • Range: 0.4-0.7s
• AVATAR_STAGGER — delay between consecutive avatar entries.
  • Range: 0.06-0.10s; cascade reads as "joining"; simultaneous reads as "all already there"
• AVATAR_BOUNCE — back.out(AVATAR_BOUNCE) coefficient on each avatar's pop.
  • Range: 1.4 (gentle) → 1.8 (firm); slightly firmer than hub for differentiation

Connection lines

• LINES_START — when the lines begin drawing outward.
  • Constraints: LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER should overlap the last avatar's settle by ~0.1-0.2s so the drawing reads as a consequence of the avatars landing
• LINES_DUR — per-line draw duration (strokeDashoffset → 0).
  • Range: 0.4-0.7s
• LINE_STAGGER — delay between consecutive lines starting.
  • Range: 0.02-0.05s; tight stagger reads as a wave outward

Idle breathing

• BREATH_START — when idle breathing activates.
  • Constraints: ≥ LINES_START + (AVATAR_COUNT − 1) × LINE_STAGGER + LINES_DUR + ~0.2s (let the lines settle)
• BREATH_DUR — total duration of the breathing tween.
  • Range: fills the remaining composition window
• BREATH_CYCLES — number of full sine cycles across BREATH_DUR.
  • Range: 1.0-2.0; under 1 reads as a single sigh, over 2 starts to look anxious
• BREATH_AMP — sine amplitude on scale (multiplicative).
  • Range: 0.02-0.06; smaller for headshots, larger for stylized glyphs

Color tokens

• {bgColor} — stage background (typically a dark gradient so the cloud reads as a constellation)
• {textColor} — hub-num color (primary copy)
• {accentColor} — hub-label + footer (the brand voice)
• {hubBg} / {hubBorder} — hub card surfaces; gradient + 1px border reads as elevated
• {avatarBg} / {avatarBorder} / {avatarGlow} — avatar circle styling; soft border + glow keeps them legible on dark backgrounds
• {lineColor} — SVG stroke color (translucent accent reads as networky)
• {font} — base typography stack

Variations

Avatar size variation (organic feel)

Vary avatar sizes by index — e.g. a small index-keyed array of sizes — so the ring doesn't read as rigidly repetitive.

Solid lines instead of dashed

Drop stroke-dasharray and use a solid stroke. Drop the dash-draw animation; lines fade in via opacity instead. More corporate, less networky.

Multi-orbit (concentric rings)

Two layers of avatars: smaller inner ring (fewer avatars, slightly larger size), larger outer ring (more, smaller). Lines connect ONLY inner ring to hub; outer ring is a "halo."

Country / role glyphs (geographic or persona spread)

Replace face images with flags / emoji / iconography. Reads as "global community" or "diverse roles."

Key Principles

• Hub above lines (z-index: 5 vs lines z-index: 1) — lines should appear to terminate AT the hub edge, not pass through. Hub must be in front.
• Lines drawn outward (dash offset 0) — drawing FROM center is the visual narrative: "the hub connects to its community."
• 8-12 avatars — fewer feels sparse, more clutters the ellipse.
• RADIUS_X > RADIUS_Y — horizontal ellipse reads as perspective; equal radii (circle) reads as 2D flat layout.
• Avatar entry stagger 0.06-0.10s — cascade reads as "joining"; simultaneous reads as "all already there."
• Stagger lines AFTER avatars are mostly settled — line draw starts ~0.1-0.2s before last avatar settles for overlap.
• Idle breathing post-formation — each avatar slightly out-of-phase. Holds the eye during climax dwell.
• ❗ Climax dwell ≥1s — after lines complete, hold for ≥1s so the formed network is readable.

Critical Constraints

• Timeline must be paused: gsap.timeline({ paused: true })
• Registry key = data-composition-id
• No CSS animation on avatars or lines
• will-change: transform, opacity on avatars
• SVG pointer-events: none — decorative overlay
• getTotalLength() not needed for straight lines — use Math.hypot for line length (cheaper, exact)
• Hub z-index > lines z-index — explicit layering

Combinations

• counting-dynamic-scale.md — the hub IS a growing counter
• sine-wave-loop.md — avatar idle breathing pattern
• 3d-text-depth-layers.md — hub label with depth layers

Pairs with HF skills

• /hyperframes-animation — staggered spring entries + SVG dash draw
• /hyperframes-core — composition wiring
• /hyperframes-cli — hyperframes lint