@liqweed/motion-kit 0.9.1 → 0.10.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.9.1"
10
+ "version": "0.10.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.9.1",
3
+ "version": "0.10.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",
@@ -30,6 +30,7 @@ import { fileURLToPath } from "node:url";
30
30
  import { parseArgs } from "node:util";
31
31
  import { bake, bakeStats } from "../runtime/bake.mjs";
32
32
  import { FORMATS } from "../runtime/scene.mjs";
33
+ import { checkContrast, sharedPairs } from "../runtime/style.mjs";
33
34
  import { SCENE_TYPES } from "../runtime/types/index.mjs";
34
35
  import { checkScene } from "../lib/check.mjs";
35
36
  import { checkFiles } from "../lib/gate.mjs";
@@ -79,6 +80,10 @@ function fail(msg) {
79
80
  console.error(`motion-kit: ${msg}`);
80
81
  process.exit(1);
81
82
  }
83
+ /** Contrast the scene does not draw but the style misses: said, never failed (G12). @param {string[]} warnings */
84
+ function warnAll(warnings) {
85
+ for (const w of warnings) console.error(`motion-kit: warning: contrast: ${w}`);
86
+ }
82
87
  function need(v, what) {
83
88
  if (!v) fail(`${cmd}: ${what} is required`);
84
89
  return v;
@@ -124,6 +129,11 @@ async function main() {
124
129
  const loaded = await loadScene(file, sopts);
125
130
  const r = checkScene(loaded.scene, { style });
126
131
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
132
+ warnAll(r.warnings);
133
+ // The page also paints the player: button text and borders, the selected step,
134
+ // captions, the focus outline, and (unless --no-heading) the heading on the canvas.
135
+ const player = checkContrast(style, sharedPairs(...(a["no-heading"] ? [] : ["ink/bg"]), "ink/surface", "onAccent/accent", "muted/bg", "emphasis/bg", "line/bg", "accent/bg"));
136
+ if (player.length) fail(`the player in the page fails the gate:\n - ${player.join("\n - ")}`);
127
137
  const html = buildHtml(loaded, { style, ...where, options: sopts.options, scrubber: !a["no-scrubber"], heading: !a["no-heading"] });
128
138
  if (/<\/script/i.test(html.slice(html.indexOf("<script>") + 8, html.lastIndexOf("</script>")))) fail("bundled code contains </script>");
129
139
  const out = need(a.out, "--out");
@@ -138,6 +148,7 @@ async function main() {
138
148
  const { scene } = await loadScene(file, sopts);
139
149
  const r = checkScene(scene, { style });
140
150
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
151
+ warnAll(r.warnings);
141
152
  if (a.png && !(await rasterizer())) fail("--png needs @resvg/resvg-js or Chrome");
142
153
  // The contact sheet's phone row shows the tall layout, as a phone does.
143
154
  /** @type {{ scene?: any, error?: string }} */
@@ -159,6 +170,7 @@ async function main() {
159
170
  const { scene } = await loadScene(file, await sceneOpts(file));
160
171
  const gate = checkScene(scene, { style });
161
172
  if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
173
+ warnAll(gate.warnings);
162
174
  const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
163
175
  const out = need(a.out, "--out");
164
176
  writeFileSync(out, svg);
@@ -171,6 +183,7 @@ async function main() {
171
183
  const { scene } = await loadScene(file, await sceneOpts(file));
172
184
  const gate = checkScene(scene, { style });
173
185
  if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
186
+ warnAll(gate.warnings);
174
187
  const out = need(a.out, "--out");
175
188
  const r = await renderVideo(scene, {
176
189
  out,
@@ -192,6 +205,7 @@ async function main() {
192
205
  const { scene } = await loadScene(file, await sceneOpts(file, { ...where, format: format ?? "1:1" }));
193
206
  const r = checkScene(scene, { style });
194
207
  if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
208
+ warnAll(r.warnings);
195
209
  const png = !a["no-png"];
196
210
  if (png && !(await rasterizer())) fail("icon PNG needs @resvg/resvg-js or Chrome (or pass --no-png)");
197
211
  const root = resolve(need(a.out, "--out"));
@@ -297,7 +311,7 @@ const VENDOR_CHECK = `#!/usr/bin/env node
297
311
  //
298
312
  // Every format unless --format; for a spec every locale its strings carry, for
299
313
  // a custom module its exported locales (default "en"), unless --locale. The style (neutral by default) must
300
- // pass the contrast check. --options passes scene options to custom modules:
314
+ // pass the contrast of the pairs each scene draws (G12). --options passes scene options to custom modules:
301
315
  // a .json file, inline JSON, or an .mjs module exporting ({ format, locale }) => options.
302
316
  // Exits 1 if anything fails; a file that cannot be loaded fails on its own.
303
317
  import { parseArgs } from "node:util";
@@ -38,7 +38,7 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
38
38
  | `steps` | `{at, label, detail?, id?}[]` | MUST | ≥ 1 step; `at` strictly increasing; `at ≤ duration` (+1e-9); every `label` non-empty; an `id`, if present, is a non-empty string unique within the scene [throws] (`validateScene`). The last step is the finished diagram. Page scripts address steps by `id` (§10.2); scene types copy a spec node's, hub's or spoke's `id`. |
39
39
  | `frame(t, ctx)` | `(number, {idPrefix}) → string` | MUST | Inner SVG markup at `t` (§2). `ctx.idPrefix` is unique to the rendered instance; every id the frame defines (clip paths, gradients, masks, markers, filters) MUST start with it, as `${idPrefix}-name` [gate] G14. A frame that defines no ids MAY ignore `ctx`. |
40
40
  | `stepLabelsInFrame` | boolean | MAY | `false` declares narrative steps whose labels are not drawn; exempts the scene from gate rule G10 (`lib/check.mjs:74`; used by `examples/custom-pulse.scene.mjs:137`, `brand/logo.scene.mjs:108`). |
41
- | `contrastPairs` | `{fg, bg, min, use?}[]` | MAY | Token pairs the scene draws beyond `CONTRAST_PAIRS` (§6); the gate checks the style against them in both themes [gate] G12 (`lib/check.mjs`, rule 8; used by `examples/custom-pulse.scene.mjs`). Tokens MUST be known and `min` in [1, 21]. |
41
+ | `contrastPairs` | `{fg, bg, min, use?}[]` | MAY | The token pairs the scene draws (§6). The gate holds the style to exactly these in both themes, and only warns about the shared pairs (`CONTRAST_PAIRS`) the list leaves out; a scene that declares none is held to every shared pair [gate] G12 (`lib/check.mjs`, `contrastReport`; used by `examples/custom-pulse.scene.mjs`; every registered scene type sets it). Tokens MUST be known and `min` in [1, 21]. |
42
42
  | `labelBoxes(t)` | `(number) → LabelBox[]` | MAY | The box of every label `frame(t)` draws, in the scene's own coordinates (`{id, x, y, width, height, stem?, opacity?}`; `labelAnchor` returns one, §4.9). Must be a function [throws]. The gate fails a scene whose labels overlap, whose stems cross a label or that leave the picture [gate] G15 (`lib/check.mjs`, rule 9; each box MUST be `{id, x, y, width, height}` with finite numbers [gate]; used by `examples/isometric-swivel.scene.mjs`). |
43
43
  | `type`, `format`, `locale` | string | MAY | Set by scene types; recorded in the export manifest (`lib/export.mjs:75-77`). |
44
44
 
@@ -312,21 +312,34 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
312
312
  literal (`runtime/scene.mjs:84`, `runtime/style.mjs:86-93`), because slide
313
313
  apps, rasterizers and image viewers ignore CSS variables; an unresolvable
314
314
  token throws.
315
- - **Contrast** (`runtime/style.mjs`, `checkContrast`, WCAG relative
316
- luminance): in both themes, every pair in `CONTRAST_PAIRS`, the token pairs
317
- the scene types and shared parts draw where the pair carries meaning in a
318
- step frame. Text ≥ 4.5:1 — `ink`/`muted` on `bg` and `surface`, `onAccent`
319
- on `accent`; shapes ≥ 3:1 — `line`, `accent`, `emphasis` on `bg`, and
320
- `emphasis` on `accent` (the ring marking the current node sits 3.5 units
321
- from the reached node it surrounds, and tells "here" from "reached" without
322
- hue). `CONTRAST_EXEMPT` lists, with a reason each, the pairs left out:
323
- `line` on `surface` (an outline is told from the canvas outside it),
324
- `accent` on `surface` and `emphasis` on `surface` and `accent` on `line`
325
- (only in motion), `onAccent` on `emphasis` (only the logo; logos are exempt
326
- from WCAG 1.4.11). A scene adds the pairs it draws besides through
327
- `contrastPairs` (§1). `motion-kit check` MUST fail when the selected style
328
- violates any shared pair, once per run, or a scene's own, per scene [gate]
329
- G12 (`lib/gate.mjs`). `neutral` MUST pass (`test/runtime.test.mjs`).
315
+ - **Contrast** (`runtime/style.mjs`, `checkContrast`, `contrastReport`, WCAG
316
+ relative luminance). WCAG judges what a scene draws, not a palette: text
317
+ needs 4.5:1 against what is behind it (1.4.3), the parts of a graphic that
318
+ carry meaning 3:1 against the colours adjacent to them (1.4.11). So the gate
319
+ holds a scene to the token pairs it draws, in both themes, and no others.
320
+ `CONTRAST_PAIRS` is the shared list of what the scene types and shared parts
321
+ draw where the pair carries meaning in a step frame: text ≥ 4.5:1 —
322
+ `ink`/`muted` on `bg` and `surface`, `onAccent` on `accent`; shapes ≥ 3:1 —
323
+ `line`, `accent`, `emphasis` on `bg`, and `emphasis` on `accent` (the ring
324
+ marking the current node sits 3.5 units from the reached node it surrounds,
325
+ and tells "here" from "reached" without hue). Each registered scene type
326
+ records which of them it draws (`contrastPairs` on its scenes,
327
+ `SCENE_TYPE_PAIRS` in `runtime/types/index.mjs`): a `hub-spoke` draws no text
328
+ on the canvas, a `sequence` draws no `ink` on `surface`.
329
+ A custom scene states what it draws in `contrastPairs` (§1; an empty list counts as none; `sharedPairs`
330
+ picks shared ones by name, others are written out). The pairs it declares
331
+ are the gate's problems; the shared pairs it leaves out are only warnings,
332
+ named with their ratio and threshold in both themes. A scene that declares
333
+ nothing is held to every shared pair, so no scene loses a check by saying
334
+ nothing. `CONTRAST_EXEMPT` lists, with a reason each, the pairs no scene
335
+ type draws or draws only in motion: `line` on `surface` (an outline is told
336
+ from the canvas outside it), `accent` on `surface` and `emphasis` on
337
+ `surface` and `accent` on `line` (only in motion), `onAccent` on `emphasis`
338
+ (only the logo; logos are exempt from WCAG 1.4.11). `motion-kit check` MUST
339
+ fail a scene whose style violates a pair it draws [gate] G12
340
+ (`lib/check.mjs`) and MUST report, once per run, every shared pair the style
341
+ misses with the scene types that draw it (`lib/gate.mjs`), without failing
342
+ on it. `neutral` MUST pass every shared pair (`test/runtime.test.mjs`).
330
343
  - motion-kit ships only `neutral` (`styles/neutral.json`); brand styles MUST
331
344
  live in the consumer repo.
332
345
 
@@ -592,8 +605,8 @@ that removes every listener, observer and mark they added.
592
605
  `motion-kit check` and the vendored `check.mjs` both run `checkFiles`
593
606
  (`lib/gate.mjs`): every file × format (all six unless `--format`, repeatable)
594
607
  × locale (`--locale`, repeatable; else every locale a spec's strings carry, and
595
- `en` for a module, §7), with `--options` for modules, plus the style contrast
596
- check. A file that cannot be read, parsed or built fails on its own and the
608
+ `en` for a module, §7), with `--options` for modules, plus the style contrast check of the pairs each scene draws and a once-per-run warning
609
+ for the shared pairs the style misses. A file that cannot be read, parsed or built fails on its own and the
597
610
  remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = unit tests +
598
611
  `check` over `examples/` and `brand/` (`package.json:15-18`).
599
612
 
@@ -610,7 +623,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
610
623
  | G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
611
624
  | G10 | Every word of every step label (escaped, trailing `/` stripped) appears in the final frame's text, unless `stepLabelsInFrame === false`. | `:72-77` | Step buttons and slides refer to things the viewer can see. Word-level, so it does not prove the label is contiguous. |
612
625
  | G11 | Every sampled frame MUST render the same bytes under two stubbed clocks as under the real one: `Date`, `performance.now`, `Temporal.Now` and `Math.random` fixed at 1970 and 0, then at 2100 and ≈ 1, the globals restored afterwards. `frame.toString()` MUST NOT contain `Date.now`, `new Date`, `Math.random`, `performance.now`, `Temporal.Now`. | `lib/check.mjs` (rules 1 and 6) | T1. The stubbed render catches reads in the helpers a frame calls; the source scan, code paths the samples miss. A reference taken before the check runs (`const D = Date` at import) escapes the stub. |
613
- | G12 | Style passes WCAG contrast in both themes for every pair in `CONTRAST_PAIRS` (once per run) and for each scene's `contrastPairs` (per scene). | `lib/gate.mjs`, `lib/check.mjs` (rule 8), `runtime/style.mjs` (`checkContrast`) | Legibility in light and dark, for the pairs actually drawn (§6). |
626
+ | G12 | The style passes WCAG contrast in both themes for each pair the scene draws: its `contrastPairs`, which the scene types set to the shared pairs they draw, else every pair in `CONTRAST_PAIRS`. Shared pairs it does not draw are warnings, never failures; the run reports every shared pair the style misses once. | `lib/check.mjs`, `lib/gate.mjs` (`styleWarnings`), `runtime/style.mjs` (`contrastReport`) | Legibility in light and dark, for the pairs actually drawn (WCAG 1.4.3 and 1.4.11 judge rendered content, §6). |
614
627
  | G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `lib/gate.mjs` | Reject, don't invent: a broken picture never renders. |
615
628
  | G14 | Rendered with two different `idPrefix` values, sampled frames share no `id`. | `lib/check.mjs` (rule 7) | Two instances on one page (wide and tall, or one diagram twice) must not share ids: `url(#x)` resolves to the first element with that id, and WCAG 2.1 SC 4.1.1 forbids duplicates. |
616
629
  | G15 | If the scene defines `labelBoxes`, at each sampled time and each step time: no two boxes with `opacity` > 0 are closer than 4 px, no stem crosses another box and every box lies inside the picture (`0, 0, width, height`). `labelBoxes` MUST return an array and not throw. Each problem is reported once, at its first time. | `lib/check.mjs` (rule 9), `runtime/iso.mjs` (`labelProblems`) | Labels placed in a projected view move with the camera; nothing else checks them against one another. Opacity 0 is not drawn, so a scene hides labels while the camera moves. |
@@ -634,6 +647,7 @@ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
634
647
  | 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. |
635
648
  | Vendored parity | CLI and vendored checks MUST call the same `lib/gate.mjs` and `lib/check.mjs`, including contrast, locales and caller options. |
636
649
  | 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. |
650
+ | Drawn pairs only | Recorded 2026-11-21 for [#72](https://github.com/liqweed/motion-kit/issues/72), after [#45](https://github.com/liqweed/motion-kit/issues/45) made every shared pair a failure for every scene. WCAG 1.4.3 and 1.4.11 judge what a scene draws against the colours next to it, so a pair that never meets in a scene is not a requirement for it: the gate fails the pairs a scene draws and warns about the other shared ones. Built-in types record the pairs they draw; a custom scene that declares `contrastPairs` is held to those, one that declares nothing to all shared pairs (no check is lost by saying nothing). `emphasis` on `accent` stays a failure for the types whose ring or dot touches the reached colour (`sequence`, `flowchart`, and the dots of `hub-spoke`, `stack` and the walks), though it rests on WCAG 1.4.1 and the shape already meets it, because the library's own call is to keep it. Thresholds and `neutral` are unchanged; detecting drawn pairs from the rendered SVG is left open. [#65](https://github.com/liqweed/motion-kit/issues/65) (logos) reuses the mechanism. |
637
651
 
638
652
  The controller also exposes `onStep(callback) → unsubscribe`, with an immediate
639
653
  current index and subsequent changed indices (`-1` before the first step).
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import { easeOut, easeStandard, progress, splitEdge, springTo } from "../runtime/motion.mjs";
10
10
  import { FORMATS, localize } from "../runtime/scene.mjs";
11
- import { tok } from "../runtime/style.mjs";
11
+ import { sharedPairs, tok } from "../runtime/style.mjs";
12
12
  import { cubic, drawOn, el, fade, num, text } from "../runtime/svg.mjs";
13
13
  import { wrapLabel } from "../runtime/wrap.mjs";
14
14
 
@@ -137,9 +137,14 @@ export default function make({ format = "16:9", locale = "en" } = {}) {
137
137
  // Steps here are events, not nodes: their labels live in the player's
138
138
  // step buttons and captions, not in the drawing.
139
139
  stepLabelsInFrame: false,
140
- // Beyond the pairs every scene draws: the progress bar's accent fill on
141
- // its surface track. The gate checks the style against it too.
142
- contrastPairs: [{ fg: "accent", bg: "surface", min: 3, use: "the progress bar's fill on its track" }],
140
+ // The pairs this scene draws, and the only ones the gate holds the style
141
+ // to (the shared pairs it leaves out, text on the canvas for one, are
142
+ // warnings): the shared ones its nodes, links and comet use, and the
143
+ // progress bar's accent fill on its surface track.
144
+ contrastPairs: [
145
+ ...sharedPairs("ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent"),
146
+ { fg: "accent", bg: "surface", min: 3, use: "the progress bar's fill on its track" },
147
+ ],
143
148
  steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
144
149
  frame,
145
150
  };
package/lib/check.mjs CHANGED
@@ -4,13 +4,13 @@
4
4
  * motion-kit · scene gate. Every scene, every format/locale it ships in, must
5
5
  * pass these before anything is exported or mounted.
6
6
  *
7
- * checkScene(scene, { style }) → { ok, problems: string[] }
7
+ * checkScene(scene, { style }) → { ok, problems: string[], warnings: string[] }
8
8
  *
9
9
  * Over files, formats and locales (the CLI and the vendored gate): lib/gate.mjs.
10
10
  */
11
11
  import { labelProblems } from "../runtime/iso.mjs";
12
12
  import { renderSvg, validateScene } from "../runtime/scene.mjs";
13
- import { checkContrast, normalizeStyle } from "../runtime/style.mjs";
13
+ import { contrastReport, normalizeStyle } from "../runtime/style.mjs";
14
14
 
15
15
  const SAMPLES = 120;
16
16
 
@@ -191,16 +191,20 @@ export const SETTLE_AFTER = Object.freeze([0.001, 0.015, 0.03, 0.045]);
191
191
  * Run the scene gate on one built scene.
192
192
  * @param {import("../runtime/scene.mjs").Scene} scene
193
193
  * @param {{ samples?: number, style?: any }} [options]
194
- * style: what the scene's own `contrastPairs` are checked against (neutral
195
- * if absent). The pairs every scene draws (CONTRAST_PAIRS) are a property of
196
- * the style alone, checked once per style by lib/gate.mjs.
197
- * @returns {{ ok: boolean, problems: string[] }}
194
+ * style: what the scene's pairs are checked against (neutral if absent): its
195
+ * own `contrastPairs` if it declares them, else all of CONTRAST_PAIRS. The
196
+ * shared pairs a declaring scene leaves out come back as `warnings`.
197
+ * @returns {{ ok: boolean, problems: string[], warnings: string[] }}
198
198
  */
199
199
  export function checkScene(scene, { samples = SAMPLES, style } = {}) {
200
200
  const problems = [];
201
201
  style = normalizeStyle(style);
202
- try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)] }; }
203
- for (const p of checkContrast(style)) problems.push(`contrast: ${p}`);
202
+ try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)], warnings: [] }; }
203
+ // The style against the pairs this scene draws (G12): all the shared ones
204
+ // unless it declares its own (`scene.contrastPairs`), which then stand in
205
+ // for them; the shared pairs it leaves out are only warnings.
206
+ const { problems: contrastProblems, warnings } = contrastReport(style, scene.contrastPairs);
207
+ for (const p of contrastProblems) problems.push(`contrast: ${p}`);
204
208
  const render = (/** @type {number} */ t) => renderSvg(scene, t, { style });
205
209
  const at = (/** @type {number} */ i) => (scene.duration * i) / samples;
206
210
 
@@ -284,11 +288,7 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
284
288
  }
285
289
  for (const id of fixed) problems.push(`fixed id "${id}": build ids from frame(t, { idPrefix }), e.g. \`\${idPrefix}-${id}\``);
286
290
 
287
- // 8. The token pairs this scene draws beyond the shared ones
288
- // (scene.contrastPairs) meet their contrast in the style, both themes.
289
- if (scene.contrastPairs !== undefined) {
290
- for (const p of checkContrast(style, scene.contrastPairs)) problems.push(`contrast: ${p}`);
291
- }
291
+ // 8. (Contrast, G12: checked first, above, by contrastReport.)
292
292
 
293
293
  // 9. Labels the scene declares (scene.labelBoxes): at the sampled times, each
294
294
  // step and the end, no two overlap, no stem crosses another label and none
@@ -322,5 +322,5 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
322
322
  }
323
323
  }
324
324
 
325
- return { ok: problems.length === 0, problems };
325
+ return { ok: problems.length === 0, problems, warnings };
326
326
  }
package/lib/gate.mjs CHANGED
@@ -6,18 +6,22 @@
6
6
  *
7
7
  * checkFiles(files, { formats, locales, style, options }) → number of failures
8
8
  *
9
- * - The style must pass the contrast check for the pairs every scene draws
10
- * (G12, CONTRAST_PAIRS), once.
11
9
  * - Every file × format (all of FORMATS unless given) × locale passes
12
- * checkScene, which also checks the style against the pairs that scene
13
- * declares it draws besides (`scene.contrastPairs`). Locales: the given ones; else, for a spec, every locale its
14
- * strings carry, and a module’s exported `locales` (default `en`).
10
+ * checkScene, which holds the style to the contrast pairs that scene draws
11
+ * (G12): the pairs its scene type draws, its own `contrastPairs`, or, if it
12
+ * declares none, all of CONTRAST_PAIRS. Locales: the given ones; else, for a
13
+ * spec, every locale its strings carry, and a module’s exported `locales`
14
+ * (default `en`).
15
+ * - The style's other shared pairs are reported once, as warnings, with the
16
+ * scene types they would fail: a style author sees every shared pair's
17
+ * result, and no scene fails on a pair it does not draw.
15
18
  * - A file that cannot be read, parsed or built is a failure for that file
16
19
  * only; the remaining files are still checked.
17
20
  */
18
21
  import { readFileSync } from "node:fs";
19
22
  import { FORMATS } from "../runtime/scene.mjs";
20
- import { checkContrast } from "../runtime/style.mjs";
23
+ import { CONTRAST_PAIRS, checkContrast } from "../runtime/style.mjs";
24
+ import { SCENE_TYPE_PAIRS } from "../runtime/types/index.mjs";
21
25
  import { checkScene } from "./check.mjs";
22
26
  import { isModule, loadScene, moduleLocales } from "./load.mjs";
23
27
 
@@ -45,17 +49,28 @@ export function detectLocales(spec) {
45
49
  return found.size ? [...found] : ["en"];
46
50
  }
47
51
 
52
+ /**
53
+ * Every shared contrast pair the style misses, each with who draws it: the
54
+ * scene types that fail on it, and any custom scene that declares no pairs of
55
+ * its own (it is held to all of them).
56
+ * @param {any} style
57
+ * @returns {string[]}
58
+ */
59
+ export function styleWarnings(style) {
60
+ return CONTRAST_PAIRS.flatMap((pair) => {
61
+ const types = Object.entries(SCENE_TYPE_PAIRS).filter(([, pairs]) => pairs.some((p) => p.fg === pair.fg && p.bg === pair.bg)).map(([t]) => t);
62
+ return checkContrast(style, [pair]).map((problem) => `${problem} (held against: ${[...types, "custom scenes that declare no or empty contrastPairs, or name this pair"].join(", ")}; a warning for any other scene)`);
63
+ });
64
+ }
65
+
48
66
  /**
49
67
  * @param {string[]} files specs (.json) and custom modules (.mjs)
50
- * @param {{ formats?: string[], locales?: string[], style?: any, options?: import("./load.mjs").OptionsSource, log?: (line: string) => void, error?: (line: string) => void }} [o]
68
+ * @param {{ formats?: string[], locales?: string[], style?: any, options?: import("./load.mjs").OptionsSource, log?: (line: string) => void, error?: (line: string) => void, warn?: (line: string) => void }} [o]
51
69
  * @returns {Promise<number>} failures (0 = the gate passes)
52
70
  */
53
- export async function checkFiles(files, { formats, locales, style, options, log = console.log, error = console.error } = {}) {
71
+ export async function checkFiles(files, { formats, locales, style, options, log = console.log, error = console.error, warn = console.warn } = {}) {
54
72
  let bad = 0;
55
- for (const p of checkContrast(style)) {
56
- bad++;
57
- error(`✗ style: ${p}`);
58
- }
73
+ for (const p of styleWarnings(style)) warn(`⚠ style: ${p}`);
59
74
  for (const file of files) {
60
75
  const module = isModule(file);
61
76
  let fileLocales = locales?.length ? locales : ["en"];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@liqweed/motion-kit",
3
- "version": "0.9.1",
3
+ "version": "0.10.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",
package/runtime/kit.mjs CHANGED
@@ -23,7 +23,7 @@
23
23
  */
24
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
- import { CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, cssVars, normalizeStyle, resolveTokens, tok } from "./style.mjs";
26
+ import { CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, contrastReport, cssVars, normalizeStyle, resolveTokens, sharedPairs, tok } from "./style.mjs";
27
27
  import { CAMERA_ISOMETRIC, CAMERA_PLAN, ISO_ELEVATION, box, camera, drawSolid, drawSolids, fitCamera, labelAnchor, labelProblems, lerpCamera, orderSolids, path3, prism, project, projector, regularPolygon, slab } from "./iso.mjs";
28
28
  import { attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, tokenPoints, tokensAlong, translate, trimSegment } from "./svg.mjs";
29
29
  import { estimateWidth, wrapLabel } from "./wrap.mjs";
@@ -37,7 +37,7 @@ import { estimateWidth, wrapLabel } from "./wrap.mjs";
37
37
  export const KIT = Object.freeze({
38
38
  ...{ DEFAULT_MOTION, ENTRANCE_MAX, SPRING_SETTLE_X, clamp01, cubicBezier, easeIn, easeOut, easeStandard, easings, lerp, linear, progress, splitEdge, springSettleTime, springStep, springTo, stagger, window01 },
39
39
  ...{ FORMATS, localize, renderSvg, safeId, stepIndex, stepIndexAt, stepTimes, validateScene, withId },
40
- ...{ CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, cssVars, normalizeStyle, resolveTokens, tok },
40
+ ...{ CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, contrastReport, cssVars, normalizeStyle, resolveTokens, sharedPairs, tok },
41
41
  ...{ attrString, cubic, dist, drawOn, el, esc, fade, num, pointOnLine, polyline, scaleAbout, text, tokenPoints, tokensAlong, translate, trimSegment },
42
42
  ...{ CAMERA_ISOMETRIC, CAMERA_PLAN, ISO_ELEVATION, box, camera, drawSolid, drawSolids, fitCamera, labelAnchor, labelProblems, lerpCamera, orderSolids, path3, prism, project, projector, regularPolygon, slab },
43
43
  ...{ estimateWidth, wrapLabel },
package/runtime/scene.mjs CHANGED
@@ -40,12 +40,14 @@ import { normalizeStyle, cssVars, resolveTokens } from "./style.mjs";
40
40
  */
41
41
  /**
42
42
  * An animated diagram as a pure function of time (see the module comment).
43
- * `contrastPairs`: token pairs the scene draws beyond CONTRAST_PAIRS
44
- * (runtime/style.mjs), which the gate checks the style against.
43
+ * `contrastPairs`: the token pairs the scene draws (runtime/style.mjs
44
+ * `sharedPairs` picks from CONTRAST_PAIRS; others are written out). The gate
45
+ * holds the style to exactly these and reports the shared pairs left out as
46
+ * warnings; a scene that declares none is held to all of CONTRAST_PAIRS.
45
47
  * `labelBoxes`: the box of every label `frame(t)` draws, in the picture's
46
48
  * coordinates (`labelAnchor` returns one); the gate fails a scene whose labels
47
49
  * overlap, whose stems cross a label, or that leave the picture (runtime/iso.mjs).
48
- * @typedef {{ id: string, width: number, height: number, duration: number, title: string, description: string, steps: Step[], frame: (t: number, ctx: FrameContext) => string, stepLabelsInFrame?: boolean, contrastPairs?: { fg: string, bg: string, min: number, use?: string }[], labelBoxes?: (t: number) => LabelBox[], type?: string, format?: string, locale?: string }} Scene
50
+ * @typedef {{ id: string, width: number, height: number, duration: number, title: string, description: string, steps: Step[], frame: (t: number, ctx: FrameContext) => string, stepLabelsInFrame?: boolean, contrastPairs?: readonly { fg: string, bg: string, min: number, use?: string }[], labelBoxes?: (t: number) => LabelBox[], type?: string, format?: string, locale?: string }} Scene
49
51
  */
50
52
 
51
53
  /** Formats: name → viewBox. Layouts are computed per format, never cropped. */
package/runtime/style.mjs CHANGED
@@ -163,10 +163,12 @@ export function contrast(a, b) {
163
163
  */
164
164
 
165
165
  /**
166
- * Every token pair the scene types and shared parts draw where the pair
167
- * carries meaning in a step frame (runtime/types/*, runtime/parts.mjs). A
168
- * scene that draws other pairs declares them in `scene.contrastPairs`; the
169
- * gate checks those too (lib/check.mjs).
166
+ * The shared list: every token pair the scene types and shared parts draw
167
+ * where the pair carries meaning in a step frame (runtime/types/*,
168
+ * runtime/parts.mjs), with the contrast WCAG asks of it. It is the menu the
169
+ * scene types pick from (`sharedPairs`), not what every scene must meet: a
170
+ * scene is held to the pairs it draws (`contrastReport`). A scene that
171
+ * declares nothing is held to all of them.
170
172
  * @type {readonly ContrastPair[]}
171
173
  */
172
174
  export const CONTRAST_PAIRS = Object.freeze([
@@ -177,14 +179,14 @@ export const CONTRAST_PAIRS = Object.freeze([
177
179
  { fg: "onAccent", bg: "accent", min: 4.5, use: "labels, glyphs and icons inside reached nodes (boxNode, circleNode)" },
178
180
  { fg: "line", bg: "bg", min: 3, use: "connectors and the outlines of pending nodes" },
179
181
  { fg: "accent", bg: "bg", min: 3, use: "reached nodes and drawn connectors" },
180
- { fg: "emphasis", bg: "bg", min: 3, use: "the emphasis ring (sequence) and dot (hub-spoke) on the canvas" },
182
+ { fg: "emphasis", bg: "bg", min: 3, use: "the emphasis ring (sequence, flowchart) and dot (hub-spoke, stack, walk) on the canvas, and the timeline's now pill" },
181
183
  {
182
184
  fg: "emphasis",
183
185
  bg: "accent",
184
186
  min: 3,
185
- use: "the emphasis ring around the reached node it marks (sequence): 3.5 units apart, so adjacent at phone size. It tells the current node from the reached ones without relying on hue",
187
+ use: "the emphasis ring around the reached node it marks (sequence, flowchart): 3.5 units apart, so adjacent at phone size. It tells the current node from the reached ones without relying on hue. The dot of hub-spoke, stack and walk rides over accent connectors",
186
188
  },
187
- ]);
189
+ ].map((p) => Object.freeze(p)));
188
190
 
189
191
  /**
190
192
  * Pairs that are drawn (by the scene types, only in motion; or by the
@@ -200,26 +202,89 @@ export const CONTRAST_EXEMPT = Object.freeze([
200
202
  ]);
201
203
 
202
204
  /**
203
- * WCAG contrast checks a style must pass, in both themes.
204
- * @param {any} style style data or "neutral"; normalizeStyle fills the rest
205
- * @param {readonly ContrastPair[]} [pairs] default CONTRAST_PAIRS; a scene's
206
- * own pairs (`scene.contrastPairs`) are checked with the same function
207
- * @returns {string[]} problems (empty = ok)
205
+ * Why a list of pairs cannot be checked (empty = it can).
206
+ * @param {string} name the style's name, for the message
207
+ * @param {unknown} pairs
208
+ * @returns {string[]}
208
209
  */
209
- export function checkContrast(style, pairs = CONTRAST_PAIRS) {
210
- const s = normalizeStyle(style);
211
- if (!Array.isArray(pairs)) return [`${s.name}: contrast pairs must be an array of { fg, bg, min }`];
210
+ function malformedPairs(name, pairs) {
211
+ if (!Array.isArray(pairs)) return [`${name}: contrast pairs must be an array of { fg, bg, min }`];
212
212
  const problems = [];
213
213
  for (const [i, p] of pairs.entries()) {
214
214
  const bad = !p || typeof p !== "object" ? "is not an object" : !TOKENS.includes(p.fg) ? `has unknown fg token "${p.fg}"` : !TOKENS.includes(p.bg) ? `has unknown bg token "${p.bg}"` : !(typeof p.min === "number" && p.min >= 1 && p.min <= 21) ? "needs a min contrast between 1 and 21" : "";
215
- if (bad) problems.push(`${s.name}: contrast pair ${i} ${bad}`);
215
+ if (bad) problems.push(`${name}: contrast pair ${i} ${bad}`);
216
216
  }
217
- if (problems.length) return problems;
218
- for (const theme of ["light", "dark"]) {
217
+ return problems;
218
+ }
219
+
220
+ /**
221
+ * Each pair a style does not reach, in both themes.
222
+ * @param {ReturnType<typeof normalizeStyle>} s
223
+ * @param {readonly ContrastPair[]} pairs well-formed
224
+ */
225
+ function misses(s, pairs) {
226
+ const out = [];
227
+ for (const theme of /** @type {const} */ (["light", "dark"])) {
219
228
  for (const { fg, bg, min } of pairs) {
220
- const r = contrast(s[theme][fg], s[theme][bg]);
221
- if (r < min) problems.push(`${s.name} ${theme}: ${fg} on ${bg} is ${r.toFixed(2)}:1, needs ${min}:1`);
229
+ const ratio = contrast(s[theme][fg], s[theme][bg]);
230
+ if (ratio < min) out.push({ theme, fg, bg, min, ratio });
222
231
  }
223
232
  }
224
- return problems;
233
+ return out;
234
+ }
235
+
236
+ /**
237
+ * WCAG contrast checks a style must pass, in both themes.
238
+ * @param {any} style style data or "neutral"; normalizeStyle fills the rest
239
+ * @param {readonly ContrastPair[]} [pairs] default CONTRAST_PAIRS; a scene's
240
+ * own pairs (`scene.contrastPairs`) are checked with the same function
241
+ * @returns {string[]} problems (empty = ok)
242
+ */
243
+ export function checkContrast(style, pairs = CONTRAST_PAIRS) {
244
+ const s = normalizeStyle(style);
245
+ const bad = malformedPairs(s.name, pairs);
246
+ if (bad.length) return bad;
247
+ return misses(s, pairs).map((m) => `${s.name} ${m.theme}: ${m.fg} on ${m.bg} is ${m.ratio.toFixed(2)}:1, needs ${m.min}:1`);
248
+ }
249
+
250
+ /**
251
+ * The shared pairs a scene type draws, picked from CONTRAST_PAIRS by their
252
+ * `fg/bg` names, in the order of that list. A scene type records them with
253
+ * the type (`contrastPairs` on its scenes) and a custom scene may do the same.
254
+ * @param {...string} names `"fg/bg"`, e.g. `"ink/bg"`; throws on one that CONTRAST_PAIRS does not hold
255
+ * @returns {readonly ContrastPair[]}
256
+ */
257
+ export function sharedPairs(...names) {
258
+ for (const n of names) if (!CONTRAST_PAIRS.some((p) => `${p.fg}/${p.bg}` === n)) throw new Error(`sharedPairs: "${n}" is not a shared pair (known: ${CONTRAST_PAIRS.map((p) => `${p.fg}/${p.bg}`).join(", ")})`);
259
+ return Object.freeze(CONTRAST_PAIRS.filter((p) => names.includes(`${p.fg}/${p.bg}`)));
260
+ }
261
+
262
+ /**
263
+ * What one scene owes the style, WCAG 1.4.3 and 1.4.11 applied to the pairs it
264
+ * draws. A scene that declares no pairs draws, for this purpose, all of
265
+ * CONTRAST_PAIRS: every miss is a problem. A scene that declares them
266
+ * (`scene.contrastPairs`) is held to those; the shared pairs it does not
267
+ * declare are only reported, as warnings, because WCAG judges what is drawn,
268
+ * not the palette.
269
+ * @param {any} style style data or "neutral"
270
+ * @param {readonly ContrastPair[]} [drawn] `scene.contrastPairs`
271
+ * @returns {{ problems: string[], warnings: string[] }}
272
+ */
273
+ export function contrastReport(style, drawn) {
274
+ const s = normalizeStyle(style);
275
+ // An empty list says nothing about what is drawn, which is no reason to drop every check.
276
+ if (drawn === undefined || (Array.isArray(drawn) && drawn.length === 0)) return { problems: checkContrast(s), warnings: [] };
277
+ if (!Array.isArray(drawn) || malformedPairs(s.name, drawn).length) return { problems: checkContrast(s, drawn), warnings: [] };
278
+ // A declaration may add pairs and name shared ones, never weaken a shared threshold.
279
+ // Contrast is symmetric, so a pair written the other way round is the same adjacency.
280
+ /** @param {ContrastPair} p @param {ContrastPair} d */
281
+ const same = (p, d) => (p.fg === d.fg && p.bg === d.bg) || (p.fg === d.bg && p.bg === d.fg);
282
+ drawn = drawn.map((d) => {
283
+ const shared = CONTRAST_PAIRS.find((p) => same(p, d));
284
+ return shared && d.min < shared.min ? { ...d, min: shared.min } : d;
285
+ });
286
+ const problems = checkContrast(s, drawn);
287
+ const undrawn = CONTRAST_PAIRS.filter((p) => !drawn.some((d) => same(p, d)));
288
+ const warnings = misses(s, undrawn).map((m) => `${s.name} ${m.theme}: ${m.fg} on ${m.bg} is ${m.ratio.toFixed(2)}:1, ${m.min}:1 recommended (this scene does not draw it)`);
289
+ return { problems, warnings };
225
290
  }
@@ -29,10 +29,17 @@
29
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
- import { NEUTRAL, tok } from "../style.mjs";
32
+ import { NEUTRAL, sharedPairs, tok } from "../style.mjs";
33
33
  import { drawOn, el, fade, num, polyline, text, translate } from "../svg.mjs";
34
34
  import { estimateWidth, wrapLabel } from "../wrap.mjs";
35
35
 
36
+ /**
37
+ * The shared contrast pairs this type draws: node labels, edge labels on the canvas, the emphasis ring on the canvas and around the reached node; no muted on surface.
38
+ * The gate holds its scenes to these and reports the other shared pairs as
39
+ * warnings (`contrastReport`, runtime/style.mjs).
40
+ */
41
+ export const contrastPairs = sharedPairs("ink/bg", "muted/bg", "ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent");
42
+
36
43
  export const FLOWCHART_SHAPES = ["box", "round", "pill", "decision"];
37
44
  export const FLOWCHART_DIRECTIONS = ["down", "up", "right", "left"];
38
45
 
@@ -398,6 +405,7 @@ export function flowchart(spec, { format = "16:9", locale = "en" } = {}) {
398
405
  title: localize(spec.title, locale),
399
406
  description: localize(spec.description, locale),
400
407
  steps: order.map((v, k) => withId({ at: stepAt(k), label: labels[v], detail: localize(nodes[v].detail, locale) }, nodes[v].id)),
408
+ contrastPairs,
401
409
  frame,
402
410
  };
403
411
  }
@@ -20,10 +20,17 @@
20
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
- import { NEUTRAL, tok } from "../style.mjs";
23
+ import { NEUTRAL, sharedPairs, tok } from "../style.mjs";
24
24
  import { drawOn, el, pointOnLine } from "../svg.mjs";
25
25
  import { wrapLabel } from "../wrap.mjs";
26
26
 
27
+ /**
28
+ * The shared contrast pairs this type draws: boxNode labels, connectors, the emphasis dot riding over them; no text on the canvas.
29
+ * The gate holds its scenes to these and reports the other shared pairs as
30
+ * warnings (`contrastReport`, runtime/style.mjs).
31
+ */
32
+ export const contrastPairs = sharedPairs("ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent");
33
+
27
34
  const ENTER = 0.4;
28
35
  const ENTER_GAP = 0.08;
29
36
  const FILL = 0.25;
@@ -213,6 +220,7 @@ export function hubSpoke(spec, { format = "16:9", locale = "en" } = {}) {
213
220
  withId({ at: HUB_ON + FILL, label: hubLabel, detail: localize(spec.hub.detail, locale) }, spec.hub.id),
214
221
  ...spokes.map((s, i) => withId({ at: stepAt(i), label: s.label, detail: s.detail }, spokesSpec[i].id)),
215
222
  ],
223
+ contrastPairs,
216
224
  frame,
217
225
  };
218
226
  }
@@ -9,13 +9,14 @@
9
9
  * here. A one-off diagram can skip the registry: write a module whose default
10
10
  * export is (opts) → scene (see examples/custom-*.scene.mjs).
11
11
  */
12
+ /** @import { ContrastPair } from "../style.mjs" */
12
13
  import { validateScene } from "../scene.mjs";
13
- import { flowchart } from "./flowchart.mjs";
14
- import { hubSpoke } from "./hub-spoke.mjs";
15
- import { sequence } from "./sequence.mjs";
16
- import { stack } from "./stack.mjs";
17
- import { walk } from "./walk.mjs";
18
- import { timeline } from "./timeline.mjs";
14
+ import { contrastPairs as flowchartPairs, flowchart } from "./flowchart.mjs";
15
+ import { contrastPairs as hubSpokePairs, hubSpoke } from "./hub-spoke.mjs";
16
+ import { contrastPairs as sequencePairs, sequence } from "./sequence.mjs";
17
+ import { contrastPairs as stackPairs, stack } from "./stack.mjs";
18
+ import { contrastPairs as walkPairs, walk } from "./walk.mjs";
19
+ import { contrastPairs as timelinePairs, timeline } from "./timeline.mjs";
19
20
 
20
21
  export const SCENE_TYPES = {
21
22
  sequence,
@@ -27,6 +28,23 @@ export const SCENE_TYPES = {
27
28
  flowchart,
28
29
  };
29
30
 
31
+ /**
32
+ * The shared contrast pairs (CONTRAST_PAIRS) each scene type draws: the pairs
33
+ * the gate holds a scene of that type to, and the only ones for which a style
34
+ * can fail it. Every scene a type builds carries the same list as
35
+ * `scene.contrastPairs`.
36
+ * @type {Readonly<Record<string, readonly ContrastPair[]>>}
37
+ */
38
+ export const SCENE_TYPE_PAIRS = Object.freeze({
39
+ sequence: sequencePairs,
40
+ "hub-spoke": hubSpokePairs,
41
+ timeline: timelinePairs,
42
+ stack: stackPairs,
43
+ "state-machine": walkPairs,
44
+ "request-journey": walkPairs,
45
+ flowchart: flowchartPairs,
46
+ });
47
+
30
48
  export function createScene(spec, opts = {}) {
31
49
  const make = SCENE_TYPES[spec.type];
32
50
  if (!make) throw new Error(`unknown scene type "${spec.type}" (known: ${Object.keys(SCENE_TYPES).join(", ")})`);
@@ -20,10 +20,17 @@
20
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
- import { NEUTRAL, tok } from "../style.mjs";
23
+ import { NEUTRAL, sharedPairs, tok } from "../style.mjs";
24
24
  import { drawOn, el, polyline, trimSegment } from "../svg.mjs";
25
25
  import { wrapLabel } from "../wrap.mjs";
26
26
 
27
+ /**
28
+ * The shared contrast pairs this type draws: labels on the canvas (stateLabel), circle glyphs, the emphasis ring on the canvas and around the reached node; no boxNode, so no ink on surface.
29
+ * The gate holds its scenes to these and reports the other shared pairs as
30
+ * warnings (`contrastReport`, runtime/style.mjs).
31
+ */
32
+ export const contrastPairs = sharedPairs("ink/bg", "muted/bg", "muted/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent");
33
+
27
34
  // Timeline (seconds). Steps are settled because PERIOD ≥ HOP + FILL.
28
35
  const ENTER_GAP = 0.1;
29
36
  const ENTER = 0.4;
@@ -199,6 +206,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
199
206
  title: localize(spec.title, locale),
200
207
  description: localize(spec.description, locale),
201
208
  steps: items.map((it, k) => withId({ at: stepAt(k), label: it.label, detail: it.detail }, nodes[k].id)),
209
+ contrastPairs,
202
210
  frame,
203
211
  };
204
212
  }
@@ -24,10 +24,17 @@
24
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
- import { NEUTRAL, tok } from "../style.mjs";
27
+ import { NEUTRAL, sharedPairs, tok } from "../style.mjs";
28
28
  import { drawOn, el, fade, num, text, translate } from "../svg.mjs";
29
29
  import { wrapLabel } from "../wrap.mjs";
30
30
 
31
+ /**
32
+ * The shared contrast pairs this type draws: layer labels, the rail and ticks, the packet dot over the accent rail; no text on the canvas.
33
+ * The gate holds its scenes to these and reports the other shared pairs as
34
+ * warnings (`contrastReport`, runtime/style.mjs).
35
+ */
36
+ export const contrastPairs = sharedPairs("ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent");
37
+
31
38
  /** @import { Scene } from "../scene.mjs" */
32
39
 
33
40
  // Timeline (seconds). Steps are settled because PERIOD ≥ HOP + FILL.
@@ -226,6 +233,7 @@ export function stack(spec, { format = "16:9", locale = "en" } = {}) {
226
233
  title: localize(spec.title, locale),
227
234
  description: localize(spec.description, locale),
228
235
  steps: order.map((li, k) => withId({ at: stepAt(k), label: labels[li], detail: localize(layers[li].detail, locale) }, layers[li].id)),
236
+ contrastPairs,
229
237
  frame,
230
238
  };
231
239
  }
@@ -26,10 +26,17 @@
26
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
- import { NEUTRAL, tok } from "../style.mjs";
29
+ import { NEUTRAL, sharedPairs, tok } from "../style.mjs";
30
30
  import { drawOn, el, fade, num, text, translate } from "../svg.mjs";
31
31
  import { wrapLabel } from "../wrap.mjs";
32
32
 
33
+ /**
34
+ * The shared contrast pairs this type draws: dates and labels on the canvas, dots and stems, the now pill (canvas fill) at the end of the accent axis; no text on surface or accent.
35
+ * The gate holds its scenes to these and reports the other shared pairs as
36
+ * warnings (`contrastReport`, runtime/style.mjs).
37
+ */
38
+ export const contrastPairs = sharedPairs("ink/bg", "muted/bg", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent");
39
+
33
40
  /** @import { Scene } from "../scene.mjs" */
34
41
 
35
42
  // Timeline (seconds). Each beat ends (step) before the next one starts.
@@ -405,6 +412,7 @@ export function timeline(spec, { format = "16:9", locale = "en" } = {}) {
405
412
  title: localize(spec.title, locale),
406
413
  description: localize(spec.description, locale),
407
414
  steps,
415
+ contrastPairs,
408
416
  frame,
409
417
  };
410
418
  }
@@ -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,
@@ -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
@@ -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.