gstack/design-motion/sections/motion.md

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.