Explainer
explainerHow 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 explainerWrites 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
- 010–2.8 sQuestionwhat this answers, naming the brand
- 023.6–26.6 sStepsthree steps on one card that changes state
- 0327.4–31.6 sRecapall steps at once, small
- 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
- Data
- r/explainer.json