Files
gstack/design-motion/sections/motion.md
T
garrytanandcapy-ai[bot] 41a720dac4 fix(design-motion): review and QA fixes before ship
- encode: refuse unknown options and --formats tokens, validate --pad (#RRGGBB[AA])
  and --crop (compare too) so nothing but a colour or crop reaches ffmpeg's filter graph
- encode: export refuses a capture with missing window frames; check prints
  MOTION_SETTINGS for any threshold/phase override; contact sheet drops -fps_mode
- capture: portrait-aware scale, --cycle must be whole 60 fps frames, stills with
  CSS animations disabled, pauseAt tolerates slow loads, clears stale manifest/stills
- skill: <motion-dir> placeholder instead of a cross-block shell variable,
  GSTACK_FFMPEG-aware probe, stop points before the first capture, doctrine fixes
- tests: refusal rows, portrait scale, cycle guard

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-10-26 01:15:58 +00:00

8.7 KiB
Raw Blame History

Motion: empty state, load, stories, cycle

Every timing, distance and curve comes from the defaults table at the end. Never invent ad hoc values; change the table instead.

Start empty

The first frame of every showcase load and every export is the empty state (on a website the doctrine wins: the markup is the finished state until the intro fires): the background plus the static joined surfaces for an app frame, the background alone for separate cards. Empty becomes loaded; never open on the finished frame.

Loading choreography

Elements rise from just below and resolve from blur to sharp, staggered in reading order.

Kind For From
card Separate cards, with their shadow translateY(24px) scale(0.985) blur(6px), opacity 0
up Text, headers, values, rows translateY(10px) blur(4px), opacity 0
down Top bars and toolbars translateY(-8px) blur(4px)
left Sidebar items, list rows, labels translateX(-10px) blur(4px)
pop Icons, badges, avatars, buttons, dots scale(0.82-0.88) from the element's own centre, blur(4px)
photo Images skeleton shimmer, then blur(14px) saturate(0.6) to sharp
wipe Bars, fills, highlights left-to-right clip-path in stage pixels: right inset from stageW − x (zero width, no sliver) to stageW − (x + w); top and bottom stay at y and stageH − (y + h)
line / grow Rules, ticks, timelines scaleX(0) / scaleY(0) from the start edge
donut Rings, gauges conic mask sweeping clockwise from 12 o'clock
tray Sheets, trays, folders up 40 px from inside the container's bottom edge, clipped by it
fade Layers under another layer opacity only
  • Containers load in reading order 80-90 ms apart (cards start about 0.15 s before their own contents). Inside one: header, labels, values, then visuals; items in a group stagger 30-80 ms. The whole intro takes 2 to 2.5 s.
  • Covered layers arrive last and leave first, so they never ghost through their cover.
  • Skeletons match the real shape and sit 1 px inside it, so no halo shows.
  • Data bars, meters and highlights fill like progress: a wipe with --io over 0.7-1.1 s. Never add a loading line or any shape the design lacks.

Stories: one per visual

The intro only opens the show. The main act is each visual acting out what it does, on a loop. Write each story as one sentence before building it ("a new lead lands on top and the older ones step back").

Visual Story
Stack (leads, notifications, files) A new item lands on top with a blur, the rest step back a slot, the last leaves
Line or area chart A scrubber glides across, a dot rides the curve, the tooltip value counts
Bar chart, grid of cells Bars breathe like a live feed and settle on the design heights
Donut, gauge Segments ease outward one at a time and back, or the ring sweeps again
Table, list A soft highlight inspects rows one by one; a preview loads for the active row
Calendar A highlight searches for an open slot, the event glides into it and back
Flow, connectors Pulses travel the connectors in flow direction and light each node they pass
Prompt, form The prompt deletes and retypes glyph by glyph; the result resolves from blur
Counters, KPIs Numbers count up with the chart that drives them
Long content It scrolls slowly inside its clip and returns
Logo row (showcase only) A marquee moving exactly one full set per loop
Media player The playhead and progress advance
  • Start and end on the exact design. At rest the frame equals ?still. Clear inline styles a story set (style.transform = '') rather than leaving translate(0), which antialiases differently and fails the rest check.
  • Use the design's own elements. Helpers a story needs match the design's style and are absent from ?still.
  • Text changes only when it is the point: counters (live text in the design's font, landing on the design's exact text) and typing (one glyph every 45-70 ms, caret at the edge; deleting runs a little faster).
  • Obvious, not busy. A card with a story shows a clear beat every one to two seconds; if a viewer cannot tell it is animated within two seconds, the story is too timid. A calm screen may rest after load if the user prefers; ask once.
  • Text-only cards get no story. They rise with their card and rest.
  • Readable in the 800×500 GIF. A moving element under about 4 px there gets enlarged within the design's style or a bigger story.
  • Offset the cards. Stories never act in unison; attention travels in reading order.
  • One story per card, 3 to 8 s. A short story may run twice in the story phase; every run ends at rest before the dissolve.
  • Stories are eased keyframe tracks on the JS clock:
// [[time, value], ...] eased per segment; values may be numbers or arrays
const easeInOut = t => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2); // --io, never past 1
function track(keys, t, ease = easeInOut) {
  if (t <= keys[0][0]) return keys[0][1];
  for (let i = 1; i < keys.length; i++) {
    const [t1, v1] = keys[i], [t0, v0] = keys[i - 1];
    if (t <= t1) {
      const k = ease(Math.min(1, (t - t0) / (t1 - t0 || 1)));
      return Array.isArray(v0) ? v0.map((v, j) => v + (v1[j] - v) * k) : v0 + (v1 - v0) * k;
    }
  }
  return keys[keys.length - 1][1];
}

Accents sit on top of a story, never instead of one, and only on elements the design already has: a pulse ring on a live indicator or play button (1.8-2.2 s, ring 1 → 2.6, opacity 0.55 → 0), a sheen on a photo or button (a band 38% wide, 1.5 s pass every 3.4 s), a skeleton glimmer on placeholder lines (2.4 s). Accents and helpers fade in over 0.6 s once the intro lands, and are gone before the dissolve. None of them ships running on a website.

The loop cycle (showcase)

Phase Default
Build in 0 → 2.4 s
Stories 2.4 → 11.0 s
Dissolve 11.0 → 11.6 s (opacity, 0.5 s)
Empty beat 11.6 → 12.0 s

The story phase holds at least one full story of every card; lengthen the cycle rather than cut one short. The dissolve returns to the empty state: an app frame dissolves only its contents, separate cards dissolve too, the background never. Reset everything: one frame with transitions disabled resets the CSS, and every JS-driven value (masks, tracks, helpers, typed text, pulses) goes back to its empty value too, or it ghosts through the empty beat. The live page keeps its stories running forever after the intro; only ?loop and the exports cycle.

Easing and camera

Token Curve Use
--e cubic-bezier(0.16, 1, 0.3, 1) Entrance transforms
--e2 cubic-bezier(0.33, 1, 0.68, 1) Opacity and blur
--io cubic-bezier(0.65, 0, 0.35, 1) Wipes, fills, sweeps, camera moves
linear linear Constant motion only (shimmer, playback)

No zoom and no pan unless asked. When asked, only the app frame scales toward the items, with --io, and it is back at rest before the dissolve.

Website sections

On a website the intro starts when about 30% of the section is visible (IntersectionObserver, once; never a scroll listener), the story pauses off screen and resumes on return, stagger stays inside the section, and prefers-reduced-motion: reduce shows the final state with no story. Map the page section by section: bento and feature cards with a visual get the card intro and a story; a product or dashboard mockup gets the loading intro, and a story only if the user says yes when asked; text-only sections (headlines, testimonials, FAQ, pricing, CTA, footer) get nothing from this skill. Under the one-moment rule, propose one section, not all of them.

Defaults

Value Default
Rise 10 px (up), 8 px (down), 10 px (left), 24 px + scale(0.985) (card), 40 px (tray)
Entrance blur 4 px; cards 6 px; photos 14 px
Pop start scale 0.82-0.88
Durations (showcase) transforms 1.05 s --e (cards 0.9 s); opacity and blur 0.7-0.8 s --e2 (cards 0.6 s); wipes 0.7 s, slow bars 1.1 s --io
Durations (website) 50-700 ms
Stagger containers 80-90 ms, items 30-80 ms
Typing one glyph per 45-70 ms, caret blink 1 s (showcase only)
Story starts 2.4 s, 3-8 s per card, offset between cards
Cycle 12 s (dissolve 11.0, reset 11.6), longer when a story needs it
Exports MP4 60 fps CRF 15 up to 1920×1200; loop GIF 960 px 20 fps; small GIF 800×500 20 fps

Adapted from Elaya's ai-design-skills design-to-motion (MIT, © 2026 Elaya), rewritten for gstack. See NOTICE.md.