@liqweed/motion-kit 0.7.0 → 0.8.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/docs/spec/technique.md +2 -1
- package/package.json +3 -2
- package/runtime/kit.mjs +2 -2
- package/runtime/motion.mjs +61 -0
- package/runtime/style.mjs +35 -3
- 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 +1 -1
- package/skills/animated-diagram/references/custom-scenes.md +4 -1
- package/skills/animated-diagram/references/ecosystem.md +1 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +29 -0
- package/skills/animated-diagram/references/styles.md +19 -0
- package/styles/neutral.json +4 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "motion-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "Deterministic animated diagrams: scenes as pure functions of time for live pages, Slidev, slide frames, baked SVG and video; plus project logos/icons.",
|
|
5
5
|
"author": { "name": "Ophir Radnitz" },
|
|
6
6
|
"repository": "https://github.com/liqweed/motion-kit",
|
package/docs/spec/technique.md
CHANGED
|
@@ -235,7 +235,7 @@ move ends at `start + lag + duration`, which is what step timing MUST budget.
|
|
|
235
235
|
`accent`, `onAccent`, `emphasis`. Roles: see
|
|
236
236
|
[`styles.md`](../../skills/animated-diagram/references/styles.md). Exactly one
|
|
237
237
|
element at a time SHOULD carry `emphasis`.
|
|
238
|
-
- A style is data: `{name, font, radius, stroke, light: {token: #rrggbb}, dark: {…}}`.
|
|
238
|
+
- A style is data: `{name, font, radius, stroke, motion, light: {token: #rrggbb}, dark: {…}}`.
|
|
239
239
|
`normalizeStyle` fills missing fields from `NEUTRAL`
|
|
240
240
|
(`runtime/style.mjs:25-50,58-77`) and MUST throw on an unknown token or a
|
|
241
241
|
non-`#rrggbb` value (`runtime/style.mjs:70-73`). If `dark` is absent, dark
|
|
@@ -560,6 +560,7 @@ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
|
|
|
560
560
|
| Module locales | Modules MAY export `locales`; all declared locales MUST be checked by default. Undeclared modules retain `en` for compatibility. Explicit `--locale` overrides. |
|
|
561
561
|
| Translations | A localized object MUST supply the exact requested locale. Plain strings are shared. Silent cross-language fallback is forbidden. |
|
|
562
562
|
| Shape styles | Built-in scenes MUST use radius 0–24 (default 10) for rectangular node corners and stroke 1–4 (default 2) as their base width. Accent lines are 1.5×; timeline stems 0.75×. Circles, region borders and pills retain their shapes. Custom scenes MAY read normalized `style` from the frame context. |
|
|
563
|
+
| Motion tokens | A style MAY set `motion.enter` (entrances) and `motion.move` (movement between visible states) as four numbers, a CSS `cubic-bezier(x1, y1, x2, y2)`, each from 0 to 1: no curve overshoots. Defaults: `(0, 0, .2, 1)` and `(.4, 0, .2, 1)`. Built-in scene types read them through `easings(style.motion)`; durations, delays and step times stay fixed, so a curve changes how a move travels and never when a step settles. A curve that is still moving near its end (a linear one) would leave a step frame unsettled, so `easings` finishes it in the first 95 % of each move and holds it at 1 for the last 5 %; a curve that ends flat (both defaults) is the exact CSS curve. Custom scenes MAY do the same. |
|
|
563
564
|
| Vendored parity | CLI and vendored checks MUST call the same `lib/gate.mjs` and `lib/check.mjs`, including contrast, locales and caller options. |
|
|
564
565
|
| Neutral contrast | Keep emphasis-on-accent at 3:1, the darker light accent and lighter dark emphasis. The site chrome follows the corresponding neutral tokens. |
|
|
565
566
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@liqweed/motion-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "Deterministic animated diagrams: scenes as pure functions of time, for live pages, slides, baked SVG and video.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"animation",
|
|
@@ -57,7 +57,8 @@
|
|
|
57
57
|
"bench:player": "node scripts/bench-player.mjs",
|
|
58
58
|
"snapshots:update": "node scripts/update-snapshots.mjs",
|
|
59
59
|
"gate:core": "npm run -s typecheck && npm run -s versions && npm test && npm run -s check && npm run -s media:check",
|
|
60
|
-
"gate": "npm run -s gate:core && npm run -s site"
|
|
60
|
+
"gate": "npm run -s gate:core && npm run -s site",
|
|
61
|
+
"skills:design": "DISABLE_TELEMETRY=1 npx -y skills@1.9.0 experimental_install --frozen-lockfile -a claude-code -a codex"
|
|
61
62
|
},
|
|
62
63
|
"optionalDependencies": {
|
|
63
64
|
"@resvg/resvg-js": "^2.6.2"
|
package/runtime/kit.mjs
CHANGED
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
* from `motion-kit build` calls the factory the same way, with the bundled
|
|
22
22
|
* runtime as `kit`, after the CLI built it here once.
|
|
23
23
|
*/
|
|
24
|
-
import { ENTRANCE_MAX, SPRING_SETTLE_X, clamp01, cubicBezier, easeIn, easeOut, easeStandard, lerp, linear, progress, splitEdge, springSettleTime, springStep, springTo, stagger, window01 } from "./motion.mjs";
|
|
24
|
+
import { DEFAULT_MOTION, ENTRANCE_MAX, SPRING_SETTLE_X, clamp01, cubicBezier, easeIn, easeOut, easeStandard, easings, lerp, linear, progress, splitEdge, springSettleTime, springStep, springTo, stagger, window01 } from "./motion.mjs";
|
|
25
25
|
import { FORMATS, localize, renderSvg, safeId, stepIndex, stepIndexAt, stepTimes, validateScene, withId } from "./scene.mjs";
|
|
26
26
|
import { CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, cssVars, normalizeStyle, resolveTokens, tok } from "./style.mjs";
|
|
27
27
|
import { attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, translate, trimSegment } from "./svg.mjs";
|
|
@@ -34,7 +34,7 @@ import { estimateWidth, wrapLabel } from "./wrap.mjs";
|
|
|
34
34
|
* in one of those modules is added here (test/runtime.test.mjs checks).
|
|
35
35
|
*/
|
|
36
36
|
export const KIT = Object.freeze({
|
|
37
|
-
...{ ENTRANCE_MAX, SPRING_SETTLE_X, clamp01, cubicBezier, easeIn, easeOut, easeStandard, lerp, linear, progress, splitEdge, springSettleTime, springStep, springTo, stagger, window01 },
|
|
37
|
+
...{ DEFAULT_MOTION, ENTRANCE_MAX, SPRING_SETTLE_X, clamp01, cubicBezier, easeIn, easeOut, easeStandard, easings, lerp, linear, progress, splitEdge, springSettleTime, springStep, springTo, stagger, window01 },
|
|
38
38
|
...{ FORMATS, localize, renderSvg, safeId, stepIndex, stepIndexAt, stepTimes, validateScene, withId },
|
|
39
39
|
...{ CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, cssVars, normalizeStyle, resolveTokens, tok },
|
|
40
40
|
...{ attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, translate, trimSegment },
|
package/runtime/motion.mjs
CHANGED
|
@@ -152,3 +152,64 @@ export function splitEdge(t, start, duration, lag = 0.07, ease = easeStandard) {
|
|
|
152
152
|
export function stagger(count, start, gap) {
|
|
153
153
|
return Array.from({ length: count }, (_, i) => start + i * gap);
|
|
154
154
|
}
|
|
155
|
+
|
|
156
|
+
/* ----------------------------------------------------- style curves */
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* The two curves a style may name: `enter` for entrances, `move` for movement
|
|
160
|
+
* between two visible states, each as the four numbers of a CSS
|
|
161
|
+
* `cubic-bezier(x1, y1, x2, y2)`. The defaults are `easeOut` and `easeStandard`.
|
|
162
|
+
* @typedef {{ enter: readonly [number, number, number, number], move: readonly [number, number, number, number] }} Motion
|
|
163
|
+
*/
|
|
164
|
+
/** @type {Readonly<Motion>} */
|
|
165
|
+
export const DEFAULT_MOTION = Object.freeze({
|
|
166
|
+
enter: Object.freeze(/** @type {[number, number, number, number]} */ ([0, 0, 0.2, 1])),
|
|
167
|
+
move: Object.freeze(/** @type {[number, number, number, number]} */ ([0.4, 0, 0.2, 1])),
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
/**
|
|
171
|
+
* A step frame must equal the frame 1 ms before it (the gate's settled-frame
|
|
172
|
+
* rule), and the shortest built-in move lasts about 0.2 s, so a curve has to be
|
|
173
|
+
* within rounding of 1 at 0.5 % of its duration before the end. The defaults are
|
|
174
|
+
* (about 1e-5 short of 1 there); a linear curve is 5e-3 short.
|
|
175
|
+
*/
|
|
176
|
+
const SETTLE_PROBE = 0.005;
|
|
177
|
+
const SETTLE_TOLERANCE = 2e-5;
|
|
178
|
+
/** Share of a curve's duration held at 1 when the curve does not settle by itself. */
|
|
179
|
+
const SETTLE_WINDOW = 0.05;
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* `curve` as it is, when it ends flat enough to settle on its own; otherwise
|
|
183
|
+
* the same curve finished in the first 95 % of its duration, so the last 5 % is
|
|
184
|
+
* held at exactly 1 and every step frame is settled whatever the curve.
|
|
185
|
+
* @param {(p: number) => number} curve
|
|
186
|
+
* @returns {(p: number) => number}
|
|
187
|
+
*/
|
|
188
|
+
function settled(curve) {
|
|
189
|
+
if (1 - curve(1 - SETTLE_PROBE) <= SETTLE_TOLERANCE) return curve;
|
|
190
|
+
return (p) => curve(Math.min(1, p / (1 - SETTLE_WINDOW)));
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/** @type {Map<string, { easeOut: (p: number) => number, easeStandard: (p: number) => number }>} */
|
|
194
|
+
const easingCache = new Map();
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* The entrance and movement curves of a style's `motion` (or the defaults).
|
|
198
|
+
* Scene types call this with `style.motion` once per frame, so a diagram moves
|
|
199
|
+
* on the page's own curve. The result is cached by curve. The endpoints stay
|
|
200
|
+
* fixed, and a curve that does not end flat (a linear one) finishes in the first
|
|
201
|
+
* 95 % of each move, so step frames are settled for every permitted curve.
|
|
202
|
+
* @param {Motion} [motion]
|
|
203
|
+
* @returns {{ easeOut: (p: number) => number, easeStandard: (p: number) => number }}
|
|
204
|
+
*/
|
|
205
|
+
export function easings(motion = DEFAULT_MOTION) {
|
|
206
|
+
if (motion === DEFAULT_MOTION) return { easeOut, easeStandard };
|
|
207
|
+
const key = `${motion.enter.join()}|${motion.move.join()}`;
|
|
208
|
+
let found = easingCache.get(key);
|
|
209
|
+
if (!found) {
|
|
210
|
+
if (easingCache.size >= 32) easingCache.clear();
|
|
211
|
+
found = { easeOut: settled(cubicBezier(...motion.enter)), easeStandard: settled(cubicBezier(...motion.move)) };
|
|
212
|
+
easingCache.set(key, found);
|
|
213
|
+
}
|
|
214
|
+
return found;
|
|
215
|
+
}
|
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
|
};
|
|
@@ -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)
|
|
@@ -122,4 +122,7 @@ A scene whose step labels narrate actions rather than name visible objects
|
|
|
122
122
|
sets `stepLabelsInFrame: false`. Those labels still belong in the player's
|
|
123
123
|
controls and accessible transcript; G10 otherwise requires each label in the
|
|
124
124
|
final frame. `frame(t, { idPrefix, style })` also receives the normalized style
|
|
125
|
-
when called through `renderSvg`; custom shape styling is opt-in.
|
|
125
|
+
when called through `renderSvg`; custom shape styling is opt-in. So is the
|
|
126
|
+
style's motion: `const { easeOut, easeStandard } = kit.easings(style.motion)` (or
|
|
127
|
+
`easings` from `runtime/motion.mjs`) gives the curves its `motion` names, the
|
|
128
|
+
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 |
|
|
@@ -56,6 +61,30 @@ Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
|
|
|
56
61
|
- Labels never move while being read: animate the node, not its label.
|
|
57
62
|
- Cross-fade text colour (muted → ink) together with the node's fill.
|
|
58
63
|
|
|
64
|
+
## Where this departs from interface-motion standards
|
|
65
|
+
|
|
66
|
+
Other design skills (Emil Kowalski's `choreograph`, `review-animations`,
|
|
67
|
+
`animate`; Impeccable's `animate`) set rules for interface feedback: a hover, a
|
|
68
|
+
menu, a toast. A diagram that explains is not that, and an agent that has those
|
|
69
|
+
skills installed will "fix" what follows unless it knows these are decided. The
|
|
70
|
+
rule is: **this file decides how a scene moves; those skills decide how the page
|
|
71
|
+
around it moves.** A finding from them against a scene type is an issue, not an
|
|
72
|
+
edit.
|
|
73
|
+
|
|
74
|
+
| Their rule | What a scene does | Why |
|
|
75
|
+
|---|---|---|
|
|
76
|
+
| 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 |
|
|
77
|
+
| 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 |
|
|
78
|
+
| 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 |
|
|
79
|
+
| 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 |
|
|
80
|
+
| 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 |
|
|
81
|
+
| 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 |
|
|
82
|
+
|
|
83
|
+
What does carry over: no `transition: all`, animate `transform` and `opacity`
|
|
84
|
+
in the page around a diagram, honour reduced motion, and never overshoot. A
|
|
85
|
+
style's `motion` curves (`styles.md`) are how a diagram takes on the page's own
|
|
86
|
+
curve without changing any of the above.
|
|
87
|
+
|
|
59
88
|
## Banned in explainers
|
|
60
89
|
|
|
61
90
|
Bounce and elastic easing · parallax · looping or auto-advancing carousels ·
|
|
@@ -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",
|