numeral-roller

name	numeral-roller
description	motion-graphic primitive — slot-machine-style digit slides with partial visibility of adjacent digits (previous on top, next on bottom). distinct from count-up which interpolates a value smoothly. canonical for stopwatch / odometer / dial idioms. linear easing — feels mechanical.

numeral-roller

Purpose

Replace digit display where each digit "wipes" in vertically as if printed on a rotating drum. The previous digit's bottom edge briefly visible at the top of the frame, then the new digit fully shown, then the next digit's top edge starts peeking at the bottom.

Distinct from count-up — that's smooth value interpolation; this is discrete digit-by-digit slot-machine swap.

Params

{
  "digits_sequence": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "per_digit_hold_frames": 20,
  "per_digit_wipe_frames": 4,            // 3-5 = sweet spot
  "wipe_direction": "bottom-to-top",     // bottom-to-top (most common) | top-to-bottom

  "font_family": "Inter",
  "font_weight": 900,
  "font_size_px": 960,                   // HUGE — fills most of frame
  "color": "#FFFFFF",
  "letter_spacing": "-0.03em",

  "per_digit_layout_balance": true,      // rebalance x-position per glyph
  "easing": "linear"
}

Behaviour

1. Render the current digit centered (with per-glyph x-balance).
2. During the wipe window:
   • Translate the current digit up by font_height over wipe_frames.
   • Simultaneously translate the new digit in from below by the same amount.
3. Hold the new digit for per_digit_hold_frames.
4. Repeat for next digit.

The wipe creates the brief "two digits visible" moment.

Style pack overrides

• SP-A (marshmallow) — adapted for stopwatch mode — black bg override, white numerals.
• Other packs: not used.

Quality Checks

• Linear easing (no spring, no bezier overshoot).
• Per-digit layout balance enabled — '1' positioned differently than '8' to maintain visual mass center.
• Wipe window 3-5 frames (not 2, not 8+).
• Both digits visible during wipe window (no instant swap).

Failure Modes

• Roller feels animated, not mechanical. Switch easing to linear.
• Digits appear to teleport. Wipe frames too short (≤2). Bump to 4.
• Visual mass shifts. Per-digit balance off. Pre-measure each digit's bbox and apply x-offset.