@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.
@@ -7,7 +7,7 @@
7
7
  "name": "motion-kit",
8
8
  "source": "./",
9
9
  "description": "animated-diagram, motion-render and project-logo skills and the motion-kit runtime/CLI",
10
- "version": "0.7.0"
10
+ "version": "0.8.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.7.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",
@@ -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.7.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 },
@@ -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 and one colour per token, per theme.
18
- * @typedef {{ name?: string, font: string, radius: number, stroke: number, light: Record<string, string>, dark: Record<string, string> }} Style
19
+ * A visual style: font, shape constants, the entrance and movement curves and
20
+ * one colour per token, per theme.
21
+ * @typedef {{ name?: string, font: string, radius: number, stroke: number, motion: Motion, light: Record<string, string>, dark: Record<string, string> }} Style
19
22
  */
20
23
 
21
24
  export const TOKENS = [
@@ -34,6 +37,7 @@ export const NEUTRAL = Object.freeze({
34
37
  font: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif',
35
38
  radius: 10,
36
39
  stroke: 2,
40
+ motion: DEFAULT_MOTION,
37
41
  light: Object.freeze({
38
42
  bg: "#ffffff",
39
43
  surface: "#f3f4f6",
@@ -61,6 +65,33 @@ export function tok(name) {
61
65
  return `var(--mk-${name})`;
62
66
  }
63
67
 
68
+ /**
69
+ * A style's `motion` with any missing curve taken from the defaults. A curve
70
+ * is four numbers, as in CSS `cubic-bezier(x1, y1, x2, y2)`: x between 0 and 1
71
+ * (CSS's own rule) and y between 0 and 1 too, because no motion-kit curve
72
+ * overshoots.
73
+ * @param {any} motion
74
+ * @param {string} name the style's name, for the error
75
+ * @returns {Motion}
76
+ */
77
+ function normalizeMotion(motion, name) {
78
+ if (motion === undefined) return DEFAULT_MOTION;
79
+ if (!motion || typeof motion !== "object" || Array.isArray(motion)) throw new Error(`style "${name}": motion must be an object with enter and move curves`);
80
+ for (const key of Object.keys(motion)) {
81
+ if (key !== "enter" && key !== "move") throw new Error(`style "${name}": unknown motion curve "${key}" (known: enter, move)`);
82
+ }
83
+ const out = { enter: DEFAULT_MOTION.enter, move: DEFAULT_MOTION.move };
84
+ for (const key of /** @type {const} */ (["enter", "move"])) {
85
+ const c = motion[key];
86
+ if (c === undefined) continue;
87
+ if (!Array.isArray(c) || c.length !== 4 || !c.every((n) => Number.isFinite(n) && n >= 0 && n <= 1)) {
88
+ throw new Error(`style "${name}": motion.${key} must be four numbers from 0 to 1 (a cubic-bezier that does not overshoot), got ${JSON.stringify(c)}`);
89
+ }
90
+ out[key] = Object.freeze(/** @type {[number, number, number, number]} */ ([...c]));
91
+ }
92
+ return Object.freeze(out);
93
+ }
94
+
64
95
  /** Fill in any missing fields from NEUTRAL and validate token names. */
65
96
  export function normalizeStyle(style) {
66
97
  if (!style || style === "neutral") return NEUTRAL;
@@ -69,6 +100,7 @@ export function normalizeStyle(style) {
69
100
  font: style.font ?? NEUTRAL.font,
70
101
  radius: style.radius ?? NEUTRAL.radius,
71
102
  stroke: style.stroke ?? NEUTRAL.stroke,
103
+ motion: normalizeMotion(style.motion, style.name ?? "custom"),
72
104
  light: { ...NEUTRAL.light, ...(style.light ?? {}) },
73
105
  dark: { ...NEUTRAL.dark, ...(style.dark ?? style.light ?? {}) },
74
106
  };
@@ -26,7 +26,7 @@
26
26
  * shape: "box" (default) | "round" | "pill" | "decision".
27
27
  * Strings may be localized objects: { en: "...", nl: "..." }.
28
28
  */
29
- import { easeOut, easeStandard, progress } from "../motion.mjs";
29
+ import { progress, easings } from "../motion.mjs";
30
30
  import { FONT_MIN, maxFontSize, rectEdge } from "../parts.mjs";
31
31
  import { FORMATS, localize, withId } from "../scene.mjs";
32
32
  import { NEUTRAL, tok } from "../style.mjs";
@@ -333,6 +333,7 @@ export function flowchart(spec, { format = "16:9", locale = "en" } = {}) {
333
333
 
334
334
  /** @param {number} t @param {{ style?: Style }} [ctx] */
335
335
  function frame(t, { style = NEUTRAL } = {}) {
336
+ const { easeOut, easeStandard } = easings(style.motion);
336
337
  const enter = (/** @type {number} */ r) => progress(t, rankIndex(r) * ENTER_GAP, ENTER, easeOut);
337
338
  const out = [];
338
339
  const drawn = edges.map((_, i) => progress(t, backward[i] ? fillStart(edgeStep[i]) - 0.1 : drawStart(edgeStep[i]), backward[i] ? DRAW - 0.05 : DRAW, easeStandard));
@@ -17,7 +17,7 @@
17
17
  * direction?: "out" | "in", // default "out"
18
18
  * fontSize?: number }
19
19
  */
20
- import { easeOut, easeStandard, progress, window01 } from "../motion.mjs";
20
+ import { progress, window01, easings } from "../motion.mjs";
21
21
  import { boxNode, FONT_MIN, maxFontSize, rectEdge } from "../parts.mjs";
22
22
  import { FORMATS, localize, withId } from "../scene.mjs";
23
23
  import { NEUTRAL, tok } from "../style.mjs";
@@ -166,6 +166,7 @@ export function hubSpoke(spec, { format = "16:9", locale = "en" } = {}) {
166
166
 
167
167
  /** @param {number} t @param {{style?: Style}} [ctx] */
168
168
  function frame(t, { style = NEUTRAL } = {}) {
169
+ const { easeOut, easeStandard } = easings(style.motion);
169
170
  const out = [];
170
171
  const sEnter = (i) => progress(t, spokeEnter(i), ENTER, easeOut);
171
172
  links.forEach((link, i) => {
@@ -17,7 +17,7 @@
17
17
  * fontSize?: number }
18
18
  * Strings may be localized objects: { en: "...", nl: "..." }.
19
19
  */
20
- import { easeOut, easeStandard, progress } from "../motion.mjs";
20
+ import { progress, easings } from "../motion.mjs";
21
21
  import { circleNode, FONT_MIN, maxFontSize, stateLabel } from "../parts.mjs";
22
22
  import { FORMATS, localize, withId } from "../scene.mjs";
23
23
  import { NEUTRAL, tok } from "../style.mjs";
@@ -157,6 +157,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
157
157
 
158
158
  /** @param {number} t @param {{style?: Style}} [ctx] */
159
159
  function frame(t, { style = NEUTRAL } = {}) {
160
+ const { easeOut, easeStandard } = easings(style.motion);
160
161
  const enter = (k) => progress(t, k * ENTER_GAP, ENTER, easeOut);
161
162
  const active = (k) => progress(t, fillStart(k), FILL, easeStandard);
162
163
  const out = [];
@@ -21,7 +21,7 @@
21
21
  * Layout: one column of full-width layers with the rail on their right, in
22
22
  * every format; layers get taller (up to a limit) where the format has room.
23
23
  */
24
- import { easeOut, easeStandard, lerp, progress } from "../motion.mjs";
24
+ import { lerp, progress, easings } from "../motion.mjs";
25
25
  import { FONT_MIN, maxFontSize } from "../parts.mjs";
26
26
  import { FORMATS, localize, withId } from "../scene.mjs";
27
27
  import { NEUTRAL, tok } from "../style.mjs";
@@ -169,7 +169,7 @@ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
169
169
  const stepAt = (k) => fillStart(k) + FILL;
170
170
  const duration = stepAt(n - 1) + TAIL;
171
171
 
172
- function packetY(t) {
172
+ function packetY(t, easeStandard) {
173
173
  let y = stops[0];
174
174
  for (let k = 0; k < n; k++) {
175
175
  const p = progress(t, hopStart(k), HOP, easeStandard);
@@ -183,6 +183,7 @@ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
183
183
 
184
184
  /** @param {number} t @param {{style?: Style}} [ctx] */
185
185
  function frame(t, { style = NEUTRAL } = {}) {
186
+ const { easeOut, easeStandard } = easings(style.motion);
186
187
  const out = [];
187
188
  const { railX } = fitted;
188
189
  // Rail: draws on from the entry end while the layers rise; an arrowhead marks the exit.
@@ -194,7 +195,7 @@ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
194
195
  const s = direction === "down" ? -1 : 1;
195
196
  out.push(el("path", { d: `M${num(railX - 6)} ${num(exitY + s * 9)} L${num(railX)} ${num(exitY)} L${num(railX + 6)} ${num(exitY + s * 9)}`, fill: "none", stroke: tok("line"), "stroke-width": style.stroke, "stroke-linecap": "round", "stroke-linejoin": "round", opacity: head }));
196
197
  }
197
- const y = packetY(t);
198
+ const y = packetY(t, easeStandard);
198
199
  if (Math.abs(y - entryY) > 0.5) out.push(vline(railX, entryY, y, { stroke: tok("accent"), "stroke-width": style.stroke * 1.5 }));
199
200
  fitted.boxes.forEach((b, li) => {
200
201
  const enter = progress(t, riseAt(li), RISE, easeOut);
@@ -23,7 +23,7 @@
23
23
  * below when they need the width (wide aspects and square); a vertical axis
24
24
  * with labels on the right (9:16, tall).
25
25
  */
26
- import { easeOut, easeStandard, lerp, progress, springSettleTime, springStep } from "../motion.mjs";
26
+ import { lerp, progress, springSettleTime, springStep, easings } from "../motion.mjs";
27
27
  import { FONT_MIN, maxFontSize, stateLabel } from "../parts.mjs";
28
28
  import { FORMATS, localize, withId } from "../scene.mjs";
29
29
  import { NEUTRAL, tok } from "../style.mjs";
@@ -296,7 +296,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
296
296
  if (now && L.nowAt) stops.push({ to: along(L.nowAt), at: nowStart });
297
297
  const axisLen = L.dir === "h" ? ax.x1 - ax.x0 : ax.y1 - ax.y0;
298
298
 
299
- function accentEnd(t) {
299
+ function accentEnd(t, easeStandard) {
300
300
  let end = start;
301
301
  let from = start;
302
302
  for (const s of stops) {
@@ -312,6 +312,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
312
312
  el("path", { d: L.dir === "h" ? `M${num(a)} ${num(ax.y0)} H${num(b)}` : `M${num(ax.x0)} ${num(a)} V${num(b)}`, fill: "none", "stroke-linecap": "round", ...attrs });
313
313
 
314
314
  function milestone(t, it, k, style) {
315
+ const { easeOut, easeStandard } = easings(style.motion);
315
316
  const p = L.at(k);
316
317
  const b = beat(k);
317
318
  const drop = progress(t, b + 0.05, DROP, easeOut);
@@ -355,6 +356,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
355
356
  }
356
357
 
357
358
  function nowMarker(t, style) {
359
+ const { easeOut } = easings(style.motion);
358
360
  if (!now || !L.nowAt || !L.nowPill) return "";
359
361
  const shown = progress(t, nowStart, NOW_FADE, easeOut);
360
362
  if (shown <= 0) return "";
@@ -372,6 +374,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
372
374
 
373
375
  /** @param {number} t @param {{style?: Style}} [ctx] */
374
376
  function frame(t, { style = NEUTRAL } = {}) {
377
+ const { easeOut, easeStandard } = easings(style.motion);
375
378
  const out = [];
376
379
  // Axis: pending line draws on; an arrowhead at its end shows the direction of time.
377
380
  const axisDash = drawOn(axisLen, progress(t, 0, AXIS, easeStandard));
@@ -381,7 +384,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
381
384
  const d = L.dir === "h" ? `M${num(ax.x1 - 9)} ${num(ax.y1 - 6)} L${num(ax.x1)} ${num(ax.y1)} L${num(ax.x1 - 9)} ${num(ax.y1 + 6)}` : `M${num(ax.x1 - 6)} ${num(ax.y1 - 9)} L${num(ax.x1)} ${num(ax.y1)} L${num(ax.x1 + 6)} ${num(ax.y1 - 9)}`;
382
385
  out.push(el("path", { d, fill: "none", stroke: tok("line"), "stroke-width": style.stroke, "stroke-linecap": "round", "stroke-linejoin": "round", opacity: head }));
383
386
  }
384
- const end = accentEnd(t);
387
+ const end = accentEnd(t, easeStandard);
385
388
  if (end - start > 0.5) out.push(line(start, end, { stroke: tok("accent"), "stroke-width": style.stroke * 1.5 }));
386
389
  items.forEach((it, k) => out.push(milestone(t, it, k, style)));
387
390
  out.push(nowMarker(t, style));
@@ -3,7 +3,7 @@
3
3
  // SPDX-License-Identifier: MIT
4
4
  // Copyright (c) 2026 Ophir Radnitz
5
5
  /** Small, explicitly narrated graphs. Layout is computed once, never in frame(). */
6
- import { easeOut, easeStandard, progress, lerp } from "../motion.mjs";
6
+ import { progress, lerp, easings } from "../motion.mjs";
7
7
  import { FONT_MIN, maxFontSize } from "../parts.mjs";
8
8
  import { FORMATS, localize } from "../scene.mjs";
9
9
  import { NEUTRAL, tok } from "../style.mjs";
@@ -117,6 +117,7 @@ export function walk(spec, { format = "16:9", locale = "en" } = {}) {
117
117
  const duration = stepAt(route.length - 1) + 0.3;
118
118
  /** @param {number} t @param {{style?: Style}} [ctx] */
119
119
  function frame(t, { style = NEUTRAL } = {}) {
120
+ const { easeOut, easeStandard } = easings(style.motion);
120
121
  const entrance = progress(t, 0, 0.5, easeOut);
121
122
  const active = nodes.map(() => 0);
122
123
  active[visits[0]] = progress(t, 0.5, 0.2, easeStandard);
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: animated-diagram
3
- description: "Build animated, interactive explanatory diagrams (process flows, hub-and-spoke integrations, build-up sequences) as deterministic scenes — pure functions of time — with motion-kit. One scene serves a live web page or Craft Page, Slidev slides (one build step per click), standalone SVG/PNG slide frames, a zero-JS baked SVG, and MP4/GIF video. Use when asked to 'animate a diagram', 'make an animated/interactive diagram or explainer', 'build-up slide', 'diagram that plays step by step', or to turn a process/architecture description into motion. For exporting/rendering an existing scene (PNG, video, social formats) use motion-render."
3
+ description: "Build animated, interactive explanatory diagrams (process flows, hub-and-spoke integrations, build-up sequences) as deterministic scenes — pure functions of time — with motion-kit. One scene serves a live web page or Craft Page, Slidev slides (one build step per click), standalone SVG/PNG slide frames, a zero-JS baked SVG, and MP4/GIF video. Use when asked to 'animate a diagram', 'make an animated/interactive diagram or explainer', 'build-up slide', 'diagram that plays step by step', or to turn a process/architecture description into motion. For exporting/rendering an existing scene (PNG, video, social formats) use motion-render. Not for page or component micro-interactions (hover, press, toast, menu), faux product-UI demos or walkthroughs of an app screen, hero or feature-card illustrations, or decorative and looping effects: those belong to a UI animation or design skill."
4
4
  ---
5
5
 
6
6
  # Animated diagram (motion-kit)
@@ -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
@@ -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",