@liqweed/motion-kit 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/runtime/scene.mjs CHANGED
@@ -1,4 +1,5 @@
1
1
  /** @import { Style } from "./style.mjs" */
2
+ /** @import { LabelBox } from "./iso.mjs" */
2
3
  // SPDX-License-Identifier: MIT
3
4
  // Copyright (c) 2026 Ophir Radnitz
4
5
  /**
@@ -11,6 +12,7 @@
11
12
  * duration, // seconds until the final state
12
13
  * title, description, // accessible name + description
13
14
  * stepLabelsInFrame?: boolean, // false for narrative steps (default true)
15
+ * labelBoxes?(t) → LabelBox[], // the boxes of the labels drawn at t, for the gate
14
16
  * steps: [{ at, label, detail?, id? }], // build steps; last = finished diagram
15
17
  * frame(t, { idPrefix }) → string // inner SVG markup at time t
16
18
  * }
@@ -40,7 +42,10 @@ import { normalizeStyle, cssVars, resolveTokens } from "./style.mjs";
40
42
  * An animated diagram as a pure function of time (see the module comment).
41
43
  * `contrastPairs`: token pairs the scene draws beyond CONTRAST_PAIRS
42
44
  * (runtime/style.mjs), which the gate checks the style against.
43
- * @typedef {{ id: string, width: number, height: number, duration: number, title: string, description: string, steps: Step[], frame: (t: number, ctx: FrameContext) => string, stepLabelsInFrame?: boolean, contrastPairs?: { fg: string, bg: string, min: number, use?: string }[], type?: string, format?: string, locale?: string }} Scene
45
+ * `labelBoxes`: the box of every label `frame(t)` draws, in the picture's
46
+ * coordinates (`labelAnchor` returns one); the gate fails a scene whose labels
47
+ * overlap, whose stems cross a label, or that leave the picture (runtime/iso.mjs).
48
+ * @typedef {{ id: string, width: number, height: number, duration: number, title: string, description: string, steps: Step[], frame: (t: number, ctx: FrameContext) => string, stepLabelsInFrame?: boolean, contrastPairs?: { fg: string, bg: string, min: number, use?: string }[], labelBoxes?: (t: number) => LabelBox[], type?: string, format?: string, locale?: string }} Scene
44
49
  */
45
50
 
46
51
  /** Formats: name → viewBox. Layouts are computed per format, never cropped. */
@@ -94,6 +99,7 @@ export function validateScene(scene) {
94
99
  if (!Number.isFinite(scene[key]) || scene[key] <= 0) throw new Error(`scene ${scene.id}: ${key} must be a positive finite number`);
95
100
  }
96
101
  if (typeof scene.frame !== "function") throw new Error(`scene ${scene.id}: frame must be a function`);
102
+ if (scene.labelBoxes !== undefined && typeof scene.labelBoxes !== "function") throw new Error(`scene ${scene.id}: labelBoxes must be a function`);
97
103
  if (!Array.isArray(scene.steps) || !scene.steps.length) throw new Error(`scene ${scene.id}: needs at least one step`);
98
104
  let prev = -Infinity;
99
105
  const ids = new Set();
package/runtime/style.mjs CHANGED
@@ -1,3 +1,4 @@
1
+ /** @import { Motion } from "./motion.mjs" */
1
2
  // SPDX-License-Identifier: MIT
2
3
  // Copyright (c) 2026 Ophir Radnitz
3
4
  /**
@@ -10,12 +11,14 @@
10
11
  * viewers do not understand CSS variables.
11
12
  *
12
13
  * A style is plain data:
13
- * { name, font, radius, stroke, light: {token: color}, dark: {token: color} }
14
+ * { name, font, radius, stroke, motion, light: {token: color}, dark: {token: color} }
14
15
  */
16
+ import { DEFAULT_MOTION } from "./motion.mjs";
15
17
 
16
18
  /**
17
- * A visual style: font, shape constants and one colour per token, per theme.
18
- * @typedef {{ name?: string, font: string, radius: number, stroke: number, light: Record<string, string>, dark: Record<string, string> }} Style
19
+ * A visual style: font, shape constants, the entrance and movement curves and
20
+ * one colour per token, per theme.
21
+ * @typedef {{ name?: string, font: string, radius: number, stroke: number, motion: Motion, light: Record<string, string>, dark: Record<string, string> }} Style
19
22
  */
20
23
 
21
24
  export const TOKENS = [
@@ -34,6 +37,7 @@ export const NEUTRAL = Object.freeze({
34
37
  font: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif',
35
38
  radius: 10,
36
39
  stroke: 2,
40
+ motion: DEFAULT_MOTION,
37
41
  light: Object.freeze({
38
42
  bg: "#ffffff",
39
43
  surface: "#f3f4f6",
@@ -61,6 +65,33 @@ export function tok(name) {
61
65
  return `var(--mk-${name})`;
62
66
  }
63
67
 
68
+ /**
69
+ * A style's `motion` with any missing curve taken from the defaults. A curve
70
+ * is four numbers, as in CSS `cubic-bezier(x1, y1, x2, y2)`: x between 0 and 1
71
+ * (CSS's own rule) and y between 0 and 1 too, because no motion-kit curve
72
+ * overshoots.
73
+ * @param {any} motion
74
+ * @param {string} name the style's name, for the error
75
+ * @returns {Motion}
76
+ */
77
+ function normalizeMotion(motion, name) {
78
+ if (motion === undefined) return DEFAULT_MOTION;
79
+ if (!motion || typeof motion !== "object" || Array.isArray(motion)) throw new Error(`style "${name}": motion must be an object with enter and move curves`);
80
+ for (const key of Object.keys(motion)) {
81
+ if (key !== "enter" && key !== "move") throw new Error(`style "${name}": unknown motion curve "${key}" (known: enter, move)`);
82
+ }
83
+ const out = { enter: DEFAULT_MOTION.enter, move: DEFAULT_MOTION.move };
84
+ for (const key of /** @type {const} */ (["enter", "move"])) {
85
+ const c = motion[key];
86
+ if (c === undefined) continue;
87
+ if (!Array.isArray(c) || c.length !== 4 || !c.every((n) => Number.isFinite(n) && n >= 0 && n <= 1)) {
88
+ throw new Error(`style "${name}": motion.${key} must be four numbers from 0 to 1 (a cubic-bezier that does not overshoot), got ${JSON.stringify(c)}`);
89
+ }
90
+ out[key] = Object.freeze(/** @type {[number, number, number, number]} */ ([...c]));
91
+ }
92
+ return Object.freeze(out);
93
+ }
94
+
64
95
  /** Fill in any missing fields from NEUTRAL and validate token names. */
65
96
  export function normalizeStyle(style) {
66
97
  if (!style || style === "neutral") return NEUTRAL;
@@ -69,6 +100,7 @@ export function normalizeStyle(style) {
69
100
  font: style.font ?? NEUTRAL.font,
70
101
  radius: style.radius ?? NEUTRAL.radius,
71
102
  stroke: style.stroke ?? NEUTRAL.stroke,
103
+ motion: normalizeMotion(style.motion, style.name ?? "custom"),
72
104
  light: { ...NEUTRAL.light, ...(style.light ?? {}) },
73
105
  dark: { ...NEUTRAL.dark, ...(style.dark ?? style.light ?? {}) },
74
106
  };
package/runtime/svg.mjs CHANGED
@@ -8,6 +8,7 @@
8
8
  * here; numbers are rounded here. Numbers you interpolate into a template
9
9
  * string yourself (transform, points, path d) must go through `num()`.
10
10
  */
11
+ import { easeStandard, progress } from "./motion.mjs";
11
12
 
12
13
  const ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
13
14
 
@@ -163,3 +164,49 @@ export function drawOn(length, p) {
163
164
  if (p >= 1) return {};
164
165
  return { "stroke-dasharray": `${num(length)} ${num(length)}`, "stroke-dashoffset": num(length * (1 - p)) };
165
166
  }
167
+
168
+ /* ------------------------------------------------------------------ tokens */
169
+
170
+ /**
171
+ * One token's journey: it starts at `start` s and takes `duration` s along
172
+ * `path` (default: the path given to the function), on `ease` (default
173
+ * `easeStandard`). It is drawn while it travels; with `hold` it stays at the
174
+ * end of the path once it has arrived.
175
+ * @typedef {{ start: number, duration: number, path?: { at: (f: number) => any }, ease?: (p: number) => number, hold?: boolean }} TokenRun
176
+ */
177
+
178
+ /**
179
+ * Where each of several tokens is at time t. Any number of tokens may travel
180
+ * at once, on one path or each on its own; a token not yet started, or
181
+ * arrived without `hold`, is left out. A scene keeps the steps settled by
182
+ * having every token arrive, and be gone, before the step's time.
183
+ * @param {{ at: (f: number) => any }} path anything with `at(fraction) → point`: `polyline`, `cubic`, `path3`
184
+ * @param {number} t
185
+ * @param {TokenRun[]} runs
186
+ * @returns {{ index: number, progress: number, point: any, run: TokenRun }[]}
187
+ */
188
+ export function tokenPoints(path, t, runs) {
189
+ const out = [];
190
+ for (const [index, run] of runs.entries()) {
191
+ const p = progress(t, run.start, run.duration, run.ease ?? easeStandard);
192
+ if (p <= 0 || (p >= 1 && !run.hold)) continue;
193
+ out.push({ index, progress: p, point: (run.path ?? path).at(p), run });
194
+ }
195
+ return out;
196
+ }
197
+
198
+ /**
199
+ * Several tokens travelling at once: `draw(point, { index, progress, run })`
200
+ * for each token in flight, concatenated. Pure like every frame helper, so any
201
+ * frame is the same whatever was drawn before it.
202
+ * @param {{ at: (f: number) => any }} path
203
+ * @param {number} t
204
+ * @param {TokenRun[]} runs
205
+ * @param {(point: any, info: { index: number, progress: number, run: TokenRun }) => string} draw
206
+ * @returns {string}
207
+ */
208
+ export function tokensAlong(path, t, runs, draw) {
209
+ return tokenPoints(path, t, runs)
210
+ .map(({ point, index, progress, run }) => draw(point, { index, progress, run }))
211
+ .join("");
212
+ }
@@ -26,7 +26,7 @@
26
26
  * shape: "box" (default) | "round" | "pill" | "decision".
27
27
  * Strings may be localized objects: { en: "...", nl: "..." }.
28
28
  */
29
- import { easeOut, easeStandard, progress } from "../motion.mjs";
29
+ import { progress, easings } from "../motion.mjs";
30
30
  import { FONT_MIN, maxFontSize, rectEdge } from "../parts.mjs";
31
31
  import { FORMATS, localize, withId } from "../scene.mjs";
32
32
  import { NEUTRAL, tok } from "../style.mjs";
@@ -333,6 +333,7 @@ export function flowchart(spec, { format = "16:9", locale = "en" } = {}) {
333
333
 
334
334
  /** @param {number} t @param {{ style?: Style }} [ctx] */
335
335
  function frame(t, { style = NEUTRAL } = {}) {
336
+ const { easeOut, easeStandard } = easings(style.motion);
336
337
  const enter = (/** @type {number} */ r) => progress(t, rankIndex(r) * ENTER_GAP, ENTER, easeOut);
337
338
  const out = [];
338
339
  const drawn = edges.map((_, i) => progress(t, backward[i] ? fillStart(edgeStep[i]) - 0.1 : drawStart(edgeStep[i]), backward[i] ? DRAW - 0.05 : DRAW, easeStandard));
@@ -17,7 +17,7 @@
17
17
  * direction?: "out" | "in", // default "out"
18
18
  * fontSize?: number }
19
19
  */
20
- import { easeOut, easeStandard, progress, window01 } from "../motion.mjs";
20
+ import { progress, window01, easings } from "../motion.mjs";
21
21
  import { boxNode, FONT_MIN, maxFontSize, rectEdge } from "../parts.mjs";
22
22
  import { FORMATS, localize, withId } from "../scene.mjs";
23
23
  import { NEUTRAL, tok } from "../style.mjs";
@@ -166,6 +166,7 @@ export function hubSpoke(spec, { format = "16:9", locale = "en" } = {}) {
166
166
 
167
167
  /** @param {number} t @param {{style?: Style}} [ctx] */
168
168
  function frame(t, { style = NEUTRAL } = {}) {
169
+ const { easeOut, easeStandard } = easings(style.motion);
169
170
  const out = [];
170
171
  const sEnter = (i) => progress(t, spokeEnter(i), ENTER, easeOut);
171
172
  links.forEach((link, i) => {
@@ -17,7 +17,7 @@
17
17
  * fontSize?: number }
18
18
  * Strings may be localized objects: { en: "...", nl: "..." }.
19
19
  */
20
- import { easeOut, easeStandard, progress } from "../motion.mjs";
20
+ import { progress, easings } from "../motion.mjs";
21
21
  import { circleNode, FONT_MIN, maxFontSize, stateLabel } from "../parts.mjs";
22
22
  import { FORMATS, localize, withId } from "../scene.mjs";
23
23
  import { NEUTRAL, tok } from "../style.mjs";
@@ -157,6 +157,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
157
157
 
158
158
  /** @param {number} t @param {{style?: Style}} [ctx] */
159
159
  function frame(t, { style = NEUTRAL } = {}) {
160
+ const { easeOut, easeStandard } = easings(style.motion);
160
161
  const enter = (k) => progress(t, k * ENTER_GAP, ENTER, easeOut);
161
162
  const active = (k) => progress(t, fillStart(k), FILL, easeStandard);
162
163
  const out = [];
@@ -21,7 +21,7 @@
21
21
  * Layout: one column of full-width layers with the rail on their right, in
22
22
  * every format; layers get taller (up to a limit) where the format has room.
23
23
  */
24
- import { easeOut, easeStandard, lerp, progress } from "../motion.mjs";
24
+ import { lerp, progress, easings } from "../motion.mjs";
25
25
  import { FONT_MIN, maxFontSize } from "../parts.mjs";
26
26
  import { FORMATS, localize, withId } from "../scene.mjs";
27
27
  import { NEUTRAL, tok } from "../style.mjs";
@@ -169,7 +169,7 @@ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
169
169
  const stepAt = (k) => fillStart(k) + FILL;
170
170
  const duration = stepAt(n - 1) + TAIL;
171
171
 
172
- function packetY(t) {
172
+ function packetY(t, easeStandard) {
173
173
  let y = stops[0];
174
174
  for (let k = 0; k < n; k++) {
175
175
  const p = progress(t, hopStart(k), HOP, easeStandard);
@@ -183,6 +183,7 @@ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
183
183
 
184
184
  /** @param {number} t @param {{style?: Style}} [ctx] */
185
185
  function frame(t, { style = NEUTRAL } = {}) {
186
+ const { easeOut, easeStandard } = easings(style.motion);
186
187
  const out = [];
187
188
  const { railX } = fitted;
188
189
  // Rail: draws on from the entry end while the layers rise; an arrowhead marks the exit.
@@ -194,7 +195,7 @@ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
194
195
  const s = direction === "down" ? -1 : 1;
195
196
  out.push(el("path", { d: `M${num(railX - 6)} ${num(exitY + s * 9)} L${num(railX)} ${num(exitY)} L${num(railX + 6)} ${num(exitY + s * 9)}`, fill: "none", stroke: tok("line"), "stroke-width": style.stroke, "stroke-linecap": "round", "stroke-linejoin": "round", opacity: head }));
196
197
  }
197
- const y = packetY(t);
198
+ const y = packetY(t, easeStandard);
198
199
  if (Math.abs(y - entryY) > 0.5) out.push(vline(railX, entryY, y, { stroke: tok("accent"), "stroke-width": style.stroke * 1.5 }));
199
200
  fitted.boxes.forEach((b, li) => {
200
201
  const enter = progress(t, riseAt(li), RISE, easeOut);
@@ -23,7 +23,7 @@
23
23
  * below when they need the width (wide aspects and square); a vertical axis
24
24
  * with labels on the right (9:16, tall).
25
25
  */
26
- import { easeOut, easeStandard, lerp, progress, springSettleTime, springStep } from "../motion.mjs";
26
+ import { lerp, progress, springSettleTime, springStep, easings } from "../motion.mjs";
27
27
  import { FONT_MIN, maxFontSize, stateLabel } from "../parts.mjs";
28
28
  import { FORMATS, localize, withId } from "../scene.mjs";
29
29
  import { NEUTRAL, tok } from "../style.mjs";
@@ -296,7 +296,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
296
296
  if (now && L.nowAt) stops.push({ to: along(L.nowAt), at: nowStart });
297
297
  const axisLen = L.dir === "h" ? ax.x1 - ax.x0 : ax.y1 - ax.y0;
298
298
 
299
- function accentEnd(t) {
299
+ function accentEnd(t, easeStandard) {
300
300
  let end = start;
301
301
  let from = start;
302
302
  for (const s of stops) {
@@ -312,6 +312,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
312
312
  el("path", { d: L.dir === "h" ? `M${num(a)} ${num(ax.y0)} H${num(b)}` : `M${num(ax.x0)} ${num(a)} V${num(b)}`, fill: "none", "stroke-linecap": "round", ...attrs });
313
313
 
314
314
  function milestone(t, it, k, style) {
315
+ const { easeOut, easeStandard } = easings(style.motion);
315
316
  const p = L.at(k);
316
317
  const b = beat(k);
317
318
  const drop = progress(t, b + 0.05, DROP, easeOut);
@@ -355,6 +356,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
355
356
  }
356
357
 
357
358
  function nowMarker(t, style) {
359
+ const { easeOut } = easings(style.motion);
358
360
  if (!now || !L.nowAt || !L.nowPill) return "";
359
361
  const shown = progress(t, nowStart, NOW_FADE, easeOut);
360
362
  if (shown <= 0) return "";
@@ -372,6 +374,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
372
374
 
373
375
  /** @param {number} t @param {{style?: Style}} [ctx] */
374
376
  function frame(t, { style = NEUTRAL } = {}) {
377
+ const { easeOut, easeStandard } = easings(style.motion);
375
378
  const out = [];
376
379
  // Axis: pending line draws on; an arrowhead at its end shows the direction of time.
377
380
  const axisDash = drawOn(axisLen, progress(t, 0, AXIS, easeStandard));
@@ -381,7 +384,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
381
384
  const d = L.dir === "h" ? `M${num(ax.x1 - 9)} ${num(ax.y1 - 6)} L${num(ax.x1)} ${num(ax.y1)} L${num(ax.x1 - 9)} ${num(ax.y1 + 6)}` : `M${num(ax.x1 - 6)} ${num(ax.y1 - 9)} L${num(ax.x1)} ${num(ax.y1)} L${num(ax.x1 + 6)} ${num(ax.y1 - 9)}`;
382
385
  out.push(el("path", { d, fill: "none", stroke: tok("line"), "stroke-width": style.stroke, "stroke-linecap": "round", "stroke-linejoin": "round", opacity: head }));
383
386
  }
384
- const end = accentEnd(t);
387
+ const end = accentEnd(t, easeStandard);
385
388
  if (end - start > 0.5) out.push(line(start, end, { stroke: tok("accent"), "stroke-width": style.stroke * 1.5 }));
386
389
  items.forEach((it, k) => out.push(milestone(t, it, k, style)));
387
390
  out.push(nowMarker(t, style));
@@ -3,7 +3,7 @@
3
3
  // SPDX-License-Identifier: MIT
4
4
  // Copyright (c) 2026 Ophir Radnitz
5
5
  /** Small, explicitly narrated graphs. Layout is computed once, never in frame(). */
6
- import { easeOut, easeStandard, progress, lerp } from "../motion.mjs";
6
+ import { progress, lerp, easings } from "../motion.mjs";
7
7
  import { FONT_MIN, maxFontSize } from "../parts.mjs";
8
8
  import { FORMATS, localize } from "../scene.mjs";
9
9
  import { NEUTRAL, tok } from "../style.mjs";
@@ -117,6 +117,7 @@ export function walk(spec, { format = "16:9", locale = "en" } = {}) {
117
117
  const duration = stepAt(route.length - 1) + 0.3;
118
118
  /** @param {number} t @param {{style?: Style}} [ctx] */
119
119
  function frame(t, { style = NEUTRAL } = {}) {
120
+ const { easeOut, easeStandard } = easings(style.motion);
120
121
  const entrance = progress(t, 0, 0.5, easeOut);
121
122
  const active = nodes.map(() => 0);
122
123
  active[visits[0]] = progress(t, 0.5, 0.2, easeStandard);
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: animated-diagram
3
- description: "Build animated, interactive explanatory diagrams (process flows, hub-and-spoke integrations, build-up sequences) as deterministic scenes — pure functions of time — with motion-kit. One scene serves a live web page or Craft Page, Slidev slides (one build step per click), standalone SVG/PNG slide frames, a zero-JS baked SVG, and MP4/GIF video. Use when asked to 'animate a diagram', 'make an animated/interactive diagram or explainer', 'build-up slide', 'diagram that plays step by step', or to turn a process/architecture description into motion. For exporting/rendering an existing scene (PNG, video, social formats) use motion-render."
3
+ description: "Build animated, interactive explanatory diagrams (process flows, hub-and-spoke integrations, build-up sequences) as deterministic scenes — pure functions of time — with motion-kit. One scene serves a live web page or Craft Page, Slidev slides (one build step per click), standalone SVG/PNG slide frames, a zero-JS baked SVG, and MP4/GIF video. Use when asked to 'animate a diagram', 'make an animated/interactive diagram or explainer', 'build-up slide', 'diagram that plays step by step', or to turn a process/architecture description into motion. For exporting/rendering an existing scene (PNG, video, social formats) use motion-render. Not for page or component micro-interactions (hover, press, toast, menu), faux product-UI demos or walkthroughs of an app screen, hero or feature-card illustrations, or decorative and looping effects: those belong to a UI animation or design skill."
4
4
  ---
5
5
 
6
6
  # Animated diagram (motion-kit)
@@ -57,7 +57,8 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
57
57
  `state-machine`, `request-journey`, `flowchart`). The user has a Mermaid
58
58
  flowchart? `motion-kit import flow.mmd --out flow.json` writes the spec
59
59
  (layout computed once). Only write a custom scene module when no type fits
60
- (`references/custom-scenes.md`).
60
+ (`references/custom-scenes.md`): that file also covers an isometric view
61
+ (camera, solids, depth order, label anchors) and several tokens moving at once.
61
62
  4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
62
63
  shipped: deterministic, settled steps, rounded numbers, token-only colours,
63
64
  escaped labels, labels fit, holds the final frame.
@@ -112,7 +113,7 @@ headers when redistributing the vendored runtime and adapters.
112
113
  | `references/targets.md` | Where it will be shown and what each target allows |
113
114
  | `references/styles.md` | Neutral default, style files, brand presets, contrast |
114
115
  | `references/qc.md` | Review stages, checklist, review-report template |
115
- | `references/custom-scenes.md` | Writing a one-off scene module |
116
+ | `references/custom-scenes.md` | Writing a one-off scene module, including isometric views and several tokens at once |
116
117
  | `references/ecosystem.md` | When GSAP, HyperFrames, Remotion, Motion Canvas, Manim, Mermaid or ELK are the better tool |
117
118
 
118
119
  For rendering, slide packaging and video, see the **motion-render** skill.
@@ -110,6 +110,55 @@ Every command supports this, `motion-kit build` included (it bundles the whole
110
110
  runtime and passes it as `kit`). A module that imports instead must use
111
111
  relative imports to a vendored runtime.
112
112
 
113
+ ## Isometric and 3D-looking scenes
114
+
115
+ `kit` carries a small isometric kit (`runtime/iso.mjs`), for a floor, machines
116
+ or buildings seen from an angle. Template: `examples/isometric-swivel.scene.mjs`
117
+ (plan view that swivels to isometric, then three work items travel a line).
118
+ Everything is a pure function: the same camera and solids give the same bytes.
119
+
120
+ World: x east, y north, `z` up, in any unit you like. Colours are token names
121
+ (`"surface"`, `"accent"`), never literals; the gate refuses a literal.
122
+
123
+ | Need | Use |
124
+ |---|---|
125
+ | A camera | `camera({ azimuth, elevation, zoom, pan })`: the view's angles in degrees, pixels per world unit, and where the world origin lands. `elevation: 90` with `azimuth: 0` is the plan view (north up); `CAMERA_ISOMETRIC` is true isometric (45° azimuth, `ISO_ELEVATION` ≈ 35.26°); `CAMERA_PLAN` is the plan view |
126
+ | A swivel | `lerpCamera(from, to, progress(t, start, dur, easeStandard))`: every field interpolates, so plan → isometric is one move between two settled steps |
127
+ | Keep it in the picture | `fitCamera(worldPoints, cam, { width, height, margin })` returns `cam` with the pan and zoom that fit the points (the floor corners, the tallest heights, the route). Call it with each frame's camera, and a swivel never clips |
128
+ | A point on the screen | `project(cam, { x, y, z })` → `{ x, y, depth }` (`projector(cam)` for many points; larger `depth` is nearer the viewer) |
129
+ | Solids | `box({ x, y, w, d, h, z })` (centred on x, y), `slab({ x, y, w, d })` (a thin box, for a floor), `prism({ points, h, z })` with `regularPolygon(x, y, r, n)` for a footprint. Options: `fill` (top token), `sides` (side token, default `fill`), `shade` (token layered over the sides at 10–26 %, `null` for flat; `ink` darkens in the light theme and lightens in the dark one, pick `bg` where the dark theme should be darker), `stroke`, `opacity`, `id` |
130
+ | Draw them | `drawSolid(solid, cam)`, or `drawSolids(list, cam)`, which orders them far to near first (`orderSolids` alone returns the order). Only faces that face the camera are drawn: at 90° elevation just the tops |
131
+ | Animate a solid | Build it again each frame with the animated `h`, `z` or `opacity`. Two-state fills cross-fade two solids (`fade(p, {}, drawSolid(reached, cam))` over the pending one), as with any other element |
132
+ | Labels | `labelAnchor(cam, { id, at: { x, y, z }, lines, lift, side, opacity })` → `{ markup, box }`: a dot on the point, a stem `lift` px up, the label above it (`side: "up"`, or beside the stem's top with `"right"` / `"left"`). Wrap and localize `lines` first (`wrapLabel`) |
133
+ | Several tokens | `tokensAlong(path, t, runs, draw)`: see below |
134
+
135
+ **The gate checks labels.** Return `labelBoxes: (t) => [box, …]` from the scene
136
+ (the `box` of each `labelAnchor` you draw at `t`), and `motion-kit check` fails
137
+ the scene when, at any sampled time or step, two label boxes overlap (closer
138
+ than 4 px), a stem runs through another label, or a box leaves the picture. Fix
139
+ it in the layout: alternate `lift` between neighbours (more in a narrow format,
140
+ where they stand closer), shorten the label, or fade labels out while the
141
+ camera moves, as the example does. Boxes with `opacity: 0` are skipped.
142
+
143
+ **Several tokens at once.** `tokensAlong(path, t, runs, draw)` draws every token
144
+ in flight. `path` is anything with `at(fraction)`: `polyline`, `cubic`, or
145
+ `path3(worldPoints)`, which gives positions by distance, so a token moves at a constant speed in the
146
+ world whatever the camera does when its `ease` is linear (the default is
147
+ `easeStandard`; project each point in `draw`). `runs` is `[{ start, duration, ease?,
148
+ path?, hold? }]`, one per token, each with its own start and, if it needs one,
149
+ its own `path`; a token is drawn from `start` until it arrives (kept at the end
150
+ with `hold`). `tokenPoints` gives the positions without drawing. Stagger the
151
+ starts (`stagger()`) so the tokens do not sit on one another. Several tokens
152
+ may move at the same time **inside the story's beats only**: every token has
153
+ arrived, and the arrivals have filled, before the step's time (the settled-step
154
+ rule in the gate applies as ever), and a token that stops mid-path is not a
155
+ resting state. A token never loops back to the start.
156
+
157
+ Canon: no loops, no ambient motion, no continuous scrubbing, 12 s hard limit
158
+ (8 s target). An isometric scene plays once and holds its last frame, like any
159
+ other, and under reduced motion the player shows that frame. A constantly
160
+ moving hero is a 3D model's job, not motion-kit's.
161
+
113
162
  ## Declared locales and narrative steps
114
163
 
115
164
  Export `const locales = ["en", "nl"]` alongside the default factory so both
@@ -122,4 +171,7 @@ A scene whose step labels narrate actions rather than name visible objects
122
171
  sets `stepLabelsInFrame: false`. Those labels still belong in the player's
123
172
  controls and accessible transcript; G10 otherwise requires each label in the
124
173
  final frame. `frame(t, { idPrefix, style })` also receives the normalized style
125
- when called through `renderSvg`; custom shape styling is opt-in.
174
+ when called through `renderSvg`; custom shape styling is opt-in. So is the
175
+ style's motion: `const { easeOut, easeStandard } = kit.easings(style.motion)` (or
176
+ `easings` from `runtime/motion.mjs`) gives the curves its `motion` names, the
177
+ neutral ones when it names none.
@@ -9,6 +9,7 @@ Checked Nov 2026. Re-verify licences before commercial use.
9
9
  | **GSAP** (incl. DrawSVG, MorphSVG, MotionPath, SplitText) | free incl. commercial since 3.13 (not for competing no-code builders) | Rich page motion, morphing, text splitting | Paused timelines are seekable (`tl.seek(t)`), so determinism holds. ~70 KB must be inlined for Craft Pages. Use for website polish; keep explainers in motion-kit |
10
10
  | **Motion Canvas / Revideo** | MIT | Hand-crafted technical explainer *videos* with generator timelines | Good for one-off videos; no live-page reuse |
11
11
  | **Manim CE** | MIT | Mathematics and science visuals, equations | Python; video only |
12
+ | **React effect libraries** (Magic UI `animated-beam`, Aceternity beams) | Magic UI: MIT (checked Nov 2026) | A few animated connectors on a page that already renders React; the first thing a design engineer reaches for | `hub-spoke` draws the same "integrations" picture with no framework, and also exports slide frames, a zero-JS baked SVG and video. Use the library for decoration on a React page; use motion-kit when the picture must appear in other media too |
12
13
  | **Mermaid** | MIT | Static diagrams from text; quick structure | Flowcharts import directly: `motion-kit import flow.mmd` (layout at build time). State diagrams: write a `state-machine` spec |
13
14
  | **ELK.js / dagre** | EPL-2.0 / MIT | Automatic layout of graphs larger than a scene's 12 nodes | `motion-kit import` has its own small layered layout; for more, run one at build time in Node and store coordinates in the spec |
14
15
  | **Lottie / Rive** | MIT runtimes | Designer-authored animation assets | Embed as media; not data-driven |
@@ -9,6 +9,11 @@
9
9
  | `easeIn` | `cubic-bezier(.4, 0, 1, 1)` | exits (rare in explainers) |
10
10
  | `linear` | — | only for things that should feel mechanical (progress bars) |
11
11
 
12
+ A style can replace `easeOut` and `easeStandard` for its diagrams (`motion` in
13
+ `styles.md`); scene types and custom scenes get them from `easings(style.motion)`,
14
+ so write `const { easeOut, easeStandard } = kit.easings(style.motion)` in a
15
+ custom scene's `frame` rather than importing the constants.
16
+
12
17
  ## Timing budget
13
18
 
14
19
  | Event | Duration |
@@ -49,6 +54,29 @@ little later with the same curve: the shape stretches in flight and settles at
49
54
  its own length. `splitEdge(t, start, dur, lag = 0.07)` → `{ lead, trail }`.
50
55
  Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
51
56
 
57
+ ## Camera swivel, depth and several tokens (isometric kit)
58
+
59
+ - **Swivel:** a camera move is one beat on `easeStandard`, 1.2–1.5 s, from one
60
+ settled view to another (plan → isometric is `lerpCamera(plan, iso, p)`).
61
+ Nothing else but the things that need the new view (solids rising to their
62
+ height) moves with it. Fit the camera to the picture each frame, so no frame
63
+ of the swivel clips.
64
+ - **Labels and a moving camera:** fade labels out before the camera moves and
65
+ back in after it rests (≈ 250–400 ms each): text is not read mid-swivel,
66
+ and its boxes cannot collide while it is hidden. The gate checks the boxes at
67
+ every sampled time.
68
+ - **Heights:** solids rise during the swivel, not before it: in plan view
69
+ height is invisible. Draw a flat top first (`h` > 0 only so the faces exist).
70
+ - **Depth:** `orderSolids` is the order; never draw by hand. Heights and
71
+ footprints decide it; a floor slab is drawn first.
72
+ - **Several tokens:** stagger their starts by 0.25–0.4 s on a trip of 1.2–2 s,
73
+ so 3–4 are in flight at once without touching. Use `linear` for tokens that
74
+ travel a conveyor at a steady speed, and grow them in and out over the first
75
+ and last ≈ 8 % of the trip, so they do not pop. All have arrived, and their
76
+ targets have filled, ≥ 50 ms before the step (the usual pause between beats).
77
+ A shadow on the floor under each token (an ellipse of `ink` at ≈ 18 %,
78
+ squashed by `sin(elevation)`) shows where it is in the world.
79
+
52
80
  ## Container and text timing
53
81
 
54
82
  - The container (box, card) starts moving immediately; new text appears only
@@ -56,6 +84,30 @@ Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
56
84
  - Labels never move while being read: animate the node, not its label.
57
85
  - Cross-fade text colour (muted → ink) together with the node's fill.
58
86
 
87
+ ## Where this departs from interface-motion standards
88
+
89
+ Other design skills (Emil Kowalski's `choreograph`, `review-animations`,
90
+ `animate`; Impeccable's `animate`) set rules for interface feedback: a hover, a
91
+ menu, a toast. A diagram that explains is not that, and an agent that has those
92
+ skills installed will "fix" what follows unless it knows these are decided. The
93
+ rule is: **this file decides how a scene moves; those skills decide how the page
94
+ around it moves.** A finding from them against a scene type is an issue, not an
95
+ edit.
96
+
97
+ | Their rule | What a scene does | Why |
98
+ |---|---|---|
99
+ | Interface motion stays under 300 ms | Entrances run 300–600 ms, the whole scene up to 8 s | A viewer reads a diagram while it builds; feedback is felt, not read. Speed that suits a button hides which node came first |
100
+ | Stagger is non-uniform (`choreograph`: "Uniform stagger is forbidden") | `sequence` enters its nodes on a uniform `k * ENTER_GAP`, siblings 80–150 ms apart in reading order | The gap is the order. An uneven rhythm reads as emphasis the data does not have; a viewer counts nodes by the beat |
101
+ | Fade or scale in from a rest state, feel alive | Nothing moves at a step's `at`; step frames are settled | A step frame is exported as a slide, a still and a poster. It must be the picture, not a frame mid-move |
102
+ | Interrupt-friendly, spring-based motion | Closed-form critically damped springs and fixed timelines; a seek jumps, it does not retarget | Same `t`, same bytes: export, video and the gate depend on it |
103
+ | Keep animating on repeat, or ambient motion for delight | One build, then hold; no loops, no ambient motion | Looping decoration competes with the text beside the diagram |
104
+ | Skip animation on high-frequency surfaces | Every scene animates, but `prefers-reduced-motion` shows the final frame | A diagram is opened to be watched, once; reduced motion keeps the content and drops the travel |
105
+
106
+ What does carry over: no `transition: all`, animate `transform` and `opacity`
107
+ in the page around a diagram, honour reduced motion, and never overshoot. A
108
+ style's `motion` curves (`styles.md`) are how a diagram takes on the page's own
109
+ curve without changing any of the above.
110
+
59
111
  ## Banned in explainers
60
112
 
61
113
  Bounce and elastic easing · parallax · looping or auto-advancing carousels ·
@@ -102,7 +102,9 @@ names a state. Each path edge must start where the previous one ended; branches,
102
102
  cycles, repeated transitions and self-transitions are supported. The path is
103
103
  explicit: the runtime never decides which branch to take. All states appear
104
104
  pending, the initial state fills, then a single token follows the path while
105
- the current state fills accent. Completed edges retain their accent.
105
+ the current state fills accent. Completed edges retain their accent. The
106
+ built-in types carry one token at a time; a custom scene that needs several
107
+ pieces of work moving at once uses `tokensAlong` (`custom-scenes.md`).
106
108
 
107
109
  Layouts use a column in reading order with separate connector lanes outside
108
110
  the labels; each fixed format centers the fitted graph, and strips grow to
@@ -27,6 +27,7 @@ properties (light + dark); standalone exports resolve them to literals.
27
27
  "font": "Inter, ui-sans-serif, system-ui, sans-serif",
28
28
  "radius": 10,
29
29
  "stroke": 2,
30
+ "motion": { "enter": [0.16, 1, 0.3, 1], "move": [0.4, 0, 0.2, 1] },
30
31
  "light": { "accent": "#0a2a8a", "emphasis": "#05966a" },
31
32
  "dark": { "accent": "#2563eb", "emphasis": "#a7f3d0" }
32
33
  }
@@ -44,6 +45,24 @@ stems at 0.75×. These settings affect live, SVG, PNG, bake and video rendering.
44
45
  Custom scenes receive the normalized style through `frame(t, { style })` and
45
46
  may use it explicitly; their own geometry is not rewritten.
46
47
 
48
+ ## Motion
49
+
50
+ `motion` names the two curves the scene types use, as the four numbers of a CSS
51
+ `cubic-bezier(x1, y1, x2, y2)`: `enter` for entrances and `move` for movement
52
+ between two visible states (fills, hops, draw-on). Both default to the curves in
53
+ `motion-vocabulary.md` (`0, 0, .2, 1` and `.4, 0, .2, 1`), so a style that sets
54
+ neither moves as before. Use it to match the page the diagram sits on: a site
55
+ that names `cubic-bezier(0.23, 1, 0.32, 1)` as its curve sets
56
+ `"move": [0.23, 1, 0.32, 1]`.
57
+
58
+ Every number is from 0 to 1, so no curve overshoots (no bounce); anything else
59
+ throws. Only the shape of a move changes: durations, delays and the times of the
60
+ steps do not, so step frames stay settled. A curve that ends flat, as the
61
+ defaults and most easing curves do, is used exactly. One that is still moving at
62
+ its end (a linear `[0, 0, 1, 1]`, an ease-in) would leave a step frame
63
+ unsettled, so it finishes in the first 95 % of each move and holds for the last
64
+ 5 %. Custom scenes read `kit.easings(style.motion)` for the same two curves.
65
+
47
66
  ## Contrast
48
67
 
49
68
  `motion-kit check --style acme.json …` checks every token pair the scene types
@@ -3,6 +3,10 @@
3
3
  "font": "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", \"Helvetica Neue\", Helvetica, Arial, sans-serif",
4
4
  "radius": 10,
5
5
  "stroke": 2,
6
+ "motion": {
7
+ "enter": [0, 0, 0.2, 1],
8
+ "move": [0.4, 0, 0.2, 1]
9
+ },
6
10
  "light": {
7
11
  "bg": "#ffffff",
8
12
  "surface": "#f3f4f6",