@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/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +4 -2
- package/docs/spec/technique.md +73 -3
- package/examples/isometric-swivel.scene.mjs +171 -0
- package/lib/check.mjs +33 -0
- package/package.json +4 -3
- package/runtime/iso.mjs +583 -0
- package/runtime/kit.mjs +7 -5
- package/runtime/motion.mjs +61 -0
- package/runtime/scene.mjs +7 -1
- package/runtime/style.mjs +35 -3
- package/runtime/svg.mjs +47 -0
- package/runtime/types/flowchart.mjs +2 -1
- package/runtime/types/hub-spoke.mjs +2 -1
- package/runtime/types/sequence.mjs +2 -1
- package/runtime/types/stack.mjs +4 -3
- package/runtime/types/timeline.mjs +6 -3
- package/runtime/types/walk.mjs +2 -1
- package/skills/animated-diagram/SKILL.md +4 -3
- package/skills/animated-diagram/references/custom-scenes.md +53 -1
- package/skills/animated-diagram/references/ecosystem.md +1 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +52 -0
- package/skills/animated-diagram/references/scene-types.md +3 -1
- package/skills/animated-diagram/references/styles.md +19 -0
- package/styles/neutral.json +4 -0
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
|
-
*
|
|
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
|
|
18
|
-
*
|
|
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 = { "&": "&", "<": "<", ">": ">", '"': """, "'": "'" };
|
|
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 {
|
|
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 {
|
|
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 {
|
|
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 = [];
|
package/runtime/types/stack.mjs
CHANGED
|
@@ -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 {
|
|
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 {
|
|
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));
|
package/runtime/types/walk.mjs
CHANGED
|
@@ -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 {
|
|
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
|
package/styles/neutral.json
CHANGED
|
@@ -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",
|