hyperframes/skills/hyperframes-animation/rules/cursor-click-ripple.md

---
name: cursor-click-ripple
description: Animated mouse cursor moves to target, clicks with scale depression and expanding ripple rings.
metadata:
  tags: cursor, click, ripple, interaction, mouse, button
---

# Cursor Click Ripple

An animated cursor moves to a target element, performs a click with visual depression, and emits expanding ripple rings from the click point.

## How It Works

Three sequential phases driven by a single GSAP timeline:

1. **Move**: eased cursor translation from entry point to the target element's center
2. **Click**: scale depression on both cursor and target (yoyo: shrink then return)
3. **Ripple**: expanding circles radiate outward from the click point with fade-out. 1–3 staggered rings amplify the click feedback

Use a GSAP timeline because the phase ordering (move → settle → click → ripples) is exactly what timelines express cleanly.

## HTML

```html
<div
  class="scene"
  id="cursor-click-scene"
  data-composition-id="cursor-click-scene"
  data-start="0"
  data-duration="2"
  data-track-index="0"
>
  <button class="target-button">{ctaLabel}</button>

  <div class="cursor">
    <svg width="24" height="24" viewBox="0 0 24 24">
      <path
        d="M5 3L19 12L12 13L9 20L5 3Z"
        fill="{cursorFill}"
        stroke="{cursorStroke}"
        stroke-width="1.5"
      />
    </svg>
  </div>

  <!-- Ripple rings — centered on click target, hidden until trigger -->
  <div class="ripple ripple-1"></div>
  <div class="ripple ripple-2"></div>
  <div class="ripple ripple-3"></div>
</div>
```

## CSS

Position cursor at the entry point. Button sits at its final position. Ripples are at the click-target center with `scale: 0` and `opacity: 0` so they hold invisible until the timeline trigger:

```css
.scene {
  position: relative;
  width: 100%;
  height: 100%;
}

.target-button {
  position: absolute;
  left: 50%;
  top: 50%;
  transform: translate(-50%, -50%);
  /* ...button styling (background, color, font from project tokens) */
}

.cursor {
  position: absolute;
  left: 10%;
  top: 80%; /* entry corner */
  pointer-events: none;
  z-index: 999;
}

.ripple {
  position: absolute;
  left: 50%;
  top: 50%; /* click target center */
  width: 100px;
  height: 100px;
  border-radius: 50%;
  border: 2px solid {rippleColor};
  transform: translate(-50%, -50%) scale(0);
  opacity: 0;
  pointer-events: none;
}
```

## GSAP Timeline

Build a paused timeline. Register it on `window.__timelines` with the same key as `data-composition-id` on the scene root. All tuning values are named constants — see How to Choose Values below.

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

  // MOVE_DUR, MOVE_EASE, CLICK_AT, PRESS_DUR, CURSOR_PRESS_SCALE, TARGET_PRESS_SCALE,
  // RIPPLE_AT, RIPPLE_DUR, RIPPLE_SCALE, RIPPLE_STAGGER, RIPPLE_EASE
  // — all named; values per How to Choose Values.

  // Phase 1 — Move cursor to target center (eased, not linear)
  tl.to(
    ".cursor",
    {
      x: TARGET_X,
      y: TARGET_Y,
      duration: MOVE_DUR,
      ease: MOVE_EASE,
    },
    0,
  );

  // Phase 2 — Click: cursor + target depress together, then return
  tl.to(
    ".cursor",
    {
      scale: CURSOR_PRESS_SCALE,
      duration: PRESS_DUR,
      ease: "power2.in",
      yoyo: true,
      repeat: 1,
    },
    CLICK_AT,
  );
  tl.to(
    ".target-button",
    {
      scale: TARGET_PRESS_SCALE,
      duration: PRESS_DUR,
      ease: "power2.in",
      yoyo: true,
      repeat: 1,
    },
    CLICK_AT,
  );

  // Phase 3 — Ripple burst, N rings staggered from the click point
  tl.set([".ripple-1", ".ripple-2", ".ripple-3"], { opacity: 1 }, RIPPLE_AT);
  tl.to(
    [".ripple-1", ".ripple-2", ".ripple-3"],
    {
      scale: RIPPLE_SCALE,
      opacity: 0,
      duration: RIPPLE_DUR,
      ease: RIPPLE_EASE,
      stagger: RIPPLE_STAGGER,
      immediateRender: false,
    },
    RIPPLE_AT,
  );

  window.__timelines["cursor-click-scene"] = tl;
</script>
```

## How to Choose Values

- **MOVE_DUR** — cursor travel time from entry to target, in seconds
  - Range: 0.4–1.0 s
  - Effects: short feels darting; long feels deliberate / "considered click"
  - Constraints: must end before `CLICK_AT` — otherwise the click fires while the cursor is still moving and reads as a misclick
  - Reference: ../../examples/cta-orbit-collapse.html uses 0.5 s

- **MOVE_EASE** — easing family for the move tween
  - Discrete choice. Options:
    - `power2.inOut` — symmetric, calm; good for "the user thoughtfully moves the cursor"
    - `back.out(<n>)` — overshoot landing; good when the click target is a button you want the cursor to "settle onto" with a tiny visible recoil. Pair with a low overshoot coefficient (~1.2–1.4) — higher reads as cartoonish
    - `power3.out` — fast start, soft landing; good for a "decisive" move
  - Reference: ../../examples/cta-orbit-collapse.html uses `back.out(1.3)`

- **CLICK_AT** — time the click fires, in seconds
  - Range: must be ≥ `MOVE_DUR` (cursor has settled); typically `MOVE_DUR + 0.0–0.3 s` of "decision pause"
  - Effects: zero pause reads as autopilot; >0.3 s of pause reads as hesitation
  - Reference: ../../examples/cta-orbit-collapse.html clicks 0.2 s after the cursor settles

- **PRESS_DUR** — half-duration of the depression (the yoyo runs twice this)
  - Range: 0.06–0.12 s
  - Effects: short feels crisp; long feels mushy
  - Constraints: total press = `2 * PRESS_DUR`; must finish before the next scene phase needs the cursor / target back at normal scale
  - Reference: ../../examples/cta-orbit-collapse.html uses 0.08 s

- **CURSOR_PRESS_SCALE / TARGET_PRESS_SCALE** — how far each compresses during the click
  - Range: cursor 0.80–0.90; target 0.92–0.97
  - Effects: smaller numbers = stronger "this click counts" feel; values close to 1 read as a gentle tap
  - Constraints: cursor compresses MORE than the target — the cursor is the actor, the target is the recipient
  - Reference: ../../examples/cta-orbit-collapse.html uses cursor 0.85 / target 0.95

- **RIPPLE_AT** — when the rings start expanding, in seconds
  - Range: `CLICK_AT + 0.0–0.08 s`
  - Effects: simultaneous with the press feels causal; slight delay feels acoustic ("the click happens, then the wave radiates")
  - Reference: ../../examples/cta-orbit-collapse.html starts the ripple at `CLICK_AT` exactly

- **RIPPLE_DUR** — how long each ring takes to fully expand and fade
  - Range: 0.5–1.0 s
  - Effects: short rings feel sharp; long rings feel like a soft sonar
  - Constraints: must complete before any phase that depends on the ring being gone (e.g. a screen wipe)
  - Reference: ../../examples/cta-orbit-collapse.html uses 0.7 s

- **RIPPLE_SCALE** — final scale of each ring before it fades
  - Range: 3–6
  - Effects: 3 keeps the ring near the click site; 6 lets it sweep the surrounding area
  - Constraints: if the ring would exit the visible frame before opacity reaches 0, lower the scale or shorten the duration
  - Reference: ../../examples/cta-orbit-collapse.html uses 5

- **RIPPLE_STAGGER** — delay between consecutive rings
  - Range: 0.06–0.12 s (or 0 for a single ring; see Variations)
  - Effects: below ~0.06 s reads as one thick ring; above ~0.12 s reads as separate events
  - Reference: ../../examples/cta-orbit-collapse.html uses a single ring (no stagger)

- **RIPPLE_EASE** — easing family for the expansion
  - Discrete choice. Options:
    - `power2.out` — fast start, soft tail; the standard "ping" feel
    - `power3.out` — even sharper attack, longer tail
    - `expo.out` — almost-instant expansion with a long quiet fade; reads as a strong, distant pulse
  - Reference: ../../examples/cta-orbit-collapse.html uses `power2.out`

- **TARGET_X / TARGET_Y** — pixel offset of the click target from the cursor's CSS-laid origin
  - These are layout-derived, not creative knobs — they must match the visual centroid of the actual click target. A 4 px miss reads as missing the button
  - Reference: ../../examples/cta-orbit-collapse.html targets the white button at `CENTER_X + 130, CENTER_Y + 15`

## Variations

- **Single ring** — keep one `.ripple` element, drop the stagger; reads as more elegant when the rest of the scene is busy
- **Keyframed attack-decay** — replace the simple expand-and-fade with a `keyframes` block that ramps opacity 0 → peak → 0 across the duration; gives a clearer "energy radiates and dissipates" envelope (used in ../../examples/cta-orbit-collapse.html)
- **Multi-ring expanding pulse** — 3 rings with 0.08 s stagger feels richer when the click is the climactic moment of the scene

## Key Principles

- **Move before click**: trigger the click only after the move tween has settled — clicking mid-motion reads as unintentional
- **Synchronized depression**: cursor + target depress at the same `position` time with the same duration (and both yoyo back)
- **Ripple from click point**: ripples expand from the exact click location (the button's visual center), not from any element's bounding-box origin
- **Subtle scale**: cursor compresses more than the target — see `CURSOR_PRESS_SCALE` / `TARGET_PRESS_SCALE`
- **High z-index cursor**: cursor renders above all content for the entire sequence

## Critical Constraints

- **Timeline must be paused**: `gsap.timeline({ paused: true })`. Never call `tl.play()` — HyperFrames seeks the timeline frame-by-frame deterministically
- **Registry key = `data-composition-id`**: `window.__timelines["<id>"]` must match the `data-composition-id` on the scene root exactly
- **`immediateRender: false` on the ripple expand**: holds the initial state (`scale: 0`, `opacity: 0`) until the click moment, otherwise the tween pre-renders and the rings appear at the wrong size at t=0
- **Finite duration**: verify `tl.duration()` matches the scene's `data-duration`
- **`pointer-events: none` on cursor + ripples**: they're purely visual; never block underlying interactivity (matters for hover-able exports)
- **No CSS transitions / animations**: all motion lives in the GSAP timeline so seek stays deterministic

## Combinations

- [orbit-3d-entry.md](orbit-3d-entry.md) — when the click is the pivot that collapses orbiting elements toward the cursor's target
- [center-outward-expansion.md](center-outward-expansion.md) — the click can be the trigger for an outward burst from the click point
- [press-release-spring.md](press-release-spring.md) for stronger physical feel on the target button
- [scale-swap-transition.md](scale-swap-transition.md) for the button's state change after click (button morphs into success state, next view, etc.)

## Pairs with HF skills

- `/hyperframes-animation` — timeline + tween API reference (eases, stagger, `immediateRender`, etc.)
- `/hyperframes-core` — composition wiring (`data-*` attributes, scene structure, registration contract)
- `/hyperframes-cli` — `hyperframes lint` to verify the registry key + duration match