hyperframes/skills/hyperframes-animation/rules/vertical-spring-ticker.md

---
name: vertical-spring-ticker
description: Slot-machine style vertical scrolling using additive spring physics within a masked container — each spring contributes one "step" of scroll.
metadata:
  tags: text, ticker, spring, scroll, vertical, slot-machine, sequence
---

# Vertical Spring Ticker (Slot Machine)

Multiple spring tweens are ADDED TOGETHER to produce total Y translation. Each spring contributes one discrete "step." The combined motion has snappy distinct moves with natural settling — instead of a single linear scroll, you get the slot-machine "click click click" rhythm.

## How It Works

Container has fixed height `ITEM_HEIGHT`, `overflow: hidden`. Inside is a vertical stack of items, each also `ITEM_HEIGHT` tall. The translate of the inner stack is computed as:

```
translateY = -ITEM_HEIGHT * sum(spring_i.progress for each spring)
```

Each spring fires at a different time, settles, then the next fires. When summed, the stack snaps forward step-by-step. The "spring" easing gives each step a tiny overshoot/settle that distinguishes it from a linear marquee.

## HTML

```html
<div
  class="scene"
  id="ticker-scene"
  data-composition-id="ticker-scene"
  data-start="0"
  data-duration="5"
  data-track-index="0"
>
  <div class="stack">
    <div class="eyebrow">{eyebrow}</div>
    <div class="ticker" id="ticker">
      <div class="stack-inner" id="stack-inner">
        <!-- One .item per state the ticker rolls through.
             The example file lists concrete labels; for the rule, treat
             these as positional slots ({item0} … {itemN}). -->
        <div class="item">{item0}</div>
        <div class="item">{item1}</div>
        <div class="item">{item2}</div>
        <div class="item">{item3}</div>
        <div class="item">{itemN}</div>
      </div>
    </div>
    <div class="brand">{footerLine}</div>
  </div>
</div>
```

## CSS

```css
.scene {
  position: relative;
  width: 100%;
  height: 100%;
  display: grid;
  place-items: center;
  background: {bgColor};
  font-family: {font};
}
.stack {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: STACK_GAP;
}
.eyebrow {
  font-size: EYEBROW_FONT_SIZE;
  font-weight: 800;
  letter-spacing: 14px;
  text-transform: uppercase;
  color: {accentColor};
}
/* MANDATORY: container height matches the per-item height exactly */
.ticker {
  width: TICKER_WIDTH;
  height: ITEM_HEIGHT;       /* MUST match .item height */
  overflow: hidden;
  border-top: 2px solid {dividerColor};
  border-bottom: 2px solid {dividerColor};
  position: relative;
}
.stack-inner {
  display: flex;
  flex-direction: column;    /* MANDATORY for vertical ticker */
  will-change: transform;
}
.item {
  height: ITEM_HEIGHT;       /* MUST equal .ticker height */
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: ITEM_FONT_SIZE;
  font-weight: 900;
  letter-spacing: 8px;
  text-transform: uppercase;
  color: {textColor};
  /* font-variant-numeric: tabular-nums; — for numeric tickers */
}
.brand {
  font-size: BRAND_FONT_SIZE;
  font-weight: 800;
  letter-spacing: 10px;
  color: {accentColor};
  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 innerEl = document.getElementById("stack-inner");

  // Each spring object holds a 0→1 progress; they accumulate to a step-counter.
  // Sum * -ITEM_HEIGHT becomes translateY.
  const springs = Array.from({ length: STEPS }, () => ({ p: 0 }));

  function applyTransform() {
    const sumP = springs.reduce((acc, s) => acc + s.p, 0);
    innerEl.style.transform = `translateY(${-sumP * ITEM_HEIGHT}px)`;
  }
  applyTransform(); // initial state

  // Fire each spring sequentially with overlap — each one snaps in one step
  springs.forEach((spring, i) => {
    tl.to(
      spring,
      {
        p: 1,
        duration: STEP_DUR,
        ease: `back.out(${BOUNCE_FACTOR})`,
        onUpdate: applyTransform,
      },
      STEP_START + i * STEP_SPACING,
    );
  });

  // Footer reveals after the ticker settles on the final item.
  tl.from(
    ".brand",
    { opacity: 0, y: BRAND_Y, duration: BRAND_FADE_DUR, ease: "power3.out" },
    STEP_START + STEPS * STEP_SPACING + BRAND_DELAY,
  );

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

## How to Choose Values

- **ITEM_HEIGHT** — px height of each ticker slot AND the masked window.
  - Range: ~`ITEM_FONT_SIZE × 1.25`; the line must hold capital descenders without clipping
  - Constraints: **`.ticker` height MUST equal `.item` height** exactly — mismatched values cause partial items to peek above/below the mask
  - Reference: ../../examples/proof-logo-chain.html uses `204px`
- **TICKER_WIDTH** — px width of the masked window.
  - Range: wide enough to hold the longest item without ellipsis; typically 30-60% of viewport width
- **STEPS** — number of additive springs (number of state transitions, not number of items).
  - Range: typically 1-4; each step = one "click" in the slot-machine cadence
  - Constraints: `STEPS ≤ itemCount − 1` (you can only roll as far as there are items below the visible one)
  - Reference: ../../examples/proof-logo-chain.html uses `1` (single roll between two states)
- **STEP_DUR** — duration of each spring tween.
  - Range: 0.3-0.7s; under 0.3 the overshoot is invisible, over 0.7 the click reads as a slide
  - Reference: ../../examples/proof-logo-chain.html uses `0.45s`
- **STEP_SPACING** — seconds between consecutive springs' start times.
  - Range: 0.3-0.5s; closer and the steps blur together (looks like linear scroll), further and the ticker feels lazy
  - Constraints: `STEP_SPACING ≤ STEP_DUR` so the previous step is still settling when the next fires (this is what makes them "additive")
- **STEP_START** — when the first spring fires.
  - Range: 0+; gate behind any preceding beat
- **BOUNCE_FACTOR** — `back.out(BOUNCE_FACTOR)` overshoot strength per step.
  - Range: 1.4 (gentle click) → 2.0 (firm click) → 2.5+ (cartoony spin-and-land for a climax step)
  - Effects: low end reads as polished UI, high end reads as casino / game show
- **BRAND_DELAY** — gap after the final step before the footer line reveals, in seconds.
  - Range: 0.2-0.5s; lets the final overshoot settle before the next element competes for attention
- **BRAND_FADE_DUR** — footer fade-in duration.
  - Range: 0.4-0.7s
- **BRAND_Y** — initial vertical offset of the footer before fade-up (in px).
  - Range: 8-24 px; bigger feels "punched in," smaller feels gentle
- **EYEBROW_FONT_SIZE / ITEM_FONT_SIZE / BRAND_FONT_SIZE / STACK_GAP** — typographic + layout scaling.
  - Constraints: items are the focal beat, sized 4-8× larger than eyebrow/footer
- **{bgColor} / {accentColor} / {textColor} / {dividerColor}** — semantic color tokens; accent reserved for the eyebrow and footer so the ticker items stay neutral.
- **{font}** — base typography stack. For numeric tickers add `font-variant-numeric: tabular-nums` so digit widths stay constant.

## Variations

### Numeric ticker (price / counter rolling)

Replace text items with the digit sequence and use the same spring-step pattern per decimal position (units, tens, hundreds...). Add `font-variant-numeric: tabular-nums` for digit-width stability.

### Reverse direction (counting down)

Swap the sign on the translate: `transform: translateY(${sumP * ITEM_HEIGHT}px)` and arrange items in reverse order. Reads as a countdown.

### Continuous infinite ticker (no settling)

Loop forever (e.g. news ticker) — use linear ease on a single long tween, duplicate the items list, reset when translation exceeds total height. NOT this rule — see [sine-wave-loop](sine-wave-loop.md) pattern for continuous motion vs this rule's discrete-step semantics.

### Pause between groups

For dramatic "spin then land" feel, group several fast spring steps (`STEP_SPACING` small) + a long `BRAND_DELAY`-style pause + a final dramatic step with bigger `BOUNCE_FACTOR`. The pause is where the eye locks in.

## Key Principles

- **Container height MUST equal item height** — otherwise items don't snap cleanly into the visible window. If container is 200px and items are 220px, every step shows a partial item edge above/below.
- **`overflow: hidden` on container, NOT on inner stack** — the mask is the window; the stack inside is free to extend below.
- **`flex-direction: column` on inner stack** — required for vertical stacking; row would make items horizontal.
- **Step spacing tighter than step duration** — overlap is what makes the springs additive and gives the "click click" cadence; non-overlapping steps read as a linear scroll.
- **`back.out` per step** — the overshoot is what makes each step feel like a "click." Linear ease or out-only ease loses the slot-machine feel.
- **Sum the springs in onUpdate, don't tween the final position directly** — this is the "additive" trick; each spring contributes its OWN snap, which is the slot-machine pacing.
- **❗ Don't update items via `innerHTML` between steps** — the ticker moves the SAME items via translate; replacing content makes the previous item visible AS the new one (broken illusion).
- **❗ Climax dwell ≥1s after final step** — see SKILL universal constraints.

## Critical Constraints

- **Timeline must be paused**: `gsap.timeline({ paused: true })`
- **Registry key = `data-composition-id`**
- **No CSS `transition`** on stack-inner — competes with the additive transform
- **`will-change: transform`** on stack-inner — many small transform updates per second
- **All items same height (pixel-exact)** — mismatched heights cause cumulative drift
- **For numeric: `font-variant-numeric: tabular-nums`** — variable digit widths break alignment

## Combinations

- [reactive-displacement.md](reactive-displacement.md) — ticker is "pushed" by an incoming element
- [scale-swap-transition.md](scale-swap-transition.md) — ticker scales out after settling on final state, scaled-in subtitle replaces it
- [press-release-spring.md](press-release-spring.md) — button press TRIGGERS the ticker spin

## Pairs with HF skills

- `/hyperframes-animation` — additive spring tweens via shared onUpdate
- `/hyperframes-core` — composition wiring
- `/hyperframes-cli` — `hyperframes lint`