@liqweed/motion-kit 0.6.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/README.md +6 -3
- package/cli/motion-kit.mjs +86 -3
- package/docs/spec/technique.md +12 -2
- package/examples/pull-request.json +93 -0
- package/examples/pull-request.mmd +15 -0
- package/lib/layout.mjs +236 -0
- package/lib/mermaid.mjs +382 -0
- package/lib/outdated.mjs +122 -0
- package/package.json +8 -4
- package/runtime/kit.mjs +2 -2
- package/runtime/motion.mjs +61 -0
- package/runtime/style.mjs +35 -3
- package/runtime/types/flowchart.mjs +403 -0
- package/runtime/types/hub-spoke.mjs +2 -1
- package/runtime/types/index.mjs +2 -0
- 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 +8 -3
- package/skills/animated-diagram/references/custom-scenes.md +4 -1
- package/skills/animated-diagram/references/ecosystem.md +3 -2
- package/skills/animated-diagram/references/motion-vocabulary.md +29 -0
- package/skills/animated-diagram/references/scene-types.md +63 -4
- package/skills/animated-diagram/references/styles.md +19 -0
- package/styles/neutral.json +4 -0
|
@@ -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)
|
|
@@ -53,8 +53,11 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
|
|
|
53
53
|
Write the spec, then render the step contact sheet and show it:
|
|
54
54
|
`motion-kit export spec.json -o <scratch>/sb --png --qc` → open `index.html`
|
|
55
55
|
or show the PNGs. Get a yes on the *story* before polishing.
|
|
56
|
-
3. **Build.** Spec-driven types first (`sequence`, `hub-spoke`, `timeline`, `stack
|
|
57
|
-
|
|
56
|
+
3. **Build.** Spec-driven types first (`sequence`, `hub-spoke`, `timeline`, `stack`,
|
|
57
|
+
`state-machine`, `request-journey`, `flowchart`). The user has a Mermaid
|
|
58
|
+
flowchart? `motion-kit import flow.mmd --out flow.json` writes the spec
|
|
59
|
+
(layout computed once). Only write a custom scene module when no type fits
|
|
60
|
+
(`references/custom-scenes.md`).
|
|
58
61
|
4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
|
|
59
62
|
shipped: deterministic, settled steps, rounded numbers, token-only colours,
|
|
60
63
|
escaped labels, labels fit, holds the final frame.
|
|
@@ -84,12 +87,14 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
|
|
|
84
87
|
mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
|
|
85
88
|
mk types; mk formats
|
|
86
89
|
mk check diagram.json # all formats × locales
|
|
90
|
+
mk import flow.mmd -o flow.json # Mermaid flowchart → sequence or flowchart spec, then checked
|
|
87
91
|
mk check flow.scene.mjs -l en -l nl --options labels.mjs # a custom module, with its text from the caller
|
|
88
92
|
mk build diagram.json -o diagram.html -f wide -l nl # Craft Page / standalone
|
|
89
93
|
mk export diagram.json -o out/ --png --qc # slides + review sheet
|
|
90
94
|
mk bake diagram.json -o diagram.svg -f wide # zero-JS animated SVG
|
|
91
95
|
mk video diagram.json -f 9:16 -o reel.mp4 --sheet sheet.png
|
|
92
96
|
mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page / element
|
|
97
|
+
mk outdated <repo>/components/motion-kit # newer release on npm? exit 1 + the re-vendor command
|
|
93
98
|
node <repo>/components/motion-kit/check.mjs flow.scene.mjs -l en -l nl --style brand.json --options labels.mjs # the vendored gate, same checks
|
|
94
99
|
```
|
|
95
100
|
|
|
@@ -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,8 +9,9 @@ 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
|
-
| **
|
|
13
|
-
| **
|
|
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 |
|
|
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 |
|
|
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 |
|
|
15
16
|
| **resvg-js** | MPL-2.0 | SVG → PNG without a browser | motion-kit's rasterizer |
|
|
16
17
|
|
|
@@ -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 ·
|
|
@@ -138,6 +138,65 @@ separate enclosures with the same name. Hops with `async: true` stay dashed,
|
|
|
138
138
|
including after activation. Return paths are ordinary hops in the opposite
|
|
139
139
|
direction. See `examples/checkout.json`.
|
|
140
140
|
|
|
141
|
+
### `flowchart`: a process with branches and joins
|
|
142
|
+
|
|
143
|
+
Usually imported from Mermaid rather than written by hand:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
motion-kit import flow.mmd --out flow.json # also checks flow.json in every format (or only the --format ones)
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```json
|
|
150
|
+
{ "type": "flowchart", "id": "pull-request",
|
|
151
|
+
"title": "…", "description": "…",
|
|
152
|
+
"direction": "down", // "up", "right", "left"
|
|
153
|
+
"nodes": [ { "id": "ci", "label": "CI passes?", "shape": "decision", "rank": 1, "pos": 0.25 }, … ],
|
|
154
|
+
"edges": [ { "from": "ci", "to": "fix", "label": "No" },
|
|
155
|
+
{ "from": "a", "to": "d", "via": [[1, 0.75]] },
|
|
156
|
+
{ "from": "login", "to": "auth", "dashed": true }, … ] }
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
2–12 nodes, 1–20 edges. The layout is stored in the spec: `rank` is a node's
|
|
160
|
+
layer along the flow (whole numbers), `pos` its place across the flow in node
|
|
161
|
+
pitches (nodes on one rank ≥ 1 apart), and an edge spanning several ranks has
|
|
162
|
+
one `via` waypoint per rank between. The importer computes these once at build
|
|
163
|
+
time (`lib/layout.mjs`, a layered layout); the scene type only scales them to
|
|
164
|
+
each format, so the runtime never lays a graph out. Shapes: `box` (default),
|
|
165
|
+
`round`, `pill`, `decision`. Edges may carry a short one-line `label`, be
|
|
166
|
+
`dashed`, or have no arrowhead (`"arrow": false`). Nodes may carry `detail`.
|
|
167
|
+
|
|
168
|
+
Storyboard: the chart appears rank by rank in pending colours → nodes fill
|
|
169
|
+
accent one at a time in flow order (rank, then across), each incoming connector
|
|
170
|
+
drawing on in accent just before its node fills → an emphasis outline marks the
|
|
171
|
+
node just reached. A connector that points back (a retry loop) turns accent
|
|
172
|
+
while its source fills. Steps = one per node; step ids are the node ids.
|
|
173
|
+
`direction` is the flow in wide formats; 9:16 and `tall` flow downward, and a
|
|
174
|
+
format falls back to the other axis when the preferred one does not fit. Throws
|
|
175
|
+
when labels, edge labels or connectors would collide: shorter labels, fewer
|
|
176
|
+
ranks or a larger format. See `examples/pull-request.mmd` and its spec.
|
|
177
|
+
|
|
178
|
+
### Importing Mermaid
|
|
179
|
+
|
|
180
|
+
`motion-kit import <file.mmd | ->` turns a Mermaid flowchart into a spec
|
|
181
|
+
(stdout, or `--out`; `--id`, `--title`, `--description` override what the
|
|
182
|
+
chart says). A plain chain (each node one link in and one out, no link labels,
|
|
183
|
+
no dotted links) becomes a `sequence`; anything else becomes a `flowchart`.
|
|
184
|
+
|
|
185
|
+
- Read: `flowchart`/`graph` with `TB`/`TD`/`BT`/`LR`/`RL`; `[box]`, `(round)`,
|
|
186
|
+
`([pill])`, `{decision}`, `{{decision}}`; quoted labels, `<br>`, `#quot;`
|
|
187
|
+
codes; `-->`, `---`, `-.->`, `-.-`, `==>`, `===` with `|text|` or
|
|
188
|
+
`-- text -->` labels; chains and `&` groups; `accTitle`, `accDescr`, a
|
|
189
|
+
front-matter `title`. The title and description become the scene's
|
|
190
|
+
accessible name and description; without `accDescr` the description lists
|
|
191
|
+
every link in words.
|
|
192
|
+
- Ignored with a warning (colours come from the motion-kit style): `classDef`,
|
|
193
|
+
`class`, `style`, `linkStyle`, `:::name`, `%%{init}%%`, front-matter `config`.
|
|
194
|
+
- Errors naming the line: subgraphs and `direction`, `click`, other shapes
|
|
195
|
+
(circle, database, subroutine, parallelogram, …), `@{ shape }`, two-way,
|
|
196
|
+
circle and cross links, `~~~`, link ids, self-loops, markdown strings, HTML
|
|
197
|
+
in labels, and more than 12 nodes or 20 links. Sequence, state and ER
|
|
198
|
+
diagrams are not converted.
|
|
199
|
+
|
|
141
200
|
## Storyboards for types not built yet
|
|
142
201
|
|
|
143
202
|
Build these as custom scenes (`custom-scenes.md`) first. Promote one to a type
|
|
@@ -149,7 +208,7 @@ once it has been used twice.
|
|
|
149
208
|
| `comparison` | option A vs B on criteria | two columns appear → criteria rows fill one at a time → the deciding row emphasised |
|
|
150
209
|
| `funnel` / `data-flow` | volume or data narrowing/merging | sources appear → streams draw on and merge → result fills |
|
|
151
210
|
|
|
152
|
-
Auto-layout
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
211
|
+
Auto-layout happens at build time, never in `frame()`: `motion-kit import`
|
|
212
|
+
lays out Mermaid flowcharts as `flowchart` specs (above). State diagrams are
|
|
213
|
+
not imported yet; write a `state-machine` spec. Don't convert sequence or ER
|
|
214
|
+
diagrams lossily.
|
|
@@ -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",
|