@liqweed/motion-kit 0.9.1 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +3 -1
- package/cli/motion-kit.mjs +15 -1
- package/docs/spec/technique.md +76 -20
- package/examples/connectors.scene.mjs +199 -0
- package/examples/custom-pulse.scene.mjs +9 -4
- package/lib/check.mjs +14 -14
- package/lib/gate.mjs +27 -12
- package/package.json +2 -2
- package/runtime/connectors.mjs +243 -0
- package/runtime/kit.mjs +5 -3
- package/runtime/scene.mjs +5 -3
- package/runtime/style.mjs +86 -21
- package/runtime/types/flowchart.mjs +9 -1
- package/runtime/types/hub-spoke.mjs +9 -1
- package/runtime/types/index.mjs +24 -6
- package/runtime/types/sequence.mjs +9 -1
- package/runtime/types/stack.mjs +9 -1
- package/runtime/types/timeline.mjs +9 -1
- package/runtime/types/walk.mjs +9 -1
- package/skills/animated-diagram/SKILL.md +3 -2
- package/skills/animated-diagram/references/custom-scenes.md +34 -4
- package/skills/animated-diagram/references/motion-vocabulary.md +19 -0
- package/skills/animated-diagram/references/styles.md +26 -7
- package/skills/motion-render/SKILL.md +1 -1
package/runtime/types/walk.mjs
CHANGED
|
@@ -6,10 +6,17 @@
|
|
|
6
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
|
-
import { NEUTRAL, tok } from "../style.mjs";
|
|
9
|
+
import { NEUTRAL, sharedPairs, tok } from "../style.mjs";
|
|
10
10
|
import { el, fade, num, text } from "../svg.mjs";
|
|
11
11
|
import { wrapLabel } from "../wrap.mjs";
|
|
12
12
|
|
|
13
|
+
/**
|
|
14
|
+
* The shared contrast pairs this type draws: node labels, region labels on the canvas, edges, the dot over them; no ink on the canvas.
|
|
15
|
+
* The gate holds its scenes to these and reports the other shared pairs as
|
|
16
|
+
* warnings (`contrastReport`, runtime/style.mjs).
|
|
17
|
+
*/
|
|
18
|
+
export const contrastPairs = sharedPairs("muted/bg", "ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent");
|
|
19
|
+
|
|
13
20
|
/**
|
|
14
21
|
* Build the common graph walk used by state-machine and request-journey.
|
|
15
22
|
* Nodes are in reading order; connectors use separate outside lanes. The
|
|
@@ -156,6 +163,7 @@ export function walk(spec, { format = "16:9", locale = "en" } = {}) {
|
|
|
156
163
|
id: `${spec.id}-${format.replace(":", "x")}`, type: spec.type, format, locale,
|
|
157
164
|
width: W, height: L.H, duration, title: localize(spec.title, locale), description: localize(spec.description, locale),
|
|
158
165
|
stepLabelsInFrame: false,
|
|
166
|
+
contrastPairs,
|
|
159
167
|
steps: [{ id: "initial", at: firstAt, label: labels[visits[0]], detail: localize(nodes[visits[0]].detail, locale) },
|
|
160
168
|
...route.map((e, k) => ({ id: `visit-${k + 1}`, at: stepAt(k), label: localize(edges[e].label, locale), detail: localize(edges[e].detail, locale) || `${labels[visits[k]]} → ${labels[visits[k + 1]]}` }))],
|
|
161
169
|
frame,
|
|
@@ -58,7 +58,8 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
|
|
|
58
58
|
flowchart? `motion-kit import flow.mmd --out flow.json` writes the spec
|
|
59
59
|
(layout computed once). Only write a custom scene module when no type fits
|
|
60
60
|
(`references/custom-scenes.md`): that file also covers an isometric view
|
|
61
|
-
(camera, solids, depth order, label anchors)
|
|
61
|
+
(camera, solids, depth order, label anchors), several tokens moving at once and
|
|
62
|
+
dashed connectors with diamond junctions and light pulses.
|
|
62
63
|
4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
|
|
63
64
|
shipped: deterministic, settled steps, rounded numbers, token-only colours,
|
|
64
65
|
escaped labels, labels fit, holds the final frame.
|
|
@@ -113,7 +114,7 @@ headers when redistributing the vendored runtime and adapters.
|
|
|
113
114
|
| `references/targets.md` | Where it will be shown and what each target allows |
|
|
114
115
|
| `references/styles.md` | Neutral default, style files, brand presets, contrast |
|
|
115
116
|
| `references/qc.md` | Review stages, checklist, review-report template |
|
|
116
|
-
| `references/custom-scenes.md` | Writing a one-off scene module, including isometric views
|
|
117
|
+
| `references/custom-scenes.md` | Writing a one-off scene module, including isometric views, several tokens at once, and connectors with pulses |
|
|
117
118
|
| `references/ecosystem.md` | When GSAP, HyperFrames, Remotion, Motion Canvas, Manim, Mermaid or ELK are the better tool |
|
|
118
119
|
|
|
119
120
|
For rendering, slide packaging and video, see the **motion-render** skill.
|
|
@@ -32,10 +32,14 @@ Rules:
|
|
|
32
32
|
no module-level mutable state.
|
|
33
33
|
- Colours only via `tok()`; numbers in strings via `num()`. Named colours
|
|
34
34
|
(`"red"`) are literals too.
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
35
|
+
- Say which token pairs the scene draws: `contrastPairs`. The gate holds the
|
|
36
|
+
style to those pairs (WCAG 1.4.3, 1.4.11) and only warns about the shared
|
|
37
|
+
ones you leave out, so a brand palette is never failed on a pair the scene
|
|
38
|
+
never shows. `kit.sharedPairs("ink/bg", "accent/bg", …)` picks shared pairs by
|
|
39
|
+
name; write out others, such as
|
|
40
|
+
`{ fg: "accent", bg: "surface", min: 3, use: "bar on its track" }` (4.5 for
|
|
41
|
+
text, 3 for shapes; `references/styles.md`). A scene that declares none is
|
|
42
|
+
held to every shared pair, so declare what you draw.
|
|
39
43
|
- Use `fade()`/`el()` so invisible elements disappear; `drawOn()` for lines.
|
|
40
44
|
- Ids (clip paths, gradients, masks, markers, filters) MUST be built from
|
|
41
45
|
`idPrefix`, the second argument's field: `${idPrefix}-clip`, referenced as
|
|
@@ -154,6 +158,32 @@ arrived, and the arrivals have filled, before the step's time (the settled-step
|
|
|
154
158
|
rule in the gate applies as ever), and a token that stops mid-path is not a
|
|
155
159
|
resting state. A token never loops back to the start.
|
|
156
160
|
|
|
161
|
+
## Connectors, junctions and pulses
|
|
162
|
+
|
|
163
|
+
`kit` also ties pieces together (`runtime/connectors.mjs`). Template:
|
|
164
|
+
`examples/connectors.scene.mjs` (a request fans out through a diamond splitter;
|
|
165
|
+
a result rides an isometric feeder line through three junctions).
|
|
166
|
+
|
|
167
|
+
| Need | Use |
|
|
168
|
+
|---|---|
|
|
169
|
+
| A route | `connectorPath(points, { camera? })`: flat `{ x, y }` points in pixels, or world `{ x, y, z }` points projected by `camera` (build it once if the camera rests, each frame if it moves). Positions go by distance, in the world under a camera |
|
|
170
|
+
| A dashed connector | `drawConnector(path, p, { stroke, width, dash, arrow, opacity })`: draws the route up to fraction `p`, a dashed line whose dashes stay put as it grows. Draw it on with `progress(t, start, 0.5, easeStandard)`; at `p = 1` it is the resting dashed line. An open-V arrowhead rides the leading end (`arrow: false` for none) |
|
|
171
|
+
| A diamond junction | `drawJunction({ at, camera?, plane, size, lit })` where connectors turn, split or join. `plane: "screen"` (default) stands on the picture, `"floor"` lies in an iso view's floor plane (give it the world point and the `camera`). `lit` (0..1) cross-fades the reached layer in, as a node's two layers do |
|
|
172
|
+
| A light pulse | `drawPulse(path, t, { start, duration, lag?, ease?, hold? }, { color, radius })`: a head with a soft glow and a fading tail, from the connector's start to its end, once. `color` is a token (default `emphasis`). Gone at `pulseEnd(run)`, or held at the end with `hold` |
|
|
173
|
+
|
|
174
|
+
**One pulse per step, inside the beat.** A pulse is a token with a glow: it runs
|
|
175
|
+
once, in its step's beat, and is over before the step. Take `pulseEnd(run)`
|
|
176
|
+
(`start + duration + lag`), add the time its target takes to light (200–300 ms),
|
|
177
|
+
and put the step's `at` at least 50 ms after that; the settled-frame rule in the
|
|
178
|
+
gate then holds. Several pulses may run in one beat: one per connector, starting
|
|
179
|
+
together to fan out from a junction (the twin pulses of an explainer), or one
|
|
180
|
+
after another, each starting when the last has arrived. Light a junction or a
|
|
181
|
+
target when the pulse reaches it: `lit: progress(t, arriveAt, 0.25, easeStandard)`,
|
|
182
|
+
where `arriveAt` is `run.start + run.duration` (with `ease: linear`, a junction
|
|
183
|
+
at a fraction `f` of the path is reached at `run.start + f * run.duration`).
|
|
184
|
+
A pulse never repeats while a step rests: a connector that pulses on a loop is
|
|
185
|
+
ambient motion, which the canon rules out.
|
|
186
|
+
|
|
157
187
|
Canon: no loops, no ambient motion, no continuous scrubbing, 12 s hard limit
|
|
158
188
|
(8 s target). An isometric scene plays once and holds its last frame, like any
|
|
159
189
|
other, and under reduced motion the player shows that frame. A constantly
|
|
@@ -77,6 +77,25 @@ Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
|
|
|
77
77
|
A shadow on the floor under each token (an ellipse of `ink` at ≈ 18 %,
|
|
78
78
|
squashed by `sin(elevation)`) shows where it is in the world.
|
|
79
79
|
|
|
80
|
+
## Connectors and pulses (derived)
|
|
81
|
+
|
|
82
|
+
- **Connector:** draws on from its start in 0.4–0.6 s on `easeStandard`, the
|
|
83
|
+
dashes fixed to the path so they do not crawl, and rests as a dashed line. The
|
|
84
|
+
open-V arrowhead rides the leading end.
|
|
85
|
+
- **Pulse:** one run per connector per step, 0.5–0.8 s on a flat connector, with
|
|
86
|
+
the tail lagging the head by 80–150 ms (split edges). On a long isometric
|
|
87
|
+
feeder use `linear`, 1.2–2 s, so the speed is constant and each junction
|
|
88
|
+
lights as it passes. It grows in over the first tenth of its life and fades
|
|
89
|
+
over the last sixth, so it never pops.
|
|
90
|
+
- **Timing rule:** the pulse is over (`pulseEnd`), and its target has lit
|
|
91
|
+
(200–300 ms), ≥ 50 ms before the step. Several pulses may share a beat: all
|
|
92
|
+
at once to fan out from a junction (twin pulses outward), or in sequence, each
|
|
93
|
+
starting as the last arrives.
|
|
94
|
+
- **Never** a pulse that repeats or runs while a step rests; that is looping
|
|
95
|
+
ambient motion (canon above). Loops are forbidden by contract and need review;
|
|
96
|
+
the gate's settled-frame rule only catches motion around the sampled step
|
|
97
|
+
boundaries, so it will not see every repeat.
|
|
98
|
+
|
|
80
99
|
## Container and text timing
|
|
81
100
|
|
|
82
101
|
- The container (box, card) starts moving immediately; new text appears only
|
|
@@ -65,10 +65,12 @@ unsettled, so it finishes in the first 95 % of each move and holds for the last
|
|
|
65
65
|
|
|
66
66
|
## Contrast
|
|
67
67
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
68
|
+
WCAG judges what a scene draws, not a palette: text needs 4.5:1 against what is
|
|
69
|
+
behind it (1.4.3), and the parts of a graphic that carry meaning need 3:1 against
|
|
70
|
+
the colours next to them (1.4.11). So `motion-kit check --style acme.json …`
|
|
71
|
+
**fails a scene only on the pairs it draws**, in both themes. The shared list
|
|
72
|
+
(`CONTRAST_PAIRS` in `runtime/style.mjs`) is every token pair the scene types
|
|
73
|
+
draw where the pair carries meaning in a step frame:
|
|
72
74
|
|
|
73
75
|
| Pair | Needs | Where it is drawn |
|
|
74
76
|
|---|---|---|
|
|
@@ -92,19 +94,36 @@ Exempt (`CONTRAST_EXEMPT`), each for a reason:
|
|
|
92
94
|
| accent on line | the accent draw-on covers the pending line; they meet only at the moving tip |
|
|
93
95
|
| onAccent on emphasis | no scene type draws it; the motion-kit logo does, and logos are exempt from WCAG 1.4.11 |
|
|
94
96
|
|
|
97
|
+
Each scene type draws some of these, not all (`SCENE_TYPE_PAIRS`): a `hub-spoke`
|
|
98
|
+
draws no text on the canvas, and a `sequence` draws no ink on surface.
|
|
99
|
+
A style that misses a pair is reported once per run, as `⚠ style:` with the
|
|
100
|
+
scene types that draw it, and fails exactly those scenes; every other scene
|
|
101
|
+
passes, and `build`, `export` and the rest print `warning: contrast:` for the
|
|
102
|
+
shared pairs they do not draw. `build` alone also fails a style that misses a pair the page's player paints (ink/surface, onAccent/accent, muted/bg, emphasis/bg, line/bg, accent/bg, and ink/bg for the heading unless `--no-heading`), declared or not. `neutral` meets every pair, so it never warns.
|
|
103
|
+
|
|
95
104
|
Emphasis on accent is the pair most palettes miss: two saturated colours of
|
|
96
105
|
the same lightness (blue and orange, teal and rust) are about 1:1 apart once
|
|
97
106
|
hue is gone. On a white canvas it usually means a dark accent (neutral light
|
|
98
107
|
uses `#1d36a8`) with a mid-tone emphasis; on a dark canvas, a light emphasis
|
|
99
108
|
(neutral dark uses `#fbbf24`).
|
|
100
109
|
|
|
101
|
-
A custom scene
|
|
102
|
-
|
|
110
|
+
A custom scene says what it draws with `contrastPairs`: the gate holds the style
|
|
111
|
+
to those pairs and only warns about the shared ones it leaves out. Shared pairs
|
|
112
|
+
come by name from `kit.sharedPairs`; others are written out. A scene that
|
|
113
|
+
declares nothing is held to every shared pair, as before, so say what you draw:
|
|
103
114
|
|
|
104
115
|
```js
|
|
105
|
-
return { …, contrastPairs: [
|
|
116
|
+
return { …, contrastPairs: [
|
|
117
|
+
...kit.sharedPairs("ink/surface", "onAccent/accent", "line/bg", "accent/bg"),
|
|
118
|
+
{ fg: "accent", bg: "surface", min: 3, use: "progress bar on its track" },
|
|
119
|
+
] };
|
|
106
120
|
```
|
|
107
121
|
|
|
122
|
+
A figure in ink on paper with a green accent that never draws `emphasis` lists
|
|
123
|
+
the pairs it does draw and passes with a palette whose `emphasis` cannot meet
|
|
124
|
+
both the canvas and the accent. Declare a pair only if it is drawn: a declared
|
|
125
|
+
pair is a failure, a threshold of 4.5 for text and 3 for graphics.
|
|
126
|
+
|
|
108
127
|
## Where style files live
|
|
109
128
|
|
|
110
129
|
In the **consuming repo**, next to its specs (e.g. `diagrams/style.json` in a
|
|
@@ -102,7 +102,7 @@ folder holds exactly what the new manifest lists. Files no export wrote are
|
|
|
102
102
|
left alone and named in a warning; keep notes and review files elsewhere.
|
|
103
103
|
|
|
104
104
|
The CLI gates `build`, `export`, `bake`, `video` and `icon` before writing
|
|
105
|
-
output, including
|
|
105
|
+
output, including the style contrast of the pairs the scene draws (a shared pair it does not draw is only a printed warning). `build` also holds the style to what the page's player paints, whatever the scene declares: ink/surface, onAccent/accent, muted/bg, emphasis/bg, line/bg, accent/bg, and ink/bg for the heading unless `--no-heading`; so `check` can pass where `build` fails. Exports
|
|
106
106
|
include `runtimeHash`, a SHA-256 of runtime module paths and bytes, in the
|
|
107
107
|
manifest and in `inputHash`, together with format, locale and render settings.
|
|
108
108
|
A changed runtime invalidates the hash even before its package version changes.
|