paper-motion

Explainer

explainer

How something works in three steps on one card that changes state, with a recap and a close, in 36 s.

Install
$ npx paper-motion add explainer

Writes a scene to pieces/, wired to your brand folder.

Tune it, then add it to your kit
Parameters
question
action
background
format
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>explainer</title>
<!--
  Recipe · explainer (36 s). How something works, in steps.
  One idea: the steps are STATIONS on a line in space, left to right. The camera dollies along the line, leaning into
  the direction of travel (yaw) and settling in front of each station; the previous one slides off to the side,
  soft. The recap is the camera pulling BACK until all three stations are in frame at once; the close is a slow
  push onto the name.
  Question 0–3 s · Steps 3–27 s · Recap 27–32 s · Close 32–36 s.
  Look, fonts, pace and sound come from /brand (serve from the project root). Edit CONFIG first; show real material
  inside each step when there is some.
-->
<style>
  #stage { overflow: hidden; }
  .abs { position: absolute; box-sizing: border-box; }
  .place { display: flex; flex-direction: column; align-items: center; text-align: center; box-sizing: border-box; }
  .card { box-sizing: border-box; display: flex; flex-direction: column; align-items: flex-start; text-align: left; overflow: hidden; }
</style>
</head>
<body>
<main id="stage">
  <div id="bg" class="abs" style="inset:0"></div>
  <div id="vig" class="abs" style="inset:0"></div>
  <div id="world">
    <div id="p-q" class="place"><div id="question"></div></div>
    <div id="rail"></div>
    <div id="p-close" class="place"><div id="mark"></div><div id="action"></div></div>
  </div>
</main>
<script type="module">
import { scene, progress, ease } from 'paper-motion';
import { wordRise, blurIn, popIn } from 'paper-motion/moves';
import { camera } from 'paper-motion/kit';
import { loadBrand } from 'paper-motion/brand';

const CONFIG = {
  background: null,
  backgroundOpacity: 0.55,                 // the shader behind the type; 1 for a field with no words over it
  question: 'How does it work?',
  steps: [
    { label: '01', title: 'First', body: 'What happens first, in one line.' },
    { label: '02', title: 'Then', body: 'The step that does the work.' },
    { label: '03', title: 'Done', body: 'What you get at the end.' },
  ],
  action: 'your.site',
  format: [1920, 1080],
};

const B = await loadBrand();
const [W, H] = CONFIG.format, SHORT = Math.min(W, H), D = 36;
const s = scene({ width: W, height: H, fps: 30, duration: D, background: B.color('ground') });
const bgId = CONFIG.background ?? B.set.entries.find((e) => e.shader && !e.image)?.id;
if (bgId) B.shader(s, '#bg', bgId);
const bg = document.querySelector('#bg'); bg.style.opacity = CONFIG.backgroundOpacity;
document.querySelector('#vig').style.background = 'radial-gradient(ellipse at 50% 55%, rgba(0,0,0,0) 30%, rgba(0,0,0,0.6) 100%)';
const $ = (id) => document.getElementById(id);

// the line: stations STEP apart along x; the camera reads each from DIST in front; the recap sees them all from FAR
const STEP = SHORT * 1.25, DIST = SHORT * 0.7, FAR = SHORT * 2.35, K = 1 + DIST / (SHORT * 1.7);
const cam = camera($('stage'), $('world'), { perspective: SHORT * 1.7 });
const question = B.style($('question'), 'display', { short: SHORT * K });
const mark = B.style($('mark'), 'display', { short: SHORT * K }), action = B.style($('action'), 'body', { short: SHORT * K, color: 'figure' });
Object.assign(action.style, { fontFamily: B.font('mono'), fontSize: `${SHORT * K * 0.028}px`, letterSpacing: '0em', marginTop: `${SHORT * 0.03}px` });
question.textContent = CONFIG.question; mark.textContent = B.name; action.textContent = CONFIG.action;
question.style.maxWidth = '16ch';
for (const id of ['p-q', 'p-close']) $(id).style.width = `${W * 0.9}px`;
// a thin rail the stations stand on: the line made visible
const rail = $('rail');
Object.assign(rail.style, { width: `${STEP * (CONFIG.steps.length + 1)}px`, height: '2px', background: `${B.color('muted')}66` });
cam.place(rail, { x: STEP * (CONFIG.steps.length - 1) / 2, y: SHORT * 0.36 * K, z: -SHORT * 0.1 });
cam.place($('p-q'), { x: -STEP, z: SHORT * 0.15, yaw: -6 });
const R = (B.tokens?.shape?.radius ?? 12) * (SHORT / 1080) * K;
const cw = SHORT * 0.92 * K, ch = cw * 0.56;
const steps = CONFIG.steps.map((p, i) => {
  const c = document.createElement('div');
  c.className = 'card';
  const light = i === 1;
  Object.assign(c.style, { width: `${cw}px`, height: `${ch}px`, padding: `${cw * 0.07}px`, borderRadius: `${R}px`, background: light ? B.color('accent', '#E9E4D8') : B.surface(), border: `1.5px solid ${light ? 'transparent' : B.color('muted') + '55'}`, boxShadow: `0 ${SHORT * 0.03}px ${SHORT * 0.1}px rgba(0,0,0,0.45)` });
  c.innerHTML = `<div data-part="label"></div><div data-part="title"></div><div data-part="body"></div>`;
  const set = (el, role, color) => { B.style(el, role, { short: SHORT * K, color: light ? 'ground' : color }); return el; };
  set(c.children[0], 'caption', 'muted').textContent = p.label;
  set(c.children[1], 'display', 'figure').textContent = p.title;
  set(c.children[2], 'body', 'muted').textContent = p.body;
  c.children[1].style.marginTop = `${SHORT * 0.02}px`; c.children[2].style.marginTop = 'auto';
  Object.assign(c.children[2].style, { fontSize: `${SHORT * K * 0.03}px`, lineHeight: 1.35, maxWidth: '26ch' });
  $('world').append(c);
  // on the line, each turned a few degrees toward where the camera comes from
  cam.place(c, { x: STEP * i, y: [0, -SHORT * 0.03, SHORT * 0.02][i], z: [0, -SHORT * 0.05, 0][i], yaw: [-8, 0, 8][i] });
  return c;
});
cam.place($('p-close'), { x: STEP * CONFIG.steps.length, z: -SHORT * 0.2 });
await document.fonts.ready;
for (const el of [question, mark]) { const k = (W * 0.84) / el.scrollWidth; if (k < 1) el.style.fontSize = `${parseFloat(el.style.fontSize) * k}px`; }

// the dolly: along the line, leaning forward on the way; the recap pulls back; the close pushes in
const T = { s1: 3, s2: 11, s3: 19, recap: 27, close: 32 };
const atX = (x, extra = {}) => ({ x, z: DIST, ...extra });
const mid = STEP * (CONFIG.steps.length - 1) / 2;
const path = [
  [0, atX(-STEP, { y: 0, yaw: -4, pitch: 0 })],
  [T.s1 - 0.6, atX(-STEP, { yaw: -5 })],
  [T.s1 + 1.0, atX(0, { yaw: -6 }), ease.inOutCubic],
  [T.s1 + 1.6, atX(0, { yaw: 0 }), ease.outCubic],
  [T.s2 - 0.6, atX(0)],
  [T.s2 + 1.0, atX(STEP, { y: -SHORT * 0.03, yaw: -7 }), ease.inOutCubic],
  [T.s2 + 1.6, atX(STEP, { y: -SHORT * 0.03, yaw: 0 }), ease.outCubic],
  [T.s3 - 0.6, atX(STEP, { y: -SHORT * 0.03 })],
  [T.s3 + 1.0, atX(STEP * 2, { y: SHORT * 0.02, yaw: -7 }), ease.inOutCubic],
  [T.s3 + 1.6, atX(STEP * 2, { y: SHORT * 0.02, yaw: 0 }), ease.outCubic],
  [T.recap - 0.6, atX(STEP * 2, { y: SHORT * 0.02 })],
  [T.recap + 1.4, { x: mid, y: 0, z: FAR, yaw: 0, pitch: 0 }, ease.inOutQuart],        // pull back: all three at once
  [T.close - 0.4, { x: mid, y: 0, z: FAR, pitch: 0 }],
  [T.close + 1.2, { x: STEP * CONFIG.steps.length, y: 0, z: DIST * 0.95 - SHORT * 0.2, pitch: 0 }, ease.inOutQuart],
  [D, { x: STEP * CONFIG.steps.length, z: DIST * 0.88 - SHORT * 0.2 }, ease.inOutSine],
];
s.update((t) => {
  cam.travel(t, path);
  // depth of field follows the camera; wide open for the recap so all stations read
  const wide = progress(t, T.recap, T.recap + 1.4) * (1 - progress(t, T.close, T.close + 1.2));
  // wide for the recap: all three stations present and sharp, the question and the close out of frame
  cam.focus(DIST + (FAR - DIST) * wide, SHORT * (0.9 + 1.3 * wide), 10, { fade: SHORT * (0.8 + 1.3 * wide) });
  bg.style.transform = `scale(${1.1 + 0.06 * progress(t, 0, D)}) translateX(${-SHORT * 0.08 * progress(t, 0, D)}px)`;
  wordRise(question, t, { start: 0.3, each: B.pace.stagger, duration: 0.9 });
  const starts = [T.s1 + 0.3, T.s2 + 0.3, T.s3 + 0.3];
  steps.forEach((c, i) => { popIn(c.children[1], t, { start: starts[i] }); blurIn(c.children[2], t, { start: starts[i] + 0.4, duration: 0.6 }); });
  wordRise(mark, t, { start: T.close + 0.1, each: B.pace.stagger, duration: 0.9 });
  blurIn(action, t, { start: T.close + 0.8, duration: 0.8 });
});
B.cue(s, 'land', 0.3); for (const k of ['s1', 's2', 's3']) { B.cue(s, 'transition', T[k]); B.cue(s, 'land', T[k] + 1.0); }
B.cue(s, 'transition', T.recap); B.cue(s, 'land', T.recap + 1.4); B.cue(s, 'transition', T.close); B.cue(s, 'land', T.close + 1.2);
B.sound(s);
await s.start();
</script>
</body>
</html>
Defaults

Structure

Explainer01 / 04
Question
what this answers, naming the brand
0.0 / 36 s
02Steps
03Recap
04Close
0 s36 s
  1. 010–2.8 sQuestionwhat this answers, naming the brand
  2. 023.6–26.6 sStepsthree steps on one card that changes state
  3. 0327.4–31.6 sRecapall steps at once, small
  4. 0432.4–36 sClosethe ending and the action

The script, sketched: the beats in order and their length, in the brand's colors and type. The clip above is the engine's render of the same recipe.

Notes

  • Wired to the brand folder: needs brand/tokens.json (a palette and a font pair work: pamo add sage-night instrument) and, for the background, a shader-set entry (pamo add mesh-sage).
  • Structure and timing only; the look always comes from the brand.
  • Uses these moves from the engine: push, magic-move, unfold, crossfade, word-rise, blur-in.

Spec

Id
explainer
Type
Recipes
Version
1.0.0
Engine
>=0.2.0
License
MIT

Related