@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/cli/motion-kit.mjs +15 -1
- package/docs/spec/technique.md +33 -19
- package/examples/custom-pulse.scene.mjs +9 -4
- package/lib/check.mjs +14 -14
- package/lib/gate.mjs +27 -12
- package/package.json +1 -1
- package/runtime/kit.mjs +2 -2
- package/runtime/scene.mjs +5 -3
- package/runtime/style.mjs +86 -21
- package/runtime/types/flowchart.mjs +9 -1
- package/runtime/types/hub-spoke.mjs +9 -1
- package/runtime/types/index.mjs +24 -6
- package/runtime/types/sequence.mjs +9 -1
- package/runtime/types/stack.mjs +9 -1
- package/runtime/types/timeline.mjs +9 -1
- package/runtime/types/walk.mjs +9 -1
- package/skills/animated-diagram/references/custom-scenes.md +8 -4
- package/skills/animated-diagram/references/styles.md +26 -7
- package/skills/motion-render/SKILL.md +1 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "motion-kit",
|
|
3
|
-
"version": "0.
|
|
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",
|
package/cli/motion-kit.mjs
CHANGED
|
@@ -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
|
|
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";
|
package/docs/spec/technique.md
CHANGED
|
@@ -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 |
|
|
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
|
|
316
|
-
luminance)
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
`
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
`line` on `
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
`
|
|
328
|
-
|
|
329
|
-
|
|
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
|
-
|
|
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 |
|
|
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
|
-
//
|
|
141
|
-
//
|
|
142
|
-
|
|
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 {
|
|
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
|
|
195
|
-
* if
|
|
196
|
-
*
|
|
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
|
-
|
|
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.
|
|
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
|
|
13
|
-
*
|
|
14
|
-
*
|
|
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
|
|
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
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
|
|
44
|
-
*
|
|
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
|
-
*
|
|
167
|
-
* carries meaning in a step frame (runtime/types/*,
|
|
168
|
-
*
|
|
169
|
-
*
|
|
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
|
-
*
|
|
204
|
-
* @param {
|
|
205
|
-
* @param {
|
|
206
|
-
*
|
|
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
|
-
|
|
210
|
-
|
|
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(`${
|
|
215
|
+
if (bad) problems.push(`${name}: contrast pair ${i} ${bad}`);
|
|
216
216
|
}
|
|
217
|
-
|
|
218
|
-
|
|
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
|
|
221
|
-
if (
|
|
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
|
|
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
|
}
|
package/runtime/types/index.mjs
CHANGED
|
@@ -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
|
}
|
package/runtime/types/stack.mjs
CHANGED
|
@@ -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
|
}
|
package/runtime/types/walk.mjs
CHANGED
|
@@ -6,10 +6,17 @@
|
|
|
6
6
|
import { progress, lerp, easings } from "../motion.mjs";
|
|
7
7
|
import { FONT_MIN, maxFontSize } from "../parts.mjs";
|
|
8
8
|
import { FORMATS, localize } from "../scene.mjs";
|
|
9
|
-
import { NEUTRAL, tok } from "../style.mjs";
|
|
9
|
+
import { NEUTRAL, sharedPairs, tok } from "../style.mjs";
|
|
10
10
|
import { el, fade, num, text } from "../svg.mjs";
|
|
11
11
|
import { wrapLabel } from "../wrap.mjs";
|
|
12
12
|
|
|
13
|
+
/**
|
|
14
|
+
* The shared contrast pairs this type draws: node labels, region labels on the canvas, edges, the dot over them; no ink on the canvas.
|
|
15
|
+
* The gate holds its scenes to these and reports the other shared pairs as
|
|
16
|
+
* warnings (`contrastReport`, runtime/style.mjs).
|
|
17
|
+
*/
|
|
18
|
+
export const contrastPairs = sharedPairs("muted/bg", "ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent");
|
|
19
|
+
|
|
13
20
|
/**
|
|
14
21
|
* Build the common graph walk used by state-machine and request-journey.
|
|
15
22
|
* Nodes are in reading order; connectors use separate outside lanes. The
|
|
@@ -156,6 +163,7 @@ export function walk(spec, { format = "16:9", locale = "en" } = {}) {
|
|
|
156
163
|
id: `${spec.id}-${format.replace(":", "x")}`, type: spec.type, format, locale,
|
|
157
164
|
width: W, height: L.H, duration, title: localize(spec.title, locale), description: localize(spec.description, locale),
|
|
158
165
|
stepLabelsInFrame: false,
|
|
166
|
+
contrastPairs,
|
|
159
167
|
steps: [{ id: "initial", at: firstAt, label: labels[visits[0]], detail: localize(nodes[visits[0]].detail, locale) },
|
|
160
168
|
...route.map((e, k) => ({ id: `visit-${k + 1}`, at: stepAt(k), label: localize(edges[e].label, locale), detail: localize(edges[e].detail, locale) || `${labels[visits[k]]} → ${labels[visits[k + 1]]}` }))],
|
|
161
169
|
frame,
|
|
@@ -32,10 +32,14 @@ Rules:
|
|
|
32
32
|
no module-level mutable state.
|
|
33
33
|
- Colours only via `tok()`; numbers in strings via `num()`. Named colours
|
|
34
34
|
(`"red"`) are literals too.
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
35
|
+
- Say which token pairs the scene draws: `contrastPairs`. The gate holds the
|
|
36
|
+
style to those pairs (WCAG 1.4.3, 1.4.11) and only warns about the shared
|
|
37
|
+
ones you leave out, so a brand palette is never failed on a pair the scene
|
|
38
|
+
never shows. `kit.sharedPairs("ink/bg", "accent/bg", …)` picks shared pairs by
|
|
39
|
+
name; write out others, such as
|
|
40
|
+
`{ fg: "accent", bg: "surface", min: 3, use: "bar on its track" }` (4.5 for
|
|
41
|
+
text, 3 for shapes; `references/styles.md`). A scene that declares none is
|
|
42
|
+
held to every shared pair, so declare what you draw.
|
|
39
43
|
- Use `fade()`/`el()` so invisible elements disappear; `drawOn()` for lines.
|
|
40
44
|
- Ids (clip paths, gradients, masks, markers, filters) MUST be built from
|
|
41
45
|
`idPrefix`, the second argument's field: `${idPrefix}-clip`, referenced as
|
|
@@ -65,10 +65,12 @@ unsettled, so it finishes in the first 95 % of each move and holds for the last
|
|
|
65
65
|
|
|
66
66
|
## Contrast
|
|
67
67
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
68
|
+
WCAG judges what a scene draws, not a palette: text needs 4.5:1 against what is
|
|
69
|
+
behind it (1.4.3), and the parts of a graphic that carry meaning need 3:1 against
|
|
70
|
+
the colours next to them (1.4.11). So `motion-kit check --style acme.json …`
|
|
71
|
+
**fails a scene only on the pairs it draws**, in both themes. The shared list
|
|
72
|
+
(`CONTRAST_PAIRS` in `runtime/style.mjs`) is every token pair the scene types
|
|
73
|
+
draw where the pair carries meaning in a step frame:
|
|
72
74
|
|
|
73
75
|
| Pair | Needs | Where it is drawn |
|
|
74
76
|
|---|---|---|
|
|
@@ -92,19 +94,36 @@ Exempt (`CONTRAST_EXEMPT`), each for a reason:
|
|
|
92
94
|
| accent on line | the accent draw-on covers the pending line; they meet only at the moving tip |
|
|
93
95
|
| onAccent on emphasis | no scene type draws it; the motion-kit logo does, and logos are exempt from WCAG 1.4.11 |
|
|
94
96
|
|
|
97
|
+
Each scene type draws some of these, not all (`SCENE_TYPE_PAIRS`): a `hub-spoke`
|
|
98
|
+
draws no text on the canvas, and a `sequence` draws no ink on surface.
|
|
99
|
+
A style that misses a pair is reported once per run, as `⚠ style:` with the
|
|
100
|
+
scene types that draw it, and fails exactly those scenes; every other scene
|
|
101
|
+
passes, and `build`, `export` and the rest print `warning: contrast:` for the
|
|
102
|
+
shared pairs they do not draw. `build` alone also fails a style that misses a pair the page's player paints (ink/surface, onAccent/accent, muted/bg, emphasis/bg, line/bg, accent/bg, and ink/bg for the heading unless `--no-heading`), declared or not. `neutral` meets every pair, so it never warns.
|
|
103
|
+
|
|
95
104
|
Emphasis on accent is the pair most palettes miss: two saturated colours of
|
|
96
105
|
the same lightness (blue and orange, teal and rust) are about 1:1 apart once
|
|
97
106
|
hue is gone. On a white canvas it usually means a dark accent (neutral light
|
|
98
107
|
uses `#1d36a8`) with a mid-tone emphasis; on a dark canvas, a light emphasis
|
|
99
108
|
(neutral dark uses `#fbbf24`).
|
|
100
109
|
|
|
101
|
-
A custom scene
|
|
102
|
-
|
|
110
|
+
A custom scene says what it draws with `contrastPairs`: the gate holds the style
|
|
111
|
+
to those pairs and only warns about the shared ones it leaves out. Shared pairs
|
|
112
|
+
come by name from `kit.sharedPairs`; others are written out. A scene that
|
|
113
|
+
declares nothing is held to every shared pair, as before, so say what you draw:
|
|
103
114
|
|
|
104
115
|
```js
|
|
105
|
-
return { …, contrastPairs: [
|
|
116
|
+
return { …, contrastPairs: [
|
|
117
|
+
...kit.sharedPairs("ink/surface", "onAccent/accent", "line/bg", "accent/bg"),
|
|
118
|
+
{ fg: "accent", bg: "surface", min: 3, use: "progress bar on its track" },
|
|
119
|
+
] };
|
|
106
120
|
```
|
|
107
121
|
|
|
122
|
+
A figure in ink on paper with a green accent that never draws `emphasis` lists
|
|
123
|
+
the pairs it does draw and passes with a palette whose `emphasis` cannot meet
|
|
124
|
+
both the canvas and the accent. Declare a pair only if it is drawn: a declared
|
|
125
|
+
pair is a failure, a threshold of 4.5 for text and 3 for graphics.
|
|
126
|
+
|
|
108
127
|
## Where style files live
|
|
109
128
|
|
|
110
129
|
In the **consuming repo**, next to its specs (e.g. `diagrams/style.json` in a
|
|
@@ -102,7 +102,7 @@ folder holds exactly what the new manifest lists. Files no export wrote are
|
|
|
102
102
|
left alone and named in a warning; keep notes and review files elsewhere.
|
|
103
103
|
|
|
104
104
|
The CLI gates `build`, `export`, `bake`, `video` and `icon` before writing
|
|
105
|
-
output, including
|
|
105
|
+
output, including the style contrast of the pairs the scene draws (a shared pair it does not draw is only a printed warning). `build` also holds the style to what the page's player paints, whatever the scene declares: ink/surface, onAccent/accent, muted/bg, emphasis/bg, line/bg, accent/bg, and ink/bg for the heading unless `--no-heading`; so `check` can pass where `build` fails. Exports
|
|
106
106
|
include `runtimeHash`, a SHA-256 of runtime module paths and bytes, in the
|
|
107
107
|
manifest and in `inputHash`, together with format, locale and render settings.
|
|
108
108
|
A changed runtime invalidates the hash even before its package version changes.
|