@liqweed/motion-kit 0.3.0 → 0.5.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 +63 -10
- package/adapters/astro/AnimatedDiagram.astro +150 -24
- package/adapters/element/README.md +6 -1
- package/adapters/element/motion-diagram.mjs +4 -3
- package/adapters/page/README.md +8 -2
- package/adapters/slidev/AnimatedDiagram.vue +24 -0
- package/cli/motion-kit.mjs +85 -81
- package/docs/spec/technique.md +166 -63
- package/examples/custom-pulse.scene.mjs +3 -0
- package/examples/incident.json +18 -0
- package/examples/web-stack.json +17 -0
- package/lib/build.mjs +26 -12
- package/lib/bundle.mjs +9 -2
- package/lib/check.mjs +219 -15
- package/lib/export.mjs +135 -16
- package/lib/gate.mjs +90 -0
- package/lib/load.mjs +49 -19
- package/package.json +6 -3
- package/runtime/bake.mjs +18 -4
- package/runtime/kit.mjs +59 -0
- package/runtime/links.mjs +314 -0
- package/runtime/page.mjs +52 -0
- package/runtime/parts.mjs +15 -0
- package/runtime/patch.mjs +297 -0
- package/runtime/player.mjs +334 -130
- package/runtime/scene.mjs +82 -5
- package/runtime/style.mjs +64 -16
- package/runtime/types/hub-spoke.mjs +7 -7
- package/runtime/types/index.mjs +4 -0
- package/runtime/types/sequence.mjs +5 -5
- package/runtime/types/stack.mjs +227 -0
- package/runtime/types/timeline.mjs +405 -0
- package/skills/animated-diagram/SKILL.md +30 -7
- package/skills/animated-diagram/references/custom-scenes.md +64 -9
- package/skills/animated-diagram/references/interactivity.md +150 -15
- package/skills/animated-diagram/references/qc.md +5 -2
- package/skills/animated-diagram/references/scene-types.md +45 -2
- package/skills/animated-diagram/references/styles.md +45 -5
- package/skills/animated-diagram/references/targets.md +7 -5
- package/skills/animated-diagram/references/technique.md +14 -4
- package/skills/motion-render/SKILL.md +31 -8
- package/skills/motion-render/references/formats.md +8 -8
- package/skills/project-logo/SKILL.md +15 -4
- package/styles/neutral.json +2 -2
|
@@ -2,24 +2,46 @@
|
|
|
2
2
|
|
|
3
3
|
## The player (`runtime/player.mjs`, used by `build`, the Astro adapter, Craft Pages)
|
|
4
4
|
|
|
5
|
-
- Starts on the **final frame
|
|
6
|
-
|
|
5
|
+
- Starts on the **final frame**. A server render can emit the player's whole
|
|
6
|
+
first state with `playerMarkup(scene, { id, … })`, `PLAYER_CSS` and
|
|
7
|
+
`themeCss(selector, style, theme)`: the final frame, the step list and the
|
|
8
|
+
colours without JavaScript, with the controls inert, and nothing moves when
|
|
9
|
+
the player mounts. The Astro adapter and `build` do this.
|
|
10
|
+
- Replays once when ~40 % of the diagram, or 40 % of the viewport, shows, so a
|
|
11
|
+
diagram taller than the screen starts too; then holds. While the diagram is
|
|
12
|
+
out of view or not rendered (`display: none`), its clock waits and nothing
|
|
13
|
+
is drawn; it resumes where it stopped.
|
|
7
14
|
- Controls: play/pause (always present, WCAG 2.2.2), one button per step (jumps
|
|
8
15
|
by default), optional scrubber, caption with the active step's `detail`.
|
|
9
|
-
|
|
16
|
+
Every control is at least 44 × 44 px. The caption and the play button keep
|
|
17
|
+
the size of their longest text, so playback does not move the page.
|
|
18
|
+
- Keyboard on the diagram (a focusable group named by the title, described by
|
|
19
|
+
a hint, `labels.keys`): ← / → step, Home / End, Space play/pause.
|
|
10
20
|
- `prefers-reduced-motion`: final frame, no autoplay, no play button.
|
|
11
|
-
- `prefers-color-scheme`: light/dark tokens switch live.
|
|
21
|
+
- `prefers-color-scheme`: light/dark tokens switch live, unless `theme` is set.
|
|
22
|
+
Tokens are set one property at a time, so CSS on the container stays.
|
|
12
23
|
- Screen readers: `role="img"` + `<title>`/`<desc>`, a visually hidden ordered
|
|
13
24
|
list of all steps with details; the visible caption is `aria-hidden`.
|
|
25
|
+
- Ids: every player renders with its own id prefix (`options.id`, else the
|
|
26
|
+
scene id plus a counter), so scenes that define ids can share a page.
|
|
27
|
+
- The stylesheet is added to the document whenever a player mounts and none is
|
|
28
|
+
there, so a page swap (Astro view transitions) cannot leave players unstyled.
|
|
29
|
+
- Each frame updates the SVG in place (`patchMarkup`, `runtime/patch.mjs`):
|
|
30
|
+
nodes that persist keep their identity and only changed attributes and text
|
|
31
|
+
are written, so hover state survives playback. Page CSS must not put
|
|
32
|
+
transitions or animations on the diagram's SVG: with persistent nodes they
|
|
33
|
+
would run between frames, and exports would no longer match what plays.
|
|
14
34
|
- Capture hook: `window.__motionKit[id].seek(t)` (for Playwright/HyperFrames-
|
|
15
35
|
style renderers).
|
|
16
36
|
|
|
17
|
-
|
|
18
|
-
`
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
37
|
+
Steps are addressed by zero-based index or by step `id` (a spec node's or
|
|
38
|
+
spoke's `id`, or a custom scene's `steps[i].id`): ids survive steps being added
|
|
39
|
+
or reordered. `controller.seekStep(ref)` jumps; `controller.playToStep(ref)`
|
|
40
|
+
plays forward from the current time and stops at the step's exact settled time.
|
|
41
|
+
Backward and same-step calls jump, and reduced motion always jumps. A new call
|
|
42
|
+
replaces the previous target; `pause()` holds the current frame, `seek(t)`
|
|
43
|
+
cancels playback, and `play()` continues to the end. An invalid index or an
|
|
44
|
+
unknown id throws `RangeError`.
|
|
23
45
|
|
|
24
46
|
Pass `{ animateSteps: true }` to `mountPlayer(container, scene, options)` to
|
|
25
47
|
enable this behavior for the step buttons and arrow/Home/End keys. The default
|
|
@@ -27,14 +49,127 @@ keeps instant navigation. Call `controller.destroy()` before removing or
|
|
|
27
49
|
replacing a player: it cancels playback, visibility observation, theme listening
|
|
28
50
|
and its capture-hook entry.
|
|
29
51
|
|
|
52
|
+
Reaching a player from page scripts: `mountPlayer` returns the controller; the
|
|
53
|
+
`<motion-diagram>` element and the Astro adapter's root element expose it as
|
|
54
|
+
`.controller` and dispatch `motion-ready` (bubbling, `detail.controller`) once
|
|
55
|
+
it is mounted. The player may already be mounted when your script runs, so use
|
|
56
|
+
whichever comes first. Give an Astro diagram an `id` to find it:
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
const el = document.getElementById("flow");
|
|
60
|
+
const go = (c) => c.playToStep("payment");
|
|
61
|
+
el.controller ? go(el.controller) : el.addEventListener("motion-ready", (e) => go(e.detail.controller), { once: true });
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Linking the page to the diagram (`runtime/links.mjs`)
|
|
65
|
+
|
|
66
|
+
Two helpers bind a controller to the page around the player. Both are
|
|
67
|
+
dependency-free browser code (no DOM at import), take a step by `id` or index,
|
|
68
|
+
throw `RangeError` for an unknown id when they bind (not when the reader gets
|
|
69
|
+
there), never move focus or layout, and return a `dispose()` that removes
|
|
70
|
+
their listeners, observers and marks. Call it before removing the elements or
|
|
71
|
+
the player (Astro: on `astro:before-swap`).
|
|
72
|
+
|
|
73
|
+
- **Hover/focus linking:** `linkSteps(controller, rootOrElements, options)`.
|
|
74
|
+
Every element with `data-mk-step` under the root (or the elements given)
|
|
75
|
+
selects its step on hover (mouse and pen), keyboard focus (also focus inside
|
|
76
|
+
it) and click; touch selects on tap, so nothing is hover-only. Make terms
|
|
77
|
+
`<button type="button" data-mk-step="payment">` so the keyboard reaches
|
|
78
|
+
them. A selection jumps to the settled step; `animate: true` plays forward
|
|
79
|
+
to a later step, except under reduced motion. The step stays when the
|
|
80
|
+
pointer or focus leaves; `restore: true` turns hover and focus into a
|
|
81
|
+
preview: once neither is on a term, the diagram returns to the frame it
|
|
82
|
+
showed before, and a click keeps its step. The terms of the selected step
|
|
83
|
+
get `aria-current="step"` (`mark: false` to style them yourself);
|
|
84
|
+
`onChange(step, element)` reports each selection (`-1, null` on restore).
|
|
85
|
+
Terms are collected when binding; bind again for terms added later. When
|
|
86
|
+
scroll sections carry `data-mk-step` as well, pass the terms themselves
|
|
87
|
+
rather than a root that contains the sections.
|
|
88
|
+
- **Scroll-driven steps:** `scrollSteps(controller, sections, options)`.
|
|
89
|
+
Each section names its step with `data-mk-step`, else by order (the third
|
|
90
|
+
section shows step 2). The active section is the last one whose top has
|
|
91
|
+
crossed a line across the viewport (`line`, a share of its height from the
|
|
92
|
+
top, default 0.5; `root` for a scrolling container), found with an
|
|
93
|
+
IntersectionObserver whose root ends at that line. It stays active through
|
|
94
|
+
the gap after it, and the last section stays active below it. Moving one
|
|
95
|
+
section forward plays to its step (`playToStep`); moving back, skipping
|
|
96
|
+
sections, the first section and reduced motion jump (`seekStep`);
|
|
97
|
+
`animate: false` always jumps. Above the first section the diagram keeps its
|
|
98
|
+
frame. The active section gets `aria-current="step"` (style it without
|
|
99
|
+
changing its size, e.g. opacity); `onChange(index, section)` reports each
|
|
100
|
+
change (`-1, null` above the first). It never scrubs continuously: the
|
|
101
|
+
diagram only ever rests on settled steps. Mount the player with
|
|
102
|
+
`autoplay: "none"`, and leave room below the last section (e.g.
|
|
103
|
+
`padding-bottom: 50vh`) so its top can reach the line. Without
|
|
104
|
+
IntersectionObserver it does nothing and the text still reads.
|
|
105
|
+
|
|
106
|
+
Plain HTML (`motion-kit vendor … --adapter page`):
|
|
107
|
+
|
|
108
|
+
```html
|
|
109
|
+
<article id="story">
|
|
110
|
+
<section data-mk-step="order"><h2>The order</h2><p>…</p></section>
|
|
111
|
+
<section data-mk-step="payment"><h2>Payment</h2><p>The <button type="button" data-mk-step="payment">card check</button> …</p></section>
|
|
112
|
+
<section data-mk-step="shipping"><h2>Shipping</h2><p>…</p></section>
|
|
113
|
+
</article>
|
|
114
|
+
<div id="flow"></div>
|
|
115
|
+
<script type="module">
|
|
116
|
+
import { mountPlayer } from "./motion-kit/runtime/player.mjs";
|
|
117
|
+
import { linkSteps, scrollSteps } from "./motion-kit/runtime/links.mjs";
|
|
118
|
+
const player = mountPlayer(document.getElementById("flow"), scene, { autoplay: "none" });
|
|
119
|
+
const story = document.getElementById("story");
|
|
120
|
+
const stopScroll = scrollSteps(player, story.querySelectorAll("section"));
|
|
121
|
+
// The sections carry data-mk-step too: pass the terms, not the article.
|
|
122
|
+
const stopLinks = linkSteps(player, story.querySelectorAll("button[data-mk-step]"));
|
|
123
|
+
</script>
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
`<motion-diagram>` (`--adapter element`): wait for the controller.
|
|
127
|
+
|
|
128
|
+
```js
|
|
129
|
+
import { scrollSteps } from "./motion-kit/runtime/links.mjs";
|
|
130
|
+
const el = document.querySelector("motion-diagram");
|
|
131
|
+
const bind = (c) => scrollSteps(c, document.querySelectorAll("#story section"));
|
|
132
|
+
el.controller ? bind(el.controller) : el.addEventListener("motion-ready", (e) => bind(e.detail.controller), { once: true });
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
The element remounts when an attribute changes, which makes a new controller:
|
|
136
|
+
listen to every `motion-ready` (not `once`) and dispose the previous binding
|
|
137
|
+
first if the page changes attributes.
|
|
138
|
+
|
|
139
|
+
Astro (`--adapter astro`), with `id` on the diagram:
|
|
140
|
+
|
|
141
|
+
```astro
|
|
142
|
+
<AnimatedDiagram spec={spec} format="tall" id="flow" />
|
|
143
|
+
<script>
|
|
144
|
+
import { linkSteps, scrollSteps } from "../motion-kit/runtime/links.mjs";
|
|
145
|
+
const el = document.getElementById("flow");
|
|
146
|
+
const bind = (c) => {
|
|
147
|
+
const stops = [scrollSteps(c, document.querySelectorAll("#story section")), linkSteps(c, document.querySelectorAll("#story button[data-mk-step]"))];
|
|
148
|
+
document.addEventListener("astro:before-swap", () => stops.forEach((stop) => stop()), { once: true });
|
|
149
|
+
};
|
|
150
|
+
el.controller ? bind(el.controller) : el.addEventListener("motion-ready", (e) => bind(e.detail.controller), { once: true });
|
|
151
|
+
</script>
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Module scripts run once per load: with view transitions (`<ClientRouter />`),
|
|
155
|
+
run the binding code in an `astro:page-load` listener so each page binds its
|
|
156
|
+
own diagram; the `astro:before-swap` dispose releases the previous one.
|
|
157
|
+
|
|
158
|
+
A page from `motion-kit build` has them on the `MotionKitRuntime` global.
|
|
159
|
+
|
|
160
|
+
The step mapping is pure and exported for tests and custom bindings:
|
|
161
|
+
`stepRef(scene, ref)` (id first, then a whole-number index),
|
|
162
|
+
`sectionSteps(scene, refs)` (a section's reference, else its position),
|
|
163
|
+
`activeSection(tops, line)` and `scrollMove({ from, to, fromStep, toStep,
|
|
164
|
+
animate, reduced })` (`"play"`, `"seek"` or null).
|
|
165
|
+
|
|
30
166
|
## Patterns worth adding per diagram (in the page around the player)
|
|
31
167
|
|
|
32
168
|
- **Hover/focus linking:** terms in the surrounding text highlight the matching
|
|
33
|
-
part of the diagram
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
steps
|
|
37
|
-
continuously on scroll; jump to settled steps.
|
|
169
|
+
part of the diagram: `linkSteps` above. Use step ids, not positions.
|
|
170
|
+
- **Scroll-driven steps:** for long-form explainers, one text section per step:
|
|
171
|
+
`scrollSteps` above. Don't scrub continuously on scroll; jump to settled
|
|
172
|
+
steps.
|
|
38
173
|
- **Details on demand:** step buttons + caption first; tooltips only for
|
|
39
174
|
secondary facts.
|
|
40
175
|
- **Explorables:** a parameter slider can change the *spec* (e.g. number of
|
|
@@ -10,8 +10,8 @@ Model screenshots are evidence, not approval. **A human signs off on the look.**
|
|
|
10
10
|
2. **Timing:** QC frames 0.2 s before/after each step: overlapping text, abrupt
|
|
11
11
|
jumps, elements vanishing, half-drawn lines, stray dots. Regular sampling
|
|
12
12
|
misses broken transitions; look *around* the transitions.
|
|
13
|
-
3. **Phone size:** the 360 px row in the sheet
|
|
14
|
-
text under 14 px at 1×.
|
|
13
|
+
3. **Phone size:** the 360 px row in the sheet (the scene's `tall` layout); the
|
|
14
|
+
`9:16` layout; no text under 14 px at 1×.
|
|
15
15
|
4. **Brand and facts:** tokens only, approved style, approved copy, no invented
|
|
16
16
|
numbers or superlatives, every locale checked.
|
|
17
17
|
5. **Final file:**
|
|
@@ -20,6 +20,9 @@ Model screenshots are evidence, not approval. **A human signs off on the look.**
|
|
|
20
20
|
reads the step list.
|
|
21
21
|
- Video: `video --sheet` contact sheet; duration, aspect and size via the
|
|
22
22
|
printed probe; watch it once at full size.
|
|
23
|
+
- Exports: `manifest.json` names the source commit and says
|
|
24
|
+
`"sourceDirty": false`; a `true` means the frames come from uncommitted
|
|
25
|
+
changes. Re-exporting into a folder replaces what the last export wrote.
|
|
23
26
|
|
|
24
27
|
**Don't trust virtual time.** Headless `--virtual-time-budget` doesn't advance
|
|
25
28
|
the player's animation clock faithfully. Use `--timeout=<ms>` (real time) or a
|
|
@@ -38,6 +38,51 @@ time draws (carrying an emphasis dot) and the spoke fills. Steps = hub, then
|
|
|
38
38
|
each spoke. Layouts: radial ellipse (wide/square), tree with an outside trunk
|
|
39
39
|
(9:16, tall). Throws when boxes would overlap: fewer spokes or a larger format.
|
|
40
40
|
|
|
41
|
+
### `timeline`: events in time
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{ "type": "timeline", "id": "incident",
|
|
45
|
+
"title": "…", "description": "…",
|
|
46
|
+
"events": [ { "when": "09:02", "label": "Alert fires", "detail": "…" },
|
|
47
|
+
…,
|
|
48
|
+
{ "when": "Thursday", "label": "Review", "planned": true } ],
|
|
49
|
+
"now": { "label": "Now", "detail": "…" }, // optional
|
|
50
|
+
"fontSize": 18 } // optional max; auto-fit otherwise
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
2–8 events in time order, each with a short `when` (one line: "09:02",
|
|
54
|
+
"Q3 2026") and a `label`. `planned: true` marks an event still to come;
|
|
55
|
+
planned events go last and need a `now`. Events and `now` may carry an `id`
|
|
56
|
+
for their step. Storyboard: the axis draws on → milestones drop onto it in
|
|
57
|
+
order; an event that has happened fills accent and the axis behind it turns
|
|
58
|
+
accent, a planned one stays pending → the "now" marker (the emphasis element)
|
|
59
|
+
settles on the axis after the last past event. Steps = one per event, then
|
|
60
|
+
`now`. Events are spaced evenly, not to scale. Layouts: horizontal axis with
|
|
61
|
+
labels below, or alternating above and below when that saves lines (wide
|
|
62
|
+
aspects, 1:1); vertical axis with labels on the right (9:16, tall). Throws when
|
|
63
|
+
a label or the now marker does not fit: fewer events, shorter labels or a
|
|
64
|
+
larger format.
|
|
65
|
+
|
|
66
|
+
### `stack`: layers that build on each other
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{ "type": "stack", "id": "web-stack",
|
|
70
|
+
"title": "…", "description": "…",
|
|
71
|
+
"layers": [ { "label": "Browser", "detail": "…" }, …,
|
|
72
|
+
{ "label": "Database", "detail": "…" } ],
|
|
73
|
+
"direction": "down", // or "up": the packet enters at the bottom
|
|
74
|
+
"fontSize": 18 } // optional max; auto-fit otherwise
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
2–8 layers, listed top to bottom as drawn; a layer may carry an `id` for its
|
|
78
|
+
step. Storyboard: the layers rise into place bottom-up → a packet (the emphasis
|
|
79
|
+
dot) enters on a rail beside the stack and hops layer to layer; the layer it
|
|
80
|
+
reaches fills accent, a layer it has left keeps an accent outline, and the rail
|
|
81
|
+
behind it turns accent. Steps = one per layer, in travel order (top → bottom
|
|
82
|
+
for `down`, bottom → top for `up`). Layout: one column of layers with the rail
|
|
83
|
+
on the right in every format; labels take one line, two when needed. Throws
|
|
84
|
+
when the layers do not fit: fewer layers, shorter labels or a larger format.
|
|
85
|
+
|
|
41
86
|
## Storyboards for types not built yet
|
|
42
87
|
|
|
43
88
|
Build these as custom scenes (`custom-scenes.md`) first. Promote one to a type
|
|
@@ -45,9 +90,7 @@ once it has been used twice.
|
|
|
45
90
|
|
|
46
91
|
| Type | Helps the viewer understand | Storyboard |
|
|
47
92
|
|---|---|---|
|
|
48
|
-
| `stack` | layers build on each other (architecture, security layers) | layers rise bottom-up; then a request/data packet travels down/up, each layer lighting as it passes |
|
|
49
93
|
| `before-after` | what changes | left state fully shown → a divider sweeps → right state builds; differences highlighted with the emphasis colour |
|
|
50
|
-
| `timeline` | events in time | axis draws on → milestones drop in order → "now" marker settles |
|
|
51
94
|
| `comparison` | option A vs B on criteria | two columns appear → criteria rows fill one at a time → the deciding row emphasised |
|
|
52
95
|
| `state-machine` | states and transitions | all states (pending) → a token walks a path of transitions, the current state accent |
|
|
53
96
|
| `request-journey` | a request crossing system components | components in regions/boundaries → a dot travels the path, each hop lights, async edges dashed |
|
|
@@ -27,15 +27,55 @@ 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
|
-
"light": { "accent": "#
|
|
31
|
-
"dark": { "accent": "#
|
|
30
|
+
"light": { "accent": "#0a2a8a", "emphasis": "#05966a" },
|
|
31
|
+
"dark": { "accent": "#2563eb", "emphasis": "#a7f3d0" }
|
|
32
32
|
}
|
|
33
33
|
```
|
|
34
34
|
|
|
35
35
|
Missing tokens fall back to neutral. Colours must be `#rrggbb`. Unknown tokens
|
|
36
|
-
throw.
|
|
37
|
-
|
|
38
|
-
|
|
36
|
+
throw.
|
|
37
|
+
|
|
38
|
+
## Contrast
|
|
39
|
+
|
|
40
|
+
`motion-kit check --style acme.json …` checks every token pair the scene types
|
|
41
|
+
draw where the pair carries meaning in a step frame (`CONTRAST_PAIRS` in
|
|
42
|
+
`runtime/style.mjs`), in both themes, at WCAG thresholds: 4.5:1 for text,
|
|
43
|
+
3:1 for shapes and strokes.
|
|
44
|
+
|
|
45
|
+
| Pair | Needs | Where it is drawn |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| ink on bg | 4.5 | labels of reached nodes, on the canvas |
|
|
48
|
+
| ink on surface | 4.5 | labels inside pending boxes |
|
|
49
|
+
| muted on bg | 4.5 | labels of pending nodes, on the canvas |
|
|
50
|
+
| muted on surface | 4.5 | glyphs and icons inside pending circles |
|
|
51
|
+
| onAccent on accent | 4.5 | labels, glyphs and icons inside reached nodes |
|
|
52
|
+
| line on bg | 3 | connectors, outlines of pending nodes |
|
|
53
|
+
| accent on bg | 3 | reached nodes, drawn connectors |
|
|
54
|
+
| emphasis on bg | 3 | the emphasis ring and dot on the canvas |
|
|
55
|
+
| emphasis on accent | 3 | the ring around the reached node it marks: "here" told from "reached" without relying on hue |
|
|
56
|
+
|
|
57
|
+
Exempt (`CONTRAST_EXEMPT`), each for a reason:
|
|
58
|
+
|
|
59
|
+
| Pair | Why it is not checked |
|
|
60
|
+
|---|---|
|
|
61
|
+
| line on surface | a pending node's outline is its edge, told from the canvas outside it (line on bg), not from its own fill |
|
|
62
|
+
| accent on surface | the reached layer covers the pending one only while a node fills; a scene that draws accent on surface (a bar on a track) declares the pair |
|
|
63
|
+
| emphasis on surface | the ring crosses pending nodes only mid-hop, never in a step frame |
|
|
64
|
+
| accent on line | the accent draw-on covers the pending line; they meet only at the moving tip |
|
|
65
|
+
| onAccent on emphasis | no scene type draws it; the motion-kit logo does, and logos are exempt from WCAG 1.4.11 |
|
|
66
|
+
|
|
67
|
+
Emphasis on accent is the pair most palettes miss: two saturated colours of
|
|
68
|
+
the same lightness (blue and orange, teal and rust) are about 1:1 apart once
|
|
69
|
+
hue is gone. On a white canvas it usually means a dark accent (neutral light
|
|
70
|
+
uses `#1d36a8`) with a mid-tone emphasis; on a dark canvas, a light emphasis
|
|
71
|
+
(neutral dark uses `#fbbf24`).
|
|
72
|
+
|
|
73
|
+
A custom scene that draws another pair declares it, and the gate checks the
|
|
74
|
+
style against it for that scene:
|
|
75
|
+
|
|
76
|
+
```js
|
|
77
|
+
return { …, contrastPairs: [{ fg: "accent", bg: "surface", min: 3, use: "progress bar on its track" }] };
|
|
78
|
+
```
|
|
39
79
|
|
|
40
80
|
## Where style files live
|
|
41
81
|
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
| **Craft in-chat preview** | **no** (`html-preview` iframe blocks scripts) | baked SVG, or step PNGs | `bake -o x.svg` → `image-preview`; or `export --png` → `image-preview` items |
|
|
7
7
|
| **Slidev** (stagewright, docomply-presentations) | yes | one step per click (component registers its own clicks; composes with `v-click`) | `vendor <deck>/components/motion-kit --adapter slidev` → `<AnimatedDiagram :spec="spec" />`; `maxHeight` (default 380px fits under a title) |
|
|
8
8
|
| **Marp / PowerPoint / Keynote** | no | one slide per step, same position; transition None/Dissolve/Morph | `export --png --scale 2` (Marp, Google Slides) or the SVGs (PowerPoint 365, Keynote) |
|
|
9
|
-
| **Website** (Astro, React, static) | yes | server-rendered final frame + player | `vendor <repo>/src/motion-kit --adapter astro`; wide + tall instances switched with CSS |
|
|
9
|
+
| **Website** (Astro, React, static) | yes | server-rendered first state (final frame, step list, colours) + player | `vendor <repo>/src/motion-kit --adapter astro`; `<AnimatedDiagram spec={…}>` or `module="/src/…/x.scene.mjs" options={…}`; `theme`, `style`; wide + tall instances switched with CSS; CI runs the vendored `check.mjs` |
|
|
10
10
|
| **README / Obsidian / email / docs** | no | baked SVG (animated) or a GIF | `bake` (CSS animation inside SVG: works in browsers and GitHub `<img>`); `video -o x.gif` for email |
|
|
11
11
|
| **Video** (social, demos, talks) | n/a | MP4/WebM/GIF | `video -f 9:16 -o reel.mp4`; see motion-render |
|
|
12
12
|
|
|
@@ -19,9 +19,11 @@
|
|
|
19
19
|
- **Slides:** frames from one scene share a viewBox, so consecutive step slides
|
|
20
20
|
register exactly. Fonts in standalone SVG fall back to the viewer's system
|
|
21
21
|
font: send PNGs for decks that travel.
|
|
22
|
-
- **Websites:** pass serializable props (spec
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
22
|
+
- **Websites:** pass serializable props (a spec, or a module path and its
|
|
23
|
+
options) to islands; pass the page's locale's text as options, so the other
|
|
24
|
+
dictionaries stay out of client bundles; mount wide and tall, switch with CSS
|
|
25
|
+
(`display:none` also removes the hidden one from the a11y tree and stops its
|
|
26
|
+
clock). The server render reserves the controls' space: mounting causes no
|
|
27
|
+
layout shift.
|
|
26
28
|
- **Brand repos** keep their own style file next to their specs; motion-kit
|
|
27
29
|
ships only `neutral`.
|
|
@@ -31,12 +31,19 @@ Video maps frame `f` at `fps` to `t = f / fps` (30 fps × 25 s = 750 frames).
|
|
|
31
31
|
7. Round every number. `el()` rounds numeric attributes; numbers you put in a
|
|
32
32
|
template string (`transform`, `points`, path `d`) must go through `num()`.
|
|
33
33
|
The gate rejects any number with 5+ decimals.
|
|
34
|
-
8. No `Date`, `Math.random()`, `performance.now()` inside a scene
|
|
34
|
+
8. No `Date`, `Math.random()`, `performance.now()` inside a scene, nor in the
|
|
35
|
+
helpers it calls: the gate renders every sample under two stubbed clocks
|
|
36
|
+
and refuses a frame whose bytes change.
|
|
35
37
|
9. **Step frames are settled** (§4).
|
|
36
38
|
10. Markup is balanced and escaped: labels cannot inject markup.
|
|
37
39
|
11. Visibility decisions use rounded values: an element whose opacity rounds to
|
|
38
40
|
0 is dropped, and an opacity that rounds to 1 is omitted, so frames that
|
|
39
41
|
look identical are byte-identical (`fade()`, `el()` do this).
|
|
42
|
+
12. Ids come from the instance: anything in `<defs>` (clip path, gradient,
|
|
43
|
+
mask, marker, filter) is named `${idPrefix}-name`, with `idPrefix` from
|
|
44
|
+
`frame(t, { idPrefix })`. Two instances on one page (wide and tall, or the
|
|
45
|
+
same diagram twice) then never share an id. The gate renders with two
|
|
46
|
+
prefixes and refuses an id both share.
|
|
40
47
|
|
|
41
48
|
## 3. Authoring a timeline
|
|
42
49
|
|
|
@@ -77,9 +84,12 @@ Patterns:
|
|
|
77
84
|
|
|
78
85
|
`steps[i].at` is when build step *i* is fully shown, and its frame is what a
|
|
79
86
|
slide shows. It must look intentional on its own: nothing mid-motion, no
|
|
80
|
-
half-drawn line pointing at nothing, no fading dot. Rule: **the
|
|
81
|
-
|
|
82
|
-
|
|
87
|
+
half-drawn line pointing at nothing, no fading dot. Rule: **the step's own
|
|
88
|
+
motion comes to rest by `at`, and the next motion starts no earlier than
|
|
89
|
+
50 ms after it.** The gate asserts `frame(at − 1 ms) === frame(at)` and that
|
|
90
|
+
the frames 1, 15, 30 and 45 ms after `at` equal it too, so a slow fade passing
|
|
91
|
+
through `at` fails even when rounding hides it over 1 ms. Anything that fades
|
|
92
|
+
out by a step (a travelling dot) must reach 0 by `at`.
|
|
83
93
|
|
|
84
94
|
## 5. Layouts are computed per format
|
|
85
95
|
|
|
@@ -6,12 +6,22 @@ description: "Render motion-kit scenes (animated diagrams) to deliverables: slid
|
|
|
6
6
|
# Motion render
|
|
7
7
|
|
|
8
8
|
All outputs come from the same pure scene, so they always agree. Locate the
|
|
9
|
-
toolkit as in the animated-diagram skill
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
toolkit as in the animated-diagram skill's "Locate the toolkit": first
|
|
10
|
+
`MOTION_KIT_HOME`, then the npm package through `npx` (at the version of these
|
|
11
|
+
skills), then the plugin copy two levels above this skill. PNG and video need
|
|
12
|
+
`@resvg/resvg-js`, which the `npx` route installs; video also needs `ffmpeg`.
|
|
13
|
+
The plugin copy alone has neither, so prefer `npx` there.
|
|
12
14
|
|
|
13
15
|
```bash
|
|
14
|
-
|
|
16
|
+
PLUGIN="$(cd -P "<this skill's base directory>" && cd ../.. && pwd -P)" # -P: the base may be a symlink to a clone
|
|
17
|
+
V="$(node -p "require(process.argv[1] + '/package.json').version" "$PLUGIN")"
|
|
18
|
+
if [ -n "${MOTION_KIT_HOME:-}" ]; then
|
|
19
|
+
MK="$MOTION_KIT_HOME"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
|
|
20
|
+
elif npx -y "@liqweed/motion-kit@$V" --help >/dev/null 2>&1; then
|
|
21
|
+
MK="$PLUGIN"; mk() { npx -y "@liqweed/motion-kit@$V" "$@"; }
|
|
22
|
+
else
|
|
23
|
+
MK="$PLUGIN"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
|
|
24
|
+
fi
|
|
15
25
|
```
|
|
16
26
|
|
|
17
27
|
**Always run `mk check <scene>` first.** Exporters refuse scenes that fail the gate.
|
|
@@ -32,8 +42,8 @@ animated-diagram skill, `references/targets.md`.
|
|
|
32
42
|
```bash
|
|
33
43
|
mk export spec.json -o out/review --png --qc
|
|
34
44
|
```
|
|
35
|
-
`index.html` holds the steps, frames 0.2 s before and after each step, a phone-size row
|
|
36
|
-
review checklist. Fill in the review report (animated-diagram
|
|
45
|
+
`index.html` holds the steps, frames 0.2 s before and after each step, a phone-size row (the
|
|
46
|
+
scene's `tall` layout at 360 px, as a phone shows it) and the review checklist. Fill in the review report (animated-diagram
|
|
37
47
|
`references/qc.md`) and get a human approval line before delivery.
|
|
38
48
|
|
|
39
49
|
## Video
|
|
@@ -53,6 +63,11 @@ mk build spec.json -o out/page.html -f wide # Craft Page / standalone in
|
|
|
53
63
|
mk bake spec.json -o out/diagram.svg -f wide --fps 12 # zero-JS animated SVG
|
|
54
64
|
```
|
|
55
65
|
|
|
66
|
+
A custom module whose text comes from the caller (a site's dictionary) takes
|
|
67
|
+
scene options: `--options labels.json`, inline JSON, or an `.mjs` whose default
|
|
68
|
+
export is `({ format, locale }) => options`. `check`, `export`, `build`, `bake`,
|
|
69
|
+
`video` and `icon` pass them to the module's factory unchanged.
|
|
70
|
+
|
|
56
71
|
For plain HTML or a framework-independent live embed, use
|
|
57
72
|
`mk vendor public/motion-kit --adapter element`, then load
|
|
58
73
|
`./motion-kit/adapter/motion-diagram.mjs` with `type="module"` and place
|
|
@@ -75,5 +90,13 @@ errors, and cleans up on disconnect. Full usage: `adapters/element/README.md`.
|
|
|
75
90
|
REVIEW.md review report with human approval line
|
|
76
91
|
```
|
|
77
92
|
`manifest.json` records scene, type, format, locale, size, duration, style,
|
|
78
|
-
theme, an input hash
|
|
79
|
-
|
|
93
|
+
theme, an input hash, the source commit and `sourceDirty` (`true` when the
|
|
94
|
+
source file has uncommitted changes, so the frames match no commit; `null`
|
|
95
|
+
outside git), with no timestamps, so a re-render from the same inputs is
|
|
96
|
+
byte-identical and a stale export is easy to spot. Deliver from a clean
|
|
97
|
+
source (`sourceDirty: false`).
|
|
98
|
+
|
|
99
|
+
Re-exporting into the same folder replaces the previous export: files its
|
|
100
|
+
`manifest.json` listed that the new export does not write are deleted, so the
|
|
101
|
+
folder holds exactly what the new manifest lists. Files no export wrote are
|
|
102
|
+
left alone and named in a warning; keep notes and review files elsewhere.
|
|
@@ -2,17 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
| Name | viewBox | Typical use | Layout behaviour |
|
|
4
4
|
|---|---|---|---|
|
|
5
|
-
| `16:9` | 960×540 | slides, YouTube, web hero | sequence row (or 2-row snake when crowded); hub-spoke radial |
|
|
6
|
-
| `4:3` | 960×720 | older decks, docs | snake grid; radial |
|
|
7
|
-
| `1:1` | 720×720 | LinkedIn/Instagram feed | snake grid; radial |
|
|
8
|
-
| `9:16` | 540×960 | Reels/Shorts/TikTok, phone | column with labels right; hub-spoke tree |
|
|
9
|
-
| `wide` | 960×auto | web strip inside a page | row; height computed |
|
|
10
|
-
| `tall` | 360×auto | phone column on a page | column / tree; height computed |
|
|
5
|
+
| `16:9` | 960×540 | slides, YouTube, web hero | sequence row (or 2-row snake when crowded); hub-spoke radial; timeline horizontal axis |
|
|
6
|
+
| `4:3` | 960×720 | older decks, docs | snake grid; radial; horizontal axis |
|
|
7
|
+
| `1:1` | 720×720 | LinkedIn/Instagram feed | snake grid; radial; horizontal axis |
|
|
8
|
+
| `9:16` | 540×960 | Reels/Shorts/TikTok, phone | column with labels right; hub-spoke tree; timeline vertical axis |
|
|
9
|
+
| `wide` | 960×auto | web strip inside a page | row; horizontal axis; height computed |
|
|
10
|
+
| `tall` | 360×auto | phone column on a page | column / tree / vertical axis; height computed |
|
|
11
11
|
|
|
12
|
-
Fixed formats auto-fit text up to 22 px (sequence) / 20 px (hub-spoke) and
|
|
12
|
+
Fixed formats auto-fit text up to 22 px (sequence, timeline, stack) / 20 px (hub-spoke) and
|
|
13
13
|
step down to 14 px; strips max 16 px. A spec that cannot fit fails `check`
|
|
14
14
|
with a reason. Fix it with shorter labels, fewer nodes, or another format.
|
|
15
|
-
Never by cropping.
|
|
15
|
+
Never by cropping. A `stack` is one column of layers in every format.
|
|
16
16
|
|
|
17
17
|
Web pages: mount `wide` + `tall` and switch at the width where the wide
|
|
18
18
|
layout's text would fall below ~14 px on screen.
|
|
@@ -12,12 +12,23 @@ Same gate, same determinism as any diagram.
|
|
|
12
12
|
|
|
13
13
|
## Locate the toolkit
|
|
14
14
|
|
|
15
|
+
As in the animated-diagram skill: first `MOTION_KIT_HOME`, then the npm
|
|
16
|
+
package through `npx` (at the version of these skills), then the plugin copy.
|
|
17
|
+
`$MK` holds the template files (`brand/`, `styles/`); `mk` runs the CLI.
|
|
18
|
+
|
|
15
19
|
```bash
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
20
|
+
PLUGIN="$(cd -P "<this skill's base directory>" && cd ../.. && pwd -P)" # -P: the base may be a symlink to a clone
|
|
21
|
+
V="$(node -p "require(process.argv[1] + '/package.json').version" "$PLUGIN")"
|
|
22
|
+
if [ -n "${MOTION_KIT_HOME:-}" ]; then
|
|
23
|
+
MK="$MOTION_KIT_HOME"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
|
|
24
|
+
elif npx -y "@liqweed/motion-kit@$V" --help >/dev/null 2>&1; then
|
|
25
|
+
MK="$PLUGIN"; mk() { npx -y "@liqweed/motion-kit@$V" "$@"; }
|
|
26
|
+
else
|
|
27
|
+
MK="$PLUGIN"; mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
|
|
28
|
+
fi
|
|
19
29
|
```
|
|
20
|
-
Node ≥ 22. PNG needs `@resvg/resvg-js
|
|
30
|
+
Node ≥ 22. PNG needs `@resvg/resvg-js`: the `npx` route installs it; in
|
|
31
|
+
`$MOTION_KIT_HOME`, run `npm install`. The plugin copy alone renders SVG only.
|
|
21
32
|
|
|
22
33
|
## Workflow
|
|
23
34
|
|
package/styles/neutral.json
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"ink": "#111827",
|
|
10
10
|
"muted": "#4b5563",
|
|
11
11
|
"line": "#8b929c",
|
|
12
|
-
"accent": "#
|
|
12
|
+
"accent": "#1d36a8",
|
|
13
13
|
"onAccent": "#ffffff",
|
|
14
14
|
"emphasis": "#d97706"
|
|
15
15
|
},
|
|
@@ -21,6 +21,6 @@
|
|
|
21
21
|
"line": "#6b7280",
|
|
22
22
|
"accent": "#2563eb",
|
|
23
23
|
"onAccent": "#ffffff",
|
|
24
|
-
"emphasis": "#
|
|
24
|
+
"emphasis": "#fbbf24"
|
|
25
25
|
}
|
|
26
26
|
}
|