@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.
@@ -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) and several tokens moving at once.
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 and several tokens at once |
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
- - Drawing a token pair the scene types don't (accent on surface, emphasis on
36
- onAccent)? Declare it so the gate checks the style against it:
37
- `contrastPairs: [{ fg: "accent", bg: "surface", min: 3, use: "bar on its track" }]`
38
- (4.5 for text, 3 for shapes; `references/styles.md`).
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
- `motion-kit check --style acme.json …` checks every token pair the scene types
69
- draw where the pair carries meaning in a step frame (`CONTRAST_PAIRS` in
70
- `runtime/style.mjs`), in both themes, at WCAG thresholds: 4.5:1 for text,
71
- 3:1 for shapes and strokes.
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 that draws another pair declares it, and the gate checks the
102
- style against it for that scene:
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: [{ fg: "accent", bg: "surface", min: 3, use: "progress bar on its track" }] };
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 shared style contrast and scene-specific pairs. Exports
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.