@liqweed/motion-kit 0.0.0-stage → 0.2.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 +13 -0
- package/.claude-plugin/plugin.json +9 -0
- package/LICENSE +21 -0
- package/README.md +119 -2
- package/adapters/astro/AnimatedDiagram.astro +55 -0
- package/adapters/page/README.md +22 -0
- package/adapters/slidev/AnimatedDiagram.vue +137 -0
- package/brand/logo.scene.mjs +115 -0
- package/cli/motion-kit.mjs +239 -0
- package/docs/spec/technique.md +447 -0
- package/examples/agent-loop.json +18 -0
- package/examples/custom-pulse.scene.mjs +141 -0
- package/examples/integrations.json +20 -0
- package/examples/order-flow.json +17 -0
- package/examples/release-pipeline.json +17 -0
- package/examples/smart-home.json +17 -0
- package/lib/build.mjs +62 -0
- package/lib/bundle.mjs +68 -0
- package/lib/check.mjs +86 -0
- package/lib/export.mjs +113 -0
- package/lib/icon.mjs +41 -0
- package/lib/load.mjs +53 -0
- package/lib/raster.mjs +69 -0
- package/lib/video.mjs +77 -0
- package/package.json +69 -5
- package/runtime/bake.mjs +61 -0
- package/runtime/motion.mjs +154 -0
- package/runtime/parts.mjs +123 -0
- package/runtime/player.mjs +207 -0
- package/runtime/scene.mjs +101 -0
- package/runtime/style.mjs +142 -0
- package/runtime/svg.mjs +165 -0
- package/runtime/types/hub-spoke.mjs +215 -0
- package/runtime/types/index.mjs +25 -0
- package/runtime/types/sequence.mjs +201 -0
- package/runtime/wrap.mjs +44 -0
- package/skills/animated-diagram/SKILL.md +90 -0
- package/skills/animated-diagram/references/custom-scenes.md +56 -0
- package/skills/animated-diagram/references/ecosystem.md +28 -0
- package/skills/animated-diagram/references/interactivity.md +38 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +70 -0
- package/skills/animated-diagram/references/qc.md +41 -0
- package/skills/animated-diagram/references/scene-types.md +59 -0
- package/skills/animated-diagram/references/styles.md +55 -0
- package/skills/animated-diagram/references/targets.md +27 -0
- package/skills/animated-diagram/references/technique.md +148 -0
- package/skills/motion-render/SKILL.md +68 -0
- package/skills/motion-render/references/formats.md +18 -0
- package/skills/motion-render/references/slides.md +18 -0
- package/skills/motion-render/references/video.md +61 -0
- package/skills/project-logo/SKILL.md +72 -0
- package/skills/project-logo/references/design.md +22 -0
- package/skills/project-logo/references/discovery.md +15 -0
- package/skills/project-logo/references/external-prompt.md +23 -0
- package/styles/neutral.json +26 -0
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Copyright (c) 2026 Ophir Radnitz
|
|
3
|
+
/**
|
|
4
|
+
* motion-kit · scene type "sequence".
|
|
5
|
+
*
|
|
6
|
+
* Helps the viewer understand: one thing passes through ordered stages.
|
|
7
|
+
* Storyboard: every node appears in reading order (skeleton first, so the whole
|
|
8
|
+
* structure is visible), then an emphasis ring — the thing itself — travels
|
|
9
|
+
* node to node; each node it reaches fills with the accent colour and the path
|
|
10
|
+
* behind it turns accent. Every step frame reads as "you are here".
|
|
11
|
+
*
|
|
12
|
+
* Spec:
|
|
13
|
+
* { type: "sequence", id, title, description,
|
|
14
|
+
* nodes: [{ label, detail?, glyph?, icon? }], // 2–12 nodes
|
|
15
|
+
* glyphs?: "numbers" | "none" // default "numbers"
|
|
16
|
+
* fontSize?: number }
|
|
17
|
+
* Strings may be localized objects: { en: "...", nl: "..." }.
|
|
18
|
+
*/
|
|
19
|
+
import { easeOut, easeStandard, progress } from "../motion.mjs";
|
|
20
|
+
import { circleNode, FONT_MIN, stateLabel } from "../parts.mjs";
|
|
21
|
+
import { FORMATS, localize } from "../scene.mjs";
|
|
22
|
+
import { tok } from "../style.mjs";
|
|
23
|
+
import { drawOn, el, polyline, trimSegment } from "../svg.mjs";
|
|
24
|
+
import { wrapLabel } from "../wrap.mjs";
|
|
25
|
+
|
|
26
|
+
// Timeline (seconds). Steps are settled because PERIOD ≥ HOP + FILL.
|
|
27
|
+
const ENTER_GAP = 0.1;
|
|
28
|
+
const ENTER = 0.4;
|
|
29
|
+
const FILL = 0.25;
|
|
30
|
+
const HOP = 0.4;
|
|
31
|
+
const PERIOD = HOP + FILL + 0.05;
|
|
32
|
+
const TAIL = 0.4;
|
|
33
|
+
|
|
34
|
+
const PAD = 24;
|
|
35
|
+
const CHAR = 0.56; // average glyph width / font size
|
|
36
|
+
|
|
37
|
+
function pickArrangement(format, n) {
|
|
38
|
+
const { width: W, height: H } = format;
|
|
39
|
+
if (format.name === "tall" || (H > 0 && W / H < 0.8)) return { rows: n, cols: 1, labels: "right" };
|
|
40
|
+
const aspect = H > 0 ? W / H : 4;
|
|
41
|
+
if (aspect >= 1.5) {
|
|
42
|
+
const cellW = (W - 2 * PAD) / n;
|
|
43
|
+
if (cellW >= 96) return { rows: 1, cols: n, labels: "below" };
|
|
44
|
+
return { rows: 2, cols: Math.ceil(n / 2), labels: "below" };
|
|
45
|
+
}
|
|
46
|
+
const rows = n <= 3 ? 1 : n <= 8 ? 2 : 3;
|
|
47
|
+
return { rows, cols: Math.ceil(n / rows), labels: "below" };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function layout(format, n, fs) {
|
|
51
|
+
const arr = pickArrangement(format, n);
|
|
52
|
+
const W = format.width;
|
|
53
|
+
const fixed = format.height > 0;
|
|
54
|
+
const lineH = fs * 1.25;
|
|
55
|
+
if (arr.labels === "right") {
|
|
56
|
+
const r = fixed ? Math.round(fs * 1.4) : 20;
|
|
57
|
+
const cellH = fixed ? Math.min(fs * 9, (format.height - 2 * PAD) / n) : 76;
|
|
58
|
+
const H = fixed ? format.height : cellH * (n - 1) + 2 * r + 2 * PAD + 8;
|
|
59
|
+
const top = (H - cellH * (n - 1)) / 2;
|
|
60
|
+
const cx = PAD + r + 4;
|
|
61
|
+
const labelX = cx + r + 14;
|
|
62
|
+
const maxChars = Math.floor((W - labelX - PAD) / (fs * CHAR));
|
|
63
|
+
const centers = Array.from({ length: n }, (_, i) => ({ x: cx, y: top + i * cellH }));
|
|
64
|
+
return { W, H, r, fs, lineH, maxChars, maxLines: 2, centers, cols: 1, label: (c) => ({ x: labelX, y: c.y, anchor: "start", baseline: "central" }) };
|
|
65
|
+
}
|
|
66
|
+
const { rows, cols } = arr;
|
|
67
|
+
const cellW = (W - 2 * PAD) / cols;
|
|
68
|
+
const r = Math.max(16, Math.min(fs * 1.9, cellW * 0.2));
|
|
69
|
+
const maxLines = 2;
|
|
70
|
+
const blockH = 2 * r + 12 + maxLines * lineH;
|
|
71
|
+
const gapY = fixed ? Math.max(28, Math.min(fs * 4, (format.height - 2 * PAD - rows * blockH) / Math.max(1, rows - 1) / 2)) : 28;
|
|
72
|
+
const H = fixed ? format.height : rows * blockH + (rows - 1) * gapY + 2 * PAD + 8;
|
|
73
|
+
const usedH = rows * blockH + (rows - 1) * gapY;
|
|
74
|
+
const top = (H - usedH) / 2 + r;
|
|
75
|
+
// Leave room on both sides for the elbow connectors of a snake grid.
|
|
76
|
+
const maxChars = Math.floor((cellW - 10) / (fs * CHAR));
|
|
77
|
+
const centers = [];
|
|
78
|
+
for (let k = 0; k < n; k++) {
|
|
79
|
+
const row = Math.floor(k / cols);
|
|
80
|
+
const inRow = k % cols;
|
|
81
|
+
const col = row % 2 === 0 ? inRow : cols - 1 - inRow; // snake
|
|
82
|
+
centers.push({ x: PAD + cellW * (col + 0.5), y: top + row * (blockH + gapY) });
|
|
83
|
+
}
|
|
84
|
+
return { W, H, r, fs, lineH, maxChars, maxLines, centers, cols, cellW, label: (c) => ({ x: c.x, y: c.y + r + 12, anchor: "middle", baseline: "hanging" }) };
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** Largest font (≤ max) at which every label fits its budget. */
|
|
88
|
+
function fit(f, nodes, locale, maxFs) {
|
|
89
|
+
let lastErr;
|
|
90
|
+
for (let fs = maxFs; fs >= FONT_MIN; fs--) {
|
|
91
|
+
const L = layout(f, nodes.length, fs);
|
|
92
|
+
if (L.maxChars < 6) continue;
|
|
93
|
+
try {
|
|
94
|
+
const lines = nodes.map((node) => wrapLabel(localize(node.label, locale), L.maxChars, L.maxLines));
|
|
95
|
+
return { L, lines };
|
|
96
|
+
} catch (e) {
|
|
97
|
+
lastErr = e;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
throw lastErr ?? new Error("does not fit");
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Connector between consecutive nodes. Same row/column: a straight segment.
|
|
105
|
+
* A snake-grid row turn: an elbow routed outside the column, clear of labels.
|
|
106
|
+
*/
|
|
107
|
+
function connector(a, b, r, W, grid, cellW) {
|
|
108
|
+
if (grid && Math.abs(a.x - b.x) < 1) {
|
|
109
|
+
const side = a.x > W / 2 ? 1 : -1;
|
|
110
|
+
// Beyond the widest possible label (cellW − 10), inside the canvas padding.
|
|
111
|
+
const out = a.x + side * (cellW / 2 + PAD / 2);
|
|
112
|
+
const p = { x: a.x + side * (r + 6), y: a.y };
|
|
113
|
+
const q = { x: b.x + side * (r + 6), y: b.y };
|
|
114
|
+
return {
|
|
115
|
+
path: polyline([p, { x: out, y: a.y }, { x: out, y: b.y }, q]),
|
|
116
|
+
ring: polyline([a, { x: out, y: a.y }, { x: out, y: b.y }, b]),
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
const [p, q] = trimSegment(a, b, r + 6);
|
|
120
|
+
return { path: polyline([p, q]), ring: polyline([a, b]) };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
|
|
124
|
+
const nodes = spec.nodes ?? [];
|
|
125
|
+
if (nodes.length < 2 || nodes.length > 12) throw new Error(`sequence "${spec.id}": needs 2–12 nodes, got ${nodes.length}`);
|
|
126
|
+
const f = typeof format === "string" ? { name: format, ...FORMATS[format] } : format;
|
|
127
|
+
if (!f.width) throw new Error(`unknown format "${format}"`);
|
|
128
|
+
const n = nodes.length;
|
|
129
|
+
const maxFs = spec.fontSize ?? (f.height > 0 ? 22 : 16);
|
|
130
|
+
let fitted;
|
|
131
|
+
try {
|
|
132
|
+
fitted = fit(f, nodes, locale, maxFs);
|
|
133
|
+
} catch (e) {
|
|
134
|
+
throw new Error(`sequence "${spec.id}": labels do not fit format ${f.name} at ≥ ${FONT_MIN}px: ${e instanceof Error ? e.message : e}`);
|
|
135
|
+
}
|
|
136
|
+
const { L } = fitted;
|
|
137
|
+
|
|
138
|
+
const items = nodes.map((node, i) => ({
|
|
139
|
+
label: localize(node.label, locale),
|
|
140
|
+
detail: localize(node.detail, locale),
|
|
141
|
+
lines: fitted.lines[i],
|
|
142
|
+
node: { ...node, glyph: node.icon ? undefined : (node.glyph ?? (spec.glyphs === "none" ? "" : String(i + 1))) },
|
|
143
|
+
}));
|
|
144
|
+
|
|
145
|
+
const START = ENTER_GAP * (n - 1) + ENTER + 0.1;
|
|
146
|
+
const FIRST_HOP = START + FILL + 0.25;
|
|
147
|
+
const hopStart = (k) => FIRST_HOP + k * PERIOD;
|
|
148
|
+
const fillStart = (k) => (k === 0 ? START : hopStart(k - 1) + HOP);
|
|
149
|
+
const stepAt = (k) => fillStart(k) + FILL;
|
|
150
|
+
const duration = stepAt(n - 1) + TAIL;
|
|
151
|
+
const ringR = L.r + 6;
|
|
152
|
+
|
|
153
|
+
// Elbows run on the canvas edge side, so the vertical turn of a snake grid
|
|
154
|
+
// never crosses a label.
|
|
155
|
+
const segs = L.centers.slice(1).map((c, i) => connector(L.centers[i], c, L.r, L.W, L.cols > 1, L.cellW));
|
|
156
|
+
|
|
157
|
+
function frame(t) {
|
|
158
|
+
const enter = (k) => progress(t, k * ENTER_GAP, ENTER, easeOut);
|
|
159
|
+
const active = (k) => progress(t, fillStart(k), FILL, easeStandard);
|
|
160
|
+
const out = [];
|
|
161
|
+
// Connectors: pending line once both ends are in, accent draw-on during the hop.
|
|
162
|
+
segs.forEach((s, k) => {
|
|
163
|
+
const shown = Math.min(enter(k), enter(k + 1));
|
|
164
|
+
const common = { d: s.path.d, fill: "none", "stroke-linecap": "round", "stroke-linejoin": "round" };
|
|
165
|
+
if (shown > 0) out.push(el("path", { ...common, stroke: tok("line"), "stroke-width": 2, opacity: shown }));
|
|
166
|
+
const dash = drawOn(s.path.length, progress(t, hopStart(k), HOP, easeStandard));
|
|
167
|
+
if (dash) out.push(el("path", { ...common, stroke: tok("accent"), "stroke-width": 3, ...dash }));
|
|
168
|
+
});
|
|
169
|
+
items.forEach((it, k) => {
|
|
170
|
+
const c = L.centers[k];
|
|
171
|
+
out.push(circleNode({ cx: c.x, cy: c.y, r: L.r, enter: enter(k), active: active(k), node: it.node }));
|
|
172
|
+
out.push(stateLabel({ ...L.label(c), lines: it.lines, fontSize: L.fs, enter: enter(k), active: active(k) }));
|
|
173
|
+
});
|
|
174
|
+
// Emphasis ring: appears on node 1, then hops.
|
|
175
|
+
const appear = progress(t, START, FILL, easeOut);
|
|
176
|
+
if (appear > 0) {
|
|
177
|
+
let pos = L.centers[0];
|
|
178
|
+
for (let k = 0; k < n - 1; k++) {
|
|
179
|
+
const p = progress(t, hopStart(k), HOP, easeStandard);
|
|
180
|
+
if (p <= 0) break;
|
|
181
|
+
pos = segs[k].ring.at(p);
|
|
182
|
+
}
|
|
183
|
+
out.push(el("circle", { cx: pos.x, cy: pos.y, r: ringR * (0.85 + 0.15 * appear), fill: "none", stroke: tok("emphasis"), "stroke-width": 3, opacity: appear }));
|
|
184
|
+
}
|
|
185
|
+
return out.join("");
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
return {
|
|
189
|
+
id: `${spec.id}-${f.name.replace(":", "x")}`,
|
|
190
|
+
type: "sequence",
|
|
191
|
+
format: f.name,
|
|
192
|
+
locale,
|
|
193
|
+
width: L.W,
|
|
194
|
+
height: L.H,
|
|
195
|
+
duration,
|
|
196
|
+
title: localize(spec.title, locale),
|
|
197
|
+
description: localize(spec.description, locale),
|
|
198
|
+
steps: items.map((it, k) => ({ at: stepAt(k), label: it.label, detail: it.detail })),
|
|
199
|
+
frame,
|
|
200
|
+
};
|
|
201
|
+
}
|
package/runtime/wrap.mjs
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Copyright (c) 2026 Ophir Radnitz
|
|
3
|
+
/**
|
|
4
|
+
* motion-kit · label wrapping.
|
|
5
|
+
*
|
|
6
|
+
* SVG text does not wrap, so every layout declares a character budget. Labels
|
|
7
|
+
* break at spaces and after a slash ("Archive/Dispose" → "Archive/", "Dispose").
|
|
8
|
+
* Overflow throws, so a long translation fails the checks instead of spilling
|
|
9
|
+
* out of its box. Budget for Dutch/German being ~30 % longer than English.
|
|
10
|
+
*/
|
|
11
|
+
export function wrapLabel(label, maxChars, maxLines = 2) {
|
|
12
|
+
const tokens = String(label)
|
|
13
|
+
.split(/\s+/)
|
|
14
|
+
.filter(Boolean)
|
|
15
|
+
// A standalone separator ("A / B", "A – B") sticks to the word before it,
|
|
16
|
+
// so no line ever starts with "/" or "–".
|
|
17
|
+
.reduce((acc, w) => {
|
|
18
|
+
if (/^[\/–—&+|]$/.test(w) && acc.length) acc[acc.length - 1] += ` ${w}`;
|
|
19
|
+
else acc.push(w);
|
|
20
|
+
return acc;
|
|
21
|
+
}, /** @type {string[]} */ ([]))
|
|
22
|
+
.flatMap((word) => word.split(/(?<=\/)(?=[^\s])/).map((part, i) => ({ part, space: i === 0 })));
|
|
23
|
+
const lines = [];
|
|
24
|
+
let cur = "";
|
|
25
|
+
for (const { part, space } of tokens) {
|
|
26
|
+
if (part.length > maxChars) throw new Error(`label "${label}": "${part}" is longer than ${maxChars} characters`);
|
|
27
|
+
const joined = cur === "" ? part : `${cur}${space ? " " : ""}${part}`;
|
|
28
|
+
if (joined.length <= maxChars) cur = joined;
|
|
29
|
+
else {
|
|
30
|
+
lines.push(cur);
|
|
31
|
+
cur = part;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
if (cur) lines.push(cur);
|
|
35
|
+
if (lines.length > maxLines) {
|
|
36
|
+
throw new Error(`label "${label}" needs ${lines.length} lines at ${maxChars} chars; the layout allows ${maxLines}`);
|
|
37
|
+
}
|
|
38
|
+
return lines;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Rough rendered width of a line, in px, for a sans-serif face. */
|
|
42
|
+
export function estimateWidth(line, fontSize) {
|
|
43
|
+
return line.length * fontSize * 0.56;
|
|
44
|
+
}
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
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."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Animated diagram (motion-kit)
|
|
7
|
+
|
|
8
|
+
A scene is `frame(t) → SVG markup`, a pure function of time. Players own the
|
|
9
|
+
clock; exporters sample exact times; video samples `t = f / fps`. Read
|
|
10
|
+
`references/technique.md` before writing a custom scene or changing the runtime.
|
|
11
|
+
|
|
12
|
+
## Locate the toolkit
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
MK="$HOME/workspace/motion-kit" # canonical clone (has node_modules)
|
|
16
|
+
[ -d "$MK" ] || MK="$(cd "<this skill's base directory>/../.." && pwd)" # plugin copy
|
|
17
|
+
node "$MK/cli/motion-kit.mjs" --help
|
|
18
|
+
```
|
|
19
|
+
Node ≥ 22. PNG/video need `@resvg/resvg-js` (`npm install` in `$MK`) and `ffmpeg`.
|
|
20
|
+
|
|
21
|
+
## Workflow
|
|
22
|
+
|
|
23
|
+
1. **Brief: ask before building** (one message, skip what's already known):
|
|
24
|
+
- What should the viewer *understand* after watching? (one sentence)
|
|
25
|
+
- Where will it be shown? → target, see `references/targets.md`
|
|
26
|
+
(Craft Page · in-chat preview · Slidev/Marp/PowerPoint · website · README/vault · video)
|
|
27
|
+
- Which formats? (16:9, 4:3, 1:1, 9:16, wide strip, tall phone column)
|
|
28
|
+
- Languages? (labels may be `{ "en": "...", "nl": "..." }`)
|
|
29
|
+
- **Visual style:** neutral (default) / a style file (`--style brand.json`) /
|
|
30
|
+
describe one → I write a style file. See `references/styles.md`.
|
|
31
|
+
- Approved copy and claims. **Never invent numbers, metrics or claims.**
|
|
32
|
+
2. **Storyboard → approval.** Pick a scene type (`references/scene-types.md`).
|
|
33
|
+
Write the spec, then render the step contact sheet and show it:
|
|
34
|
+
`motion-kit export spec.json -o <scratch>/sb --png --qc` → open `index.html`
|
|
35
|
+
or show the PNGs. Get a yes on the *story* before polishing.
|
|
36
|
+
3. **Build.** Spec-driven types first (`sequence`, `hub-spoke`). Only write a
|
|
37
|
+
custom scene module when no type fits (`references/custom-scenes.md`).
|
|
38
|
+
4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
|
|
39
|
+
shipped: deterministic, settled steps, rounded numbers, token-only colours,
|
|
40
|
+
escaped labels, labels fit, holds the final frame.
|
|
41
|
+
5. **QC.** `references/qc.md`: before/after frames around each step, phone
|
|
42
|
+
size, real-time playback (never trust virtual-time screenshots), reduced
|
|
43
|
+
motion, dark mode. **A human approves the look**: green checks don't show it.
|
|
44
|
+
6. **Deliver** per target (`references/targets.md`) and write down where the
|
|
45
|
+
spec lives so it can be edited and re-rendered later.
|
|
46
|
+
|
|
47
|
+
## Hard rules
|
|
48
|
+
|
|
49
|
+
- Plays once and holds the final frame (loops only for ambient status displays).
|
|
50
|
+
- One entrance ≤ 600 ms, siblings staggered 80–150 ms, whole scene ≤ ~8 s.
|
|
51
|
+
- No bounce/elastic, no parallax, no ambient motion inside an explainer.
|
|
52
|
+
- Every motion must answer "what does this help the viewer understand?".
|
|
53
|
+
- Skeleton first, then fill: show the whole structure, then walk through it.
|
|
54
|
+
- One emphasis colour, one emphasis element.
|
|
55
|
+
- Step frames are settled: the next motion starts at or after the step's `at`.
|
|
56
|
+
- Long text belongs in HTML captions (`detail`), not in the SVG.
|
|
57
|
+
- Always a pause control (WCAG 2.2.2); reduced motion = final frame, no autoplay.
|
|
58
|
+
- No `Date`, `Math.random`, `performance.now` inside a scene.
|
|
59
|
+
|
|
60
|
+
## Quick recipes
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
|
|
64
|
+
mk types; mk formats
|
|
65
|
+
mk check diagram.json # all formats × locales
|
|
66
|
+
mk build diagram.json -o diagram.html -f wide -l nl # Craft Page / standalone
|
|
67
|
+
mk export diagram.json -o out/ --png --qc # slides + review sheet
|
|
68
|
+
mk bake diagram.json -o diagram.svg -f wide # zero-JS animated SVG
|
|
69
|
+
mk video diagram.json -f 9:16 -o reel.mp4 --sheet sheet.png
|
|
70
|
+
mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Vendoring includes the full MIT `LICENSE`. Keep that file and the SPDX
|
|
74
|
+
headers when redistributing the vendored runtime and adapters.
|
|
75
|
+
|
|
76
|
+
## References
|
|
77
|
+
|
|
78
|
+
| File | Read when |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `references/technique.md` | Always for custom scenes or runtime changes: the model, determinism rules, timeline authoring, lessons learned |
|
|
81
|
+
| `references/scene-types.md` | Choosing a type; spec fields; storyboards for types not built yet |
|
|
82
|
+
| `references/motion-vocabulary.md` | Easing, timing budgets, springs, split edges, container/text timing |
|
|
83
|
+
| `references/interactivity.md` | Player controls, scrubber, hover-linking, scroll-driven, explorables, a11y |
|
|
84
|
+
| `references/targets.md` | Where it will be shown and what each target allows |
|
|
85
|
+
| `references/styles.md` | Neutral default, style files, brand presets, contrast |
|
|
86
|
+
| `references/qc.md` | Review stages, checklist, review-report template |
|
|
87
|
+
| `references/custom-scenes.md` | Writing a one-off scene module |
|
|
88
|
+
| `references/ecosystem.md` | When GSAP, HyperFrames, Remotion, Motion Canvas, Manim, Mermaid or ELK are the better tool |
|
|
89
|
+
|
|
90
|
+
For rendering, slide packaging and video, see the **motion-render** skill.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# Custom scenes
|
|
2
|
+
|
|
3
|
+
When no scene type fits, write a module. Template: `examples/custom-pulse.scene.mjs`.
|
|
4
|
+
|
|
5
|
+
```js
|
|
6
|
+
// my-diagram.scene.mjs. Import ONLY from motion-kit's runtime, single-line
|
|
7
|
+
// relative imports (the HTML builder inlines modules line by line).
|
|
8
|
+
import { easeOut, easeStandard, progress } from "../runtime/motion.mjs";
|
|
9
|
+
import { FORMATS, localize } from "../runtime/scene.mjs";
|
|
10
|
+
import { tok } from "../runtime/style.mjs";
|
|
11
|
+
import { el, fade, num, text } from "../runtime/svg.mjs";
|
|
12
|
+
|
|
13
|
+
export default function make({ format = "16:9", locale = "en" } = {}) {
|
|
14
|
+
const { width, height } = FORMATS[format];
|
|
15
|
+
// timeline constants …
|
|
16
|
+
return {
|
|
17
|
+
id: `my-diagram-${format.replace(":", "x")}`, width, height,
|
|
18
|
+
duration: 4.2,
|
|
19
|
+
title: localize({ en: "…", nl: "…" }, locale),
|
|
20
|
+
description: localize({ en: "…", nl: "…" }, locale),
|
|
21
|
+
steps: [{ at: 1.2, label: "…", detail: "…" }, …],
|
|
22
|
+
frame(t) { /* return inner SVG markup for time t */ },
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Rules:
|
|
28
|
+
|
|
29
|
+
- Pure: the frame depends only on `t` and constants. No clock, no randomness,
|
|
30
|
+
no module-level mutable state.
|
|
31
|
+
- Colours only via `tok()`; numbers in strings via `num()`.
|
|
32
|
+
- Use `fade()`/`el()` so invisible elements disappear; `drawOn()` for lines.
|
|
33
|
+
- Lay out per format; throw if labels don't fit (`wrapLabel`).
|
|
34
|
+
- Gate: `motion-kit check my-diagram.scene.mjs` (all formats you support; pass
|
|
35
|
+
`--format` to limit).
|
|
36
|
+
- Imports must be single-line `import { a, b } from "./relative.mjs";` and the
|
|
37
|
+
default export a function; the HTML builder supports only that subset.
|
|
38
|
+
- If the same shape is needed twice, promote it to a scene type in
|
|
39
|
+
`runtime/types/` with a spec and tests.
|
|
40
|
+
|
|
41
|
+
## Scenes outside this repository: `kit`
|
|
42
|
+
|
|
43
|
+
The CLI calls `make({ format, locale, kit })`, where `kit` is the whole
|
|
44
|
+
runtime in one flat namespace (`lib/load.mjs` `KIT`). A scene file kept in
|
|
45
|
+
another repository can destructure what it needs instead of importing:
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
export default function make({ format = "1:1", kit }) {
|
|
49
|
+
const { tok, el, num, progress, easeOut } = kit;
|
|
50
|
+
…
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Every Node-side command (check, export, bake, icon, video) supports this.
|
|
55
|
+
`motion-kit build` bundles the module for the browser and needs relative
|
|
56
|
+
imports; vendor the runtime for that.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Ecosystem: when another tool is the better choice
|
|
2
|
+
|
|
3
|
+
Checked Nov 2026. Re-verify licences before commercial use.
|
|
4
|
+
|
|
5
|
+
| Tool | Licence | Use it when | Fit with motion-kit |
|
|
6
|
+
|---|---|---|---|
|
|
7
|
+
| **HyperFrames** (heygen-com/hyperframes) | Apache-2.0 | Video with media, screen recordings, audio, longer edits, captions; HTML compositions rendered deterministically (headless Chrome + FFmpeg); ships Claude Code skills | Same seek(t) principle. A motion-kit scene can be a clip: the player exposes `window.__motionKit[id].seek(t)` for a custom-runtime adapter. Install its skills only in repos that need video editing: `npx skills add heygen-com/hyperframes` or the Claude Code plugin marketplace |
|
|
8
|
+
| **Remotion** | source-available; free for individuals and companies ≤ 3 people, paid company licence otherwise | React-based video compositions, rich templates, Lambda rendering | Official agent skills: `npx skills add remotion-dev/skills`. Prefer HyperFrames for licence simplicity unless the team already uses React video |
|
|
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
|
+
| **Motion Canvas / Revideo** | MIT | Hand-crafted technical explainer *videos* with generator timelines | Good for one-off videos; no live-page reuse |
|
|
11
|
+
| **Manim CE** | MIT | Mathematics and science visuals, equations | Python; video only |
|
|
12
|
+
| **Mermaid** | MIT | Static diagrams from text; quick structure | Use as *input notation* (flowchart/state), then lay out and animate in motion-kit |
|
|
13
|
+
| **ELK.js / dagre** | EPL-2.0 / MIT | Automatic layout of larger graphs | Run at build time in Node, store coordinates in the spec |
|
|
14
|
+
| **Lottie / Rive** | MIT runtimes | Designer-authored animation assets | Embed as media; not data-driven |
|
|
15
|
+
| **resvg-js** | MPL-2.0 | SVG → PNG without a browser | motion-kit's rasterizer |
|
|
16
|
+
|
|
17
|
+
## Related agent skills worth borrowing ideas from
|
|
18
|
+
|
|
19
|
+
- **visual-explainer** (nicobailon, MIT): fixed visual registers, hover-linking
|
|
20
|
+
between text and figure, contact-sheet self-check.
|
|
21
|
+
- **Dashmotion** (csthink, MIT): Mermaid → animated SVG with CSS/SMIL, zero
|
|
22
|
+
dependencies; a pause toggle and reduced-motion handling inside the SVG.
|
|
23
|
+
|
|
24
|
+
## Further reading
|
|
25
|
+
|
|
26
|
+
- Bret Victor, "Explorable Explanations"; Nicky Case's explorables: interaction
|
|
27
|
+
that teaches.
|
|
28
|
+
- WCAG 2.2: 2.2.2 Pause, Stop, Hide; 2.3.3 Animation from Interactions.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Interactivity and accessibility
|
|
2
|
+
|
|
3
|
+
## The player (`runtime/player.mjs`, used by `build`, the Astro adapter, Craft Pages)
|
|
4
|
+
|
|
5
|
+
- Starts on the **final frame** (also the no-JS / server-rendered fallback).
|
|
6
|
+
- Replays once when ~40 % visible, then holds.
|
|
7
|
+
- Controls: play/pause (always present, WCAG 2.2.2), one button per step (jumps,
|
|
8
|
+
no animation), optional scrubber, caption with the active step's `detail`.
|
|
9
|
+
- Keyboard on the diagram: ← / → step, Home / End, Space play/pause.
|
|
10
|
+
- `prefers-reduced-motion`: final frame, no autoplay, no play button.
|
|
11
|
+
- `prefers-color-scheme`: light/dark tokens switch live.
|
|
12
|
+
- Screen readers: `role="img"` + `<title>`/`<desc>`, a visually hidden ordered
|
|
13
|
+
list of all steps with details; the visible caption is `aria-hidden`.
|
|
14
|
+
- Capture hook: `window.__motionKit[id].seek(t)` (for Playwright/HyperFrames-
|
|
15
|
+
style renderers).
|
|
16
|
+
|
|
17
|
+
## Patterns worth adding per diagram (in the page around the player)
|
|
18
|
+
|
|
19
|
+
- **Hover/focus linking:** terms in the surrounding text highlight the matching
|
|
20
|
+
part of the diagram (and back). Wrap the term in
|
|
21
|
+
`<span data-mk-step="3">`; on hover, `controller.seekStep(3)`.
|
|
22
|
+
- **Scroll-driven steps:** for long-form explainers, map section visibility to
|
|
23
|
+
steps (IntersectionObserver per text section → `seekStep(i)`). Don't scrub
|
|
24
|
+
continuously on scroll; jump to settled steps.
|
|
25
|
+
- **Details on demand:** step buttons + caption first; tooltips only for
|
|
26
|
+
secondary facts.
|
|
27
|
+
- **Explorables:** a parameter slider can change the *spec* (e.g. number of
|
|
28
|
+
spokes, a rate), re-create the scene and seek to the same step. Keep the
|
|
29
|
+
scene pure: the parameter is input, not state.
|
|
30
|
+
|
|
31
|
+
## Rules
|
|
32
|
+
|
|
33
|
+
- Never autoplay sound. Never loop an explainer.
|
|
34
|
+
- Every interactive control is a real `<button>`/`<input>` with a visible focus
|
|
35
|
+
style and an accessible name.
|
|
36
|
+
- Don't hide information only in hover states; touch devices have no hover.
|
|
37
|
+
- Test: keyboard only, a screen reader pass (VoiceOver: the step list is read),
|
|
38
|
+
phone width, reduced motion, dark mode.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Motion vocabulary
|
|
2
|
+
|
|
3
|
+
## Easing (`runtime/motion.mjs`, exact cubic-bézier solve, no overshoot)
|
|
4
|
+
|
|
5
|
+
| Name | Curve | Use |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| `easeOut` | `cubic-bezier(0, 0, .2, 1)` | entrances, appearing |
|
|
8
|
+
| `easeStandard` | `cubic-bezier(.4, 0, .2, 1)` | movement between two visible states, fills, draw-on |
|
|
9
|
+
| `easeIn` | `cubic-bezier(.4, 0, 1, 1)` | exits (rare in explainers) |
|
|
10
|
+
| `linear` | — | only for things that should feel mechanical (progress bars) |
|
|
11
|
+
|
|
12
|
+
## Timing budget
|
|
13
|
+
|
|
14
|
+
| Event | Duration |
|
|
15
|
+
|---|---|
|
|
16
|
+
| One entrance | 300–600 ms |
|
|
17
|
+
| Sibling stagger | 80–150 ms, reading order |
|
|
18
|
+
| State fill (pending → active) | 200–300 ms |
|
|
19
|
+
| Travel between nodes | 350–500 ms |
|
|
20
|
+
| Pause between beats | ≥ 50 ms, so step frames settle |
|
|
21
|
+
| Whole explainer | ≤ ~8 s, then hold |
|
|
22
|
+
|
|
23
|
+
## Springs, without breaking random access (derived)
|
|
24
|
+
|
|
25
|
+
Frame-by-frame spring simulation depends on earlier frames. Use the closed form.
|
|
26
|
+
A **critically damped** spring never overshoots:
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
s(τ) = 1 − (1 + ωτ)·e^(−ωτ) τ > 0, else 0 (springStep)
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
ω ≈ 8–16 rad/s for UI-scale motion (settles in `9.24 / ω` s). The value snaps to
|
|
33
|
+
exactly 1 at ωτ ≥ 9.24 (error ≤ 0.1 %), so settled frames are byte-stable.
|
|
34
|
+
|
|
35
|
+
**Retargeting** (a value that changes target mid-flight) is exact superposition,
|
|
36
|
+
because the spring is linear and time-invariant:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
value(t) = from + Σ (to_i − to_{i−1}) · s(t − at_i) (springTo)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Continuous at every change, still random-access. Underdamped (bouncy) springs
|
|
43
|
+
are out of scope for explainers.
|
|
44
|
+
|
|
45
|
+
## Split edges (derived)
|
|
46
|
+
|
|
47
|
+
A moving shape's leading edge moves first and the trailing edge follows a
|
|
48
|
+
little later with the same curve: the shape stretches in flight and settles at
|
|
49
|
+
its own length. `splitEdge(t, start, dur, lag = 0.07)` → `{ lead, trail }`.
|
|
50
|
+
Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
|
|
51
|
+
|
|
52
|
+
## Container and text timing
|
|
53
|
+
|
|
54
|
+
- The container (box, card) starts moving immediately; new text appears only
|
|
55
|
+
once there is room for it; the old text is gone before the next transition.
|
|
56
|
+
- Labels never move while being read: animate the node, not its label.
|
|
57
|
+
- Cross-fade text colour (muted → ink) together with the node's fill.
|
|
58
|
+
|
|
59
|
+
## Banned in explainers
|
|
60
|
+
|
|
61
|
+
Bounce and elastic easing · parallax · looping or auto-advancing carousels ·
|
|
62
|
+
ambient motion · `transition: all` · anything whose only purpose is decoration.
|
|
63
|
+
|
|
64
|
+
## Sound (video only)
|
|
65
|
+
|
|
66
|
+
Attach visual events (a node lighting, a link completing) to beat or peak
|
|
67
|
+
times in the soundtrack: put the times in the spec and derive the timeline
|
|
68
|
+
from them. Use licensed or original audio only, and review audio like visuals.
|
|
69
|
+
motion-kit's own video path is silent. For audio-synced edits use HyperFrames
|
|
70
|
+
(see `ecosystem.md`).
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Quality control
|
|
2
|
+
|
|
3
|
+
Model screenshots are evidence, not approval. **A human signs off on the look.**
|
|
4
|
+
"Checks are green" says nothing about how it looks.
|
|
5
|
+
|
|
6
|
+
## Five stages
|
|
7
|
+
|
|
8
|
+
1. **Storyboard:** step contact sheet (`export --png --qc` → `index.html`).
|
|
9
|
+
Does the sequence tell the story without narration? Approve before polishing.
|
|
10
|
+
2. **Timing:** QC frames 0.2 s before/after each step: overlapping text, abrupt
|
|
11
|
+
jumps, elements vanishing, half-drawn lines, stray dots. Regular sampling
|
|
12
|
+
misses broken transitions; look *around* the transitions.
|
|
13
|
+
3. **Phone size:** the 360 px row in the sheet; the `tall`/`9:16` layout; no
|
|
14
|
+
text under 14 px at 1×.
|
|
15
|
+
4. **Brand and facts:** tokens only, approved style, approved copy, no invented
|
|
16
|
+
numbers or superlatives, every locale checked.
|
|
17
|
+
5. **Final file:**
|
|
18
|
+
- Live: real-time playback at desktop and phone width; reduced motion
|
|
19
|
+
(`--force-prefers-reduced-motion`); dark mode; keyboard; screen reader
|
|
20
|
+
reads the step list.
|
|
21
|
+
- Video: `video --sheet` contact sheet; duration, aspect and size via the
|
|
22
|
+
printed probe; watch it once at full size.
|
|
23
|
+
|
|
24
|
+
**Don't trust virtual time.** Headless `--virtual-time-budget` doesn't advance
|
|
25
|
+
the player's animation clock faithfully. Use `--timeout=<ms>` (real time) or a
|
|
26
|
+
DevTools/Playwright session, or force reduced motion to check the final frame.
|
|
27
|
+
|
|
28
|
+
## Review report (paste into the PR / task)
|
|
29
|
+
|
|
30
|
+
```markdown
|
|
31
|
+
### Diagram review: <scene id> (<formats>, <locales>, <style>)
|
|
32
|
+
- Gate: `motion-kit check` ✓ (n formats × m locales)
|
|
33
|
+
- Timestamps inspected: steps 1–N; before/after each transition; phone row
|
|
34
|
+
- Issues found:
|
|
35
|
+
- …
|
|
36
|
+
- Fixes applied:
|
|
37
|
+
- …
|
|
38
|
+
- Remaining concerns:
|
|
39
|
+
- …
|
|
40
|
+
- Human approval: ☐ <name>, <date>
|
|
41
|
+
```
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Scene types
|
|
2
|
+
|
|
3
|
+
Prefer a spec-driven type; a new diagram is then data, not code. Strings can be
|
|
4
|
+
plain or localized (`{ "en": "...", "nl": "..." }`). Every node may have a
|
|
5
|
+
`detail` sentence (player caption + screen-reader text).
|
|
6
|
+
|
|
7
|
+
## Built
|
|
8
|
+
|
|
9
|
+
### `sequence`: one thing through ordered stages
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{ "type": "sequence", "id": "order-flow",
|
|
13
|
+
"title": "How an order reaches the customer",
|
|
14
|
+
"description": "Six stages in order: …",
|
|
15
|
+
"nodes": [ { "label": "Order", "detail": "The customer places an order." }, … ],
|
|
16
|
+
"glyphs": "numbers", // or "none"; per node: "glyph": "A" or "icon": "<path d>"
|
|
17
|
+
"fontSize": 18 } // optional max; auto-fit otherwise
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
2–12 nodes. Storyboard: nodes appear in reading order → an emphasis ring lands
|
|
21
|
+
on node 1 → it travels node to node; each reached node fills accent and the
|
|
22
|
+
path behind turns accent. Steps = one per node.
|
|
23
|
+
Layouts: row (wide aspects), snake grid with outside elbows (1:1, 4:3, crowded
|
|
24
|
+
16:9), column with labels on the right (9:16, tall).
|
|
25
|
+
|
|
26
|
+
### `hub-spoke`: one centre connected to many
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{ "type": "hub-spoke", "id": "integrations",
|
|
30
|
+
"title": "…", "description": "…",
|
|
31
|
+
"hub": { "label": "Platform", "detail": "…" },
|
|
32
|
+
"spokes": [ { "label": "E-mail", "detail": "…" }, … ],
|
|
33
|
+
"direction": "out" } // "in" = spokes feed the hub
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
2–10 spokes. Storyboard: hub + spokes appear → the hub activates → one link at a
|
|
37
|
+
time draws (carrying an emphasis dot) and the spoke fills. Steps = hub, then
|
|
38
|
+
each spoke. Layouts: radial ellipse (wide/square), tree with an outside trunk
|
|
39
|
+
(9:16, tall). Throws when boxes would overlap: fewer spokes or a larger format.
|
|
40
|
+
|
|
41
|
+
## Storyboards for types not built yet
|
|
42
|
+
|
|
43
|
+
Build these as custom scenes (`custom-scenes.md`) first. Promote one to a type
|
|
44
|
+
once it has been used twice.
|
|
45
|
+
|
|
46
|
+
| Type | Helps the viewer understand | Storyboard |
|
|
47
|
+
|---|---|---|
|
|
48
|
+
| `stack` | layers build on each other (architecture, security layers) | layers rise bottom-up; then a request/data packet travels down/up, each layer lighting as it passes |
|
|
49
|
+
| `before-after` | what changes | left state fully shown → a divider sweeps → right state builds; differences highlighted with the emphasis colour |
|
|
50
|
+
| `timeline` | events in time | axis draws on → milestones drop in order → "now" marker settles |
|
|
51
|
+
| `comparison` | option A vs B on criteria | two columns appear → criteria rows fill one at a time → the deciding row emphasised |
|
|
52
|
+
| `state-machine` | states and transitions | all states (pending) → a token walks a path of transitions, the current state accent |
|
|
53
|
+
| `request-journey` | a request crossing system components | components in regions/boundaries → a dot travels the path, each hop lights, async edges dashed |
|
|
54
|
+
| `funnel` / `data-flow` | volume or data narrowing/merging | sources appear → streams draw on and merge → result fills |
|
|
55
|
+
|
|
56
|
+
Auto-layout for larger graphs: lay out with ELK.js or dagre once (Node, at
|
|
57
|
+
build time), store coordinates in the spec, then animate. Mermaid flowchart or
|
|
58
|
+
state syntax can serve as input notation (parse nodes/edges, recompute layout).
|
|
59
|
+
Don't convert sequence or ER diagrams lossily.
|