@liqweed/motion-kit 0.0.0-stage → 0.2.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.
Files changed (55) hide show
  1. package/.claude-plugin/marketplace.json +13 -0
  2. package/.claude-plugin/plugin.json +9 -0
  3. package/LICENSE +21 -0
  4. package/README.md +119 -2
  5. package/adapters/astro/AnimatedDiagram.astro +55 -0
  6. package/adapters/page/README.md +22 -0
  7. package/adapters/slidev/AnimatedDiagram.vue +137 -0
  8. package/brand/logo.scene.mjs +115 -0
  9. package/cli/motion-kit.mjs +239 -0
  10. package/docs/spec/technique.md +447 -0
  11. package/examples/agent-loop.json +18 -0
  12. package/examples/custom-pulse.scene.mjs +141 -0
  13. package/examples/integrations.json +20 -0
  14. package/examples/order-flow.json +17 -0
  15. package/examples/release-pipeline.json +17 -0
  16. package/examples/smart-home.json +17 -0
  17. package/lib/build.mjs +62 -0
  18. package/lib/bundle.mjs +68 -0
  19. package/lib/check.mjs +86 -0
  20. package/lib/export.mjs +113 -0
  21. package/lib/icon.mjs +41 -0
  22. package/lib/load.mjs +53 -0
  23. package/lib/raster.mjs +69 -0
  24. package/lib/video.mjs +77 -0
  25. package/package.json +69 -5
  26. package/runtime/bake.mjs +61 -0
  27. package/runtime/motion.mjs +154 -0
  28. package/runtime/parts.mjs +123 -0
  29. package/runtime/player.mjs +207 -0
  30. package/runtime/scene.mjs +101 -0
  31. package/runtime/style.mjs +142 -0
  32. package/runtime/svg.mjs +165 -0
  33. package/runtime/types/hub-spoke.mjs +215 -0
  34. package/runtime/types/index.mjs +25 -0
  35. package/runtime/types/sequence.mjs +201 -0
  36. package/runtime/wrap.mjs +44 -0
  37. package/skills/animated-diagram/SKILL.md +90 -0
  38. package/skills/animated-diagram/references/custom-scenes.md +56 -0
  39. package/skills/animated-diagram/references/ecosystem.md +28 -0
  40. package/skills/animated-diagram/references/interactivity.md +38 -0
  41. package/skills/animated-diagram/references/motion-vocabulary.md +70 -0
  42. package/skills/animated-diagram/references/qc.md +41 -0
  43. package/skills/animated-diagram/references/scene-types.md +59 -0
  44. package/skills/animated-diagram/references/styles.md +55 -0
  45. package/skills/animated-diagram/references/targets.md +27 -0
  46. package/skills/animated-diagram/references/technique.md +148 -0
  47. package/skills/motion-render/SKILL.md +68 -0
  48. package/skills/motion-render/references/formats.md +18 -0
  49. package/skills/motion-render/references/slides.md +18 -0
  50. package/skills/motion-render/references/video.md +61 -0
  51. package/skills/project-logo/SKILL.md +72 -0
  52. package/skills/project-logo/references/design.md +22 -0
  53. package/skills/project-logo/references/discovery.md +15 -0
  54. package/skills/project-logo/references/external-prompt.md +23 -0
  55. package/styles/neutral.json +26 -0
@@ -0,0 +1,55 @@
1
+ # Visual styles
2
+
3
+ **Neutral is the default.** Ask for a style during the brief; if none is given,
4
+ use neutral and say so.
5
+
6
+ ## Tokens (scenes may use only these)
7
+
8
+ | Token | Role |
9
+ |---|---|
10
+ | `bg` | canvas (exports with `--background`, video) |
11
+ | `surface` | pending node fill |
12
+ | `ink` | primary text |
13
+ | `muted` | secondary text, pending labels |
14
+ | `line` | pending strokes and connectors |
15
+ | `accent` | active/reached fill and paths |
16
+ | `onAccent` | text/glyphs on accent |
17
+ | `emphasis` | the one emphasis element (ring, dot) |
18
+
19
+ Scenes write `tok("accent")` → `var(--mk-accent)`. Live players set the custom
20
+ properties (light + dark); standalone exports resolve them to literals.
21
+
22
+ ## Style file
23
+
24
+ ```json
25
+ {
26
+ "name": "acme",
27
+ "font": "Inter, ui-sans-serif, system-ui, sans-serif",
28
+ "radius": 10,
29
+ "stroke": 2,
30
+ "light": { "accent": "#0b5fff", "emphasis": "#00a37a" },
31
+ "dark": { "accent": "#3d7eff", "emphasis": "#2fd3a0" }
32
+ }
33
+ ```
34
+
35
+ Missing tokens fall back to neutral. Colours must be `#rrggbb`. Unknown tokens
36
+ throw. `motion-kit check --style acme.json …` also checks contrast (WCAG):
37
+ text ≥ 4.5:1 (ink/muted on bg and surface, onAccent on accent), shapes ≥ 3:1
38
+ (line, accent, emphasis on bg), in both themes.
39
+
40
+ ## Where style files live
41
+
42
+ In the **consuming repo**, next to its specs (e.g. `diagrams/style.json` in a
43
+ deck or website repo). motion-kit itself ships only neutral.
44
+
45
+ ## "Describe one"
46
+
47
+ When the user describes a style ("calm, navy and teal, rounded"), write a style
48
+ file, run the contrast check, render one step frame in light and dark, and get a
49
+ yes before applying it everywhere.
50
+
51
+ ## Fonts
52
+
53
+ Live: the page's font stack. Exports: the rasterizer uses system fonts (resvg
54
+ falls back to Helvetica on macOS). For brand fonts in PNG/video, install the
55
+ font on the rendering machine. Embedding fonts in SVG is out of scope.
@@ -0,0 +1,27 @@
1
+ # Output targets
2
+
3
+ | Target | JS? | Use | Command |
4
+ |---|---|---|---|
5
+ | **Craft Page** (revisit / share) | yes, inline only; no network (`connect-src 'none'`) | interactive player | `build -o x.html` → `create_page` with the file content (read `~/.craft-agent/docs/pages.md` first) |
6
+ | **Craft in-chat preview** | **no** (`html-preview` iframe blocks scripts) | baked SVG, or step PNGs | `bake -o x.svg` → `image-preview`; or `export --png` → `image-preview` items |
7
+ | **Slidev** (stagewright, docomply-presentations) | yes | one step per click (component registers its own clicks; composes with `v-click`) | `vendor <deck>/components/motion-kit --adapter slidev` → `<AnimatedDiagram :spec="spec" />`; `maxHeight` (default 380px fits under a title) |
8
+ | **Marp / PowerPoint / Keynote** | no | one slide per step, same position; transition None/Dissolve/Morph | `export --png --scale 2` (Marp, Google Slides) or the SVGs (PowerPoint 365, Keynote) |
9
+ | **Website** (Astro, React, static) | yes | server-rendered final frame + player | `vendor <repo>/src/motion-kit --adapter astro`; wide + tall instances switched with CSS |
10
+ | **README / Obsidian / email / docs** | no | baked SVG (animated) or a GIF | `bake` (CSS animation inside SVG: works in browsers and GitHub `<img>`); `video -o x.gif` for email |
11
+ | **Video** (social, demos, talks) | n/a | MP4/WebM/GIF | `video -f 9:16 -o reel.mp4`; see motion-render |
12
+
13
+ ## Notes per target
14
+
15
+ - **Craft Pages** must be one standalone document; `build` output already is.
16
+ Don't write into `pages/<slug>/` directly. Use the page tools.
17
+ - **Baked SVG** costs size (fps × duration distinct frames, holds merged): a
18
+ 6 s scene at 15 fps is ~150–400 KB. Lower `--fps` (10–12) for READMEs.
19
+ - **Slides:** frames from one scene share a viewBox, so consecutive step slides
20
+ register exactly. Fonts in standalone SVG fall back to the viewer's system
21
+ font: send PNGs for decks that travel.
22
+ - **Websites:** pass serializable props (spec JSON) to islands; keep label
23
+ dictionaries out of client bundles; mount wide and tall, switch with CSS
24
+ (`display:none` also removes the hidden one from the a11y tree and its
25
+ autoplay observer).
26
+ - **Brand repos** keep their own style file next to their specs; motion-kit
27
+ ships only `neutral`.
@@ -0,0 +1,148 @@
1
+ # The technique: animation as a pure function of time
2
+
3
+ Origin: a production technique for code-driven motion design ("an automated
4
+ motion design system", X article by @e1genqq, Oct 2026, read via paraphrase),
5
+ first applied to live website diagrams and then generalized here. Numbers below
6
+ marked *derived* were worked out for motion-kit; the article gave none.
7
+
8
+ ## 1. The model
9
+
10
+ Write `frame(t)` that draws the **complete** picture for any time `t`, instead of
11
+ authoring a timeline and recording it. Consequences:
12
+
13
+ - **Random access.** Frame 600 renders without frames 0–599. A step button can
14
+ jump anywhere; an exporter writes exactly the frame a slide needs; a test can
15
+ sample any instant.
16
+ - **Editable.** Change a label, a timing or a colour and re-render: nothing is baked.
17
+ - **Repeatable.** The same `t` gives the same bytes, so tests, diffs, caching and
18
+ review all work.
19
+ - **One source, many outputs.** Live page, Slidev, SVG/PNG stills, baked SVG, video.
20
+
21
+ Video maps frame `f` at `fps` to `t = f / fps` (30 fps × 25 s = 750 frames).
22
+
23
+ ## 2. Determinism rules (enforced by `motion-kit check`)
24
+
25
+ 1. No dependence on previous frames.
26
+ 2. No uncontrolled randomness (derive variation from a seed and `t` if needed).
27
+ 3. No CSS transitions/animations or timers while rendering; the renderer owns time.
28
+ 4. No state that exists only because something happened earlier.
29
+ 5. Every visible property is computed from `t`.
30
+ 6. Same input, same bytes.
31
+ 7. Round every number. `el()` rounds numeric attributes; numbers you put in a
32
+ template string (`transform`, `points`, path `d`) must go through `num()`.
33
+ The gate rejects any number with 5+ decimals.
34
+ 8. No `Date`, `Math.random()`, `performance.now()` inside a scene.
35
+ 9. **Step frames are settled** (§4).
36
+ 10. Markup is balanced and escaped: labels cannot inject markup.
37
+ 11. Visibility decisions use rounded values: an element whose opacity rounds to
38
+ 0 is dropped, and an opacity that rounds to 1 is omitted, so frames that
39
+ look identical are byte-identical (`fade()`, `el()` do this).
40
+
41
+ ## 3. Authoring a timeline
42
+
43
+ Name the timing constants, derive every event from them:
44
+
45
+ ```js
46
+ const ENTER_GAP = 0.1; // stagger between siblings
47
+ const ENTER = 0.4; // one entrance (≤ 0.6)
48
+ const START = ENTER_GAP * (n - 1) + ENTER + 0.1; // after the last entrance
49
+ const FILL = 0.25; // a node turning accent
50
+ const HOP = 0.4; // emphasis travelling between nodes
51
+ const PERIOD = HOP + FILL + 0.05; // ≥ HOP + FILL → settled steps
52
+ const hopStart = (k) => FIRST_HOP + k * PERIOD;
53
+ const stepAt = (k) => fillStart(k) + FILL;
54
+ ```
55
+
56
+ Helpers (`runtime/motion.mjs`): `progress(t, start, dur, ease)` is eased 0..1,
57
+ holding 0 before and 1 after; a property is `lerp(a, b, progress(...))`.
58
+ Compose by multiplying progress values or by stacking layers, never by mutation.
59
+
60
+ Patterns:
61
+
62
+ - **Skeleton first, then fill.** Everything appears (pending style) so the whole
63
+ structure is visible, then the walk-through starts. Each step frame reads as
64
+ "you are here"; the viewer never holds an unseen future in mind.
65
+ - **Cross-fade states, don't interpolate colours.** Pending and active are two
66
+ layers with opacities `1 − p` and `p`. Scenes stay token-only.
67
+ - **Draw-on connectors.** `stroke-dasharray = L`, `dashoffset = L·(1 − p)`.
68
+ `drawOn()` returns null at `p ≤ 0`: a zero-length dash with round caps still
69
+ paints a dot.
70
+ - **One emphasis element** (ring, dot) carries the narrative; it is the only
71
+ thing in the emphasis colour.
72
+ - **Route connectors around text.** A snake-grid row turn is an elbow outside
73
+ the column, beyond the widest possible label, never a straight line through
74
+ the label below a node.
75
+
76
+ ## 4. Settled step frames
77
+
78
+ `steps[i].at` is when build step *i* is fully shown, and its frame is what a
79
+ slide shows. It must look intentional on its own: nothing mid-motion, no
80
+ half-drawn line pointing at nothing, no fading dot. Rule: **the next motion may
81
+ not start before `at`.** The gate asserts `frame(at − 1 ms) === frame(at)`.
82
+ Anything that fades out by a step (a travelling dot) must reach 0 by `at`.
83
+
84
+ ## 5. Layouts are computed per format
85
+
86
+ Never crop one master. Timings and the spec are shared; geometry is a function
87
+ of the format (`16:9`, `4:3`, `1:1`, `9:16`, `wide` strip, `tall` column):
88
+
89
+ - Row for wide aspects, snake grid for square-ish, column or tree for tall.
90
+ - **Auto-fit text:** try the largest font (fixed formats ≤ 22 px, strips ≤ 16 px)
91
+ and step down to 14 px until every label wraps into its budget; fail if even
92
+ 14 px doesn't fit. Never shrink below 14 px at 1×.
93
+ - **Collision checks:** nodes must not overlap or leave the canvas; the layout
94
+ throws instead of rendering a broken picture.
95
+ - **Web breakpoint:** switch wide → tall where the wide layout's text would drop
96
+ under ~14 px on screen (a 960-wide strip → switch at ~1024 px).
97
+
98
+ ## 6. Text
99
+
100
+ - SVG text does not wrap. Each layout has a character budget; `wrapLabel()`
101
+ breaks at spaces and after a slash, keeps a standalone "/" with the word
102
+ before it, and **throws** on an unbreakable word or too many lines.
103
+ - Dutch/German run ~30 % longer than English: check every locale shipped.
104
+ - Labels, not paragraphs. Sentences go in `detail` → the player's caption and
105
+ the screen-reader list.
106
+ - Copy comes from the approved source (the page's dictionary, the deck's text).
107
+ A diagram must not claim what the surrounding content doesn't.
108
+
109
+ ## 7. Validate before rendering (reject, don't invent)
110
+
111
+ Missing label → throw. Label too long → throw. Unknown token → throw. Layout
112
+ overlap → throw. Unknown scene type/format → throw. Claims are checked by a
113
+ human (no unmeasured numbers, "supports" rather than "guarantees").
114
+
115
+ ## 8. Architecture (the article's six components → motion-kit)
116
+
117
+ | Component | Job | motion-kit |
118
+ |---|---|---|
119
+ | Brief compiler | material → structured data, creative input separate from code | the spec JSON (+ style file) |
120
+ | Scene engine | data → animation | `runtime/types/*` (spec-driven), custom modules |
121
+ | Renderer | frame at timestamp | `renderSvg(scene, t, opts)` in Node and browser |
122
+ | Quality controller | find problems before delivery | `check`, contact sheet `--qc`, review checklist, human sign-off |
123
+ | Variant generator | formats × locales × hooks | `--format`, `--locale`, `--style`; one spec, many outputs |
124
+ | Delivery | package | `export` (SVG/PNG + manifest), `build`, `bake`, `video` |
125
+
126
+ ## 9. Lessons learned (each now a rule or a check)
127
+
128
+ 1. Unrounded numbers in template strings leaked 17 digits and made a "settled"
129
+ frame differ from 1 ms earlier → `num()`, decimal check.
130
+ 2. A connector started drawing 50 ms before its step → settled-step check,
131
+ `PERIOD ≥ HOP + FILL`.
132
+ 3. Zero-length dash + round caps = a stray dot → `drawOn()` returns null.
133
+ 4. Slash-separated labels left a leading space or a line starting with "/" →
134
+ `wrapLabel` rules.
135
+ 5. A badge collided with long Dutch labels → give labels the full width; test
136
+ every locale.
137
+ 6. Importing all dictionaries into a client island bloated the bundle → keep
138
+ label resolution server-side; pass serializable data (a spec, not a scene).
139
+ 7. `opacity` 0.9999 vs omitted made identical-looking frames differ → decide
140
+ visibility on rounded values.
141
+ 8. A straight row-turn connector crossed a label in a snake grid → elbow routing.
142
+ 9. A hub-spoke trunk drawn through boxes in a tall layout → tree layout with
143
+ the trunk outside the boxes.
144
+ 10. Headless-Chrome `--virtual-time-budget` doesn't advance the player's clock
145
+ faithfully (blank frame at t=0) → check playback in real time (`--timeout`,
146
+ DevTools protocol) or with `--force-prefers-reduced-motion` for the final frame.
147
+ 11. A dev server silently moved to another port and served a stale page → read
148
+ the printed URL.
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: motion-render
3
+ description: "Render motion-kit scenes (animated diagrams) to deliverables: slide-ready step frames (SVG/PNG, per-format, light/dark), a review contact sheet, zero-JS baked SVG, self-contained HTML for Craft Pages, and MP4/WebM/GIF video in 16:9, 1:1, 4:3 or 9:16, plus format × locale variant matrices. Use when asked to 'export the diagram', 'make slides from the animation', 'render a video / reel / GIF of the diagram', 'vertical version for social', or to package diagram outputs. To design or build the diagram itself use animated-diagram."
4
+ ---
5
+
6
+ # Motion render
7
+
8
+ All outputs come from the same pure scene, so they always agree. Locate the
9
+ toolkit as in the animated-diagram skill (`MK=$HOME/workspace/motion-kit`, else
10
+ the plugin root two levels above this skill). PNG and video need
11
+ `@resvg/resvg-js` (`npm install` in `$MK`) and `ffmpeg`.
12
+
13
+ ```bash
14
+ mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
15
+ ```
16
+
17
+ **Always run `mk check <scene>` first.** Exporters refuse scenes that fail the gate.
18
+
19
+ ## Slides
20
+
21
+ ```bash
22
+ mk export spec.json -o out/slides -f 16:9 -l nl --png --scale 2 [--background] [--theme dark] [--style brand.json]
23
+ ```
24
+ One `NN-<step>.svg` (+ `.png`) per build step, tokens resolved. Put one step
25
+ per slide at an identical position and size; transition None, Dissolve or
26
+ Morph. Details and per-app notes: `references/slides.md`.
27
+ Slidev decks: use the Slidev adapter instead (click-driven, live). See the
28
+ animated-diagram skill, `references/targets.md`.
29
+
30
+ ## Review sheet
31
+
32
+ ```bash
33
+ mk export spec.json -o out/review --png --qc
34
+ ```
35
+ `index.html` holds the steps, frames 0.2 s before and after each step, a phone-size row and the
36
+ review checklist. Fill in the review report (animated-diagram
37
+ `references/qc.md`) and get a human approval line before delivery.
38
+
39
+ ## Video
40
+
41
+ ```bash
42
+ mk video spec.json -f 9:16 -o out/reel.mp4 --fps 30 --scale 2 --hold 1.5 --sheet out/reel-sheet.png
43
+ mk video spec.json -f 16:9 -o out/demo.webm
44
+ mk video spec.json -f wide -o out/readme.gif --fps 15 --scale 1
45
+ ```
46
+ Formats, sizes, encoder settings, variant matrices and the HyperFrames handoff:
47
+ `references/video.md` and `references/formats.md`.
48
+
49
+ ## Other outputs
50
+
51
+ ```bash
52
+ mk build spec.json -o out/page.html -f wide # Craft Page / standalone interactive
53
+ mk bake spec.json -o out/diagram.svg -f wide --fps 12 # zero-JS animated SVG
54
+ ```
55
+
56
+ ## Delivery package
57
+
58
+ ```
59
+ <name>/
60
+ spec.json (+ style.json) source of truth: edit and re-render
61
+ slides/ NN-step.svg|png, manifest.json, index.html
62
+ video/ <name>-<format>.mp4, sheet.png
63
+ web/ <name>.html, <name>.svg (baked)
64
+ REVIEW.md review report with human approval line
65
+ ```
66
+ `manifest.json` records scene, type, format, locale, size, duration, style,
67
+ theme, an input hash and the source commit, with no timestamps, so a re-render
68
+ from the same inputs is byte-identical and a stale export is easy to spot.
@@ -0,0 +1,18 @@
1
+ # Formats
2
+
3
+ | Name | viewBox | Typical use | Layout behaviour |
4
+ |---|---|---|---|
5
+ | `16:9` | 960×540 | slides, YouTube, web hero | sequence row (or 2-row snake when crowded); hub-spoke radial |
6
+ | `4:3` | 960×720 | older decks, docs | snake grid; radial |
7
+ | `1:1` | 720×720 | LinkedIn/Instagram feed | snake grid; radial |
8
+ | `9:16` | 540×960 | Reels/Shorts/TikTok, phone | column with labels right; hub-spoke tree |
9
+ | `wide` | 960×auto | web strip inside a page | row; height computed |
10
+ | `tall` | 360×auto | phone column on a page | column / tree; height computed |
11
+
12
+ Fixed formats auto-fit text up to 22 px (sequence) / 20 px (hub-spoke) and
13
+ step down to 14 px; strips max 16 px. A spec that cannot fit fails `check`
14
+ with a reason. Fix it with shorter labels, fewer nodes, or another format.
15
+ Never by cropping.
16
+
17
+ Web pages: mount `wide` + `tall` and switch at the width where the wide
18
+ layout's text would fall below ~14 px on screen.
@@ -0,0 +1,18 @@
1
+ # Slides
2
+
3
+ | App | Use | Notes |
4
+ |---|---|---|
5
+ | **Slidev** | the Slidev adapter (live, one step per click) | `vendor <deck>/components/motion-kit --adapter slidev`; `<AnimatedDiagram :spec="spec" />` registers its own clicks; `slidev export --with-clicks` writes one settled frame per click (verified, Slidev 53) |
6
+ | **Marp** | `--png --scale 2` | `![bg contain](slides/03-step.png)`, one slide per step |
7
+ | **PowerPoint 365** | SVG (editable, sharp) or PNG | Same position and size on each slide; transition *Morph* or *None* |
8
+ | **Keynote** | SVG or PNG | Magic Move works when frames share a size and position |
9
+ | **Google Slides** | PNG only | No SVG support |
10
+
11
+ - Frames from one scene share a viewBox, so consecutive step slides register exactly.
12
+ - **Fonts:** standalone SVG uses the presenting machine's fonts. Send PNGs for
13
+ decks that travel.
14
+ - **Background:** transparent by default (sits on the slide theme). Use
15
+ `--background` for an opaque canvas in the style's `bg` colour.
16
+ - **Dark decks:** `--theme dark` resolves the dark tokens.
17
+ - Export at the deck's aspect (`-f 16:9` or `-f 4:3`); the layout is computed
18
+ for it, not cropped.
@@ -0,0 +1,61 @@
1
+ # Video
2
+
3
+ ## motion-kit's own pipeline (SVG scenes, silent)
4
+
5
+ ```
6
+ frame f → t = f/fps − lead → renderSvg(standalone, opaque bg) → PNG (resvg) → ffmpeg stdin
7
+ ```
8
+
9
+ - No browser, no per-frame files; identical consecutive frames are rasterized once.
10
+ - `--hold` (default 1.5 s) keeps the final frame readable; `lead` 0.25 s.
11
+ - Encoders: MP4 `libx264 -preset slow -crf 18 -pix_fmt yuv420p -movflags +faststart`
12
+ (even dimensions padded); WebM `libvpx-vp9 -crf 32`; GIF two-pass palette,
13
+ ≤ 20 fps, Bayer dither.
14
+ - Output summary prints probe data (size, duration, fps). `--sheet` writes a
15
+ 1 fps contact sheet (5 columns) for review.
16
+ - Determinism: same spec + style + settings → same frames. Encoder output is
17
+ stable on one machine/ffmpeg version; don't byte-compare across machines.
18
+
19
+ ## Sizes (scale 2)
20
+
21
+ | Format | Canvas | Video |
22
+ |---|---|---|
23
+ | 16:9 | 960×540 | 1920×1080 |
24
+ | 4:3 | 960×720 | 1920×1440 |
25
+ | 1:1 | 720×720 | 1440×1440 |
26
+ | 9:16 | 540×960 | 1080×1920 |
27
+
28
+ ## Variant matrix
29
+
30
+ A shell loop over scene × format × locale (× style) writes
31
+ `<scene>-<format>-<locale>.mp4`. Keep the matrix explicit and small: render
32
+ what will actually be published.
33
+
34
+ ```bash
35
+ for f in 16:9 1:1 9:16; do for l in en nl; do
36
+ mk video spec.json -f "$f" -l "$l" -o "out/$(basename spec .json)-${f/:/x}-$l.mp4"
37
+ done; done
38
+ ```
39
+
40
+ Marketing-style variants (hook A/B/C × CTA) are separate specs or spec fields.
41
+ Never generate claims for them.
42
+
43
+ ## When to hand off to HyperFrames
44
+
45
+ Use HyperFrames (Apache-2.0, HeyGen) when the video needs screen recordings,
46
+ images or footage, audio or voice-over synced to beats, captions, or multi-scene
47
+ edits longer than ~30 s.
48
+
49
+ - Install its skills in that repo only: `npx skills add heygen-com/hyperframes`
50
+ (or `claude plugin marketplace add heygen-com/hyperframes` →
51
+ `claude plugin install hyperframes@hyperframes`). Requires Node 22+ and FFmpeg.
52
+ - Two ways to bring a motion-kit diagram in:
53
+ 1. **As a clip:** render `mk video … -o diagram.webm` (or a PNG sequence) and
54
+ place it as a media element in the composition. Simplest and robust.
55
+ 2. **Live:** embed the `build` output and drive it through HyperFrames'
56
+ custom-runtime adapter, calling `window.__motionKit[id].seek(t)` per frame.
57
+ Verify the adapter API against the current HyperFrames docs first.
58
+ - Sync visual beats to audio by putting beat times in the spec and deriving the
59
+ timeline from them.
60
+
61
+ Remotion is the alternative for React-heavy teams. Check its company licence first.
@@ -0,0 +1,72 @@
1
+ ---
2
+ name: project-logo
3
+ description: "Design a project's logo / avatar / app icon as a motion-kit scene and write the icon set where tools discover it: assets/icon.png (Conductor), .idea/icon.svg (JetBrains IDEs), assets/icon.svg + an animated SVG for the README. Use when asked for 'a logo', 'an avatar', 'a repo icon', 'a project icon', 'an icon for Conductor / IntelliJ', or to refresh a project's mark. Also writes a prompt for an external vector generator (Quiver) when the user wants a second option."
4
+ ---
5
+
6
+ # Project logo
7
+
8
+ A logo here is a **square motion-kit scene whose final frame is the mark**.
9
+ That gives you, from one source file: a static SVG, a PNG at any size, a
10
+ light and dark variant, and an animated SVG intro that plays once and holds.
11
+ Same gate, same determinism as any diagram.
12
+
13
+ ## Locate the toolkit
14
+
15
+ ```bash
16
+ MK="$HOME/workspace/motion-kit" # canonical clone (has node_modules)
17
+ [ -d "$MK" ] || MK="$(cd "<this skill's base directory>/../.." && pwd)" # plugin copy
18
+ mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
19
+ ```
20
+ Node ≥ 22. PNG needs `@resvg/resvg-js` (`npm install` in `$MK`).
21
+
22
+ ## Workflow
23
+
24
+ 1. **Brief: one message, skip what's known.** Read the target repo's README
25
+ first and propose answers rather than asking blind:
26
+ - What the project *does*, in one line, and the single idea the mark
27
+ should carry (a mechanism, not a pun on the name).
28
+ - Existing brand colours? Otherwise derive a palette (below).
29
+ - Where it will show: GitHub avatar, IDE/Conductor sidebar, favicon,
30
+ README header. All of them are small: design for 32 px.
31
+ 2. **Concept: 2–3 options in words**, each one motif from the project's own
32
+ domain (the motion-kit mark is an easing curve between two keyframes,
33
+ because the project is about motion between states). Recommend one.
34
+ 3. **Build** `<repo>/brand/logo.scene.mjs`, starting from
35
+ `$MK/brand/logo.scene.mjs` (copy it; change the motif, keep the
36
+ structure). It has **no imports**: the CLI passes the runtime in as
37
+ `kit` (`export default ({ kit }) => …`), so the file works from any repo.
38
+ Rules for the mark: see `references/design.md`.
39
+ 4. **Style.** If the palette is not neutral's blue/amber, write
40
+ `<repo>/brand/style.json` (same shape as `$MK/styles/neutral.json`) and
41
+ pass `--style brand/style.json`. Colours stay tokens in the scene.
42
+ 5. **Gate + look.**
43
+ ```bash
44
+ mk check brand/logo.scene.mjs -f 1:1
45
+ mk export brand/logo.scene.mjs -f 1:1 -o out/logo --png --scale 1
46
+ ```
47
+ Open the PNG. Then judge it at 32 px and 16 px (render with
48
+ `mk icon … --size 32` into a scratch dir and look). Iterate on the scene,
49
+ not by editing SVG output.
50
+ 6. **Write the icon set into the repo:**
51
+ ```bash
52
+ mk icon brand/logo.scene.mjs -o <repo> [--size 512] [--style brand/style.json]
53
+ ```
54
+ Writes `assets/icon.svg`, `assets/icon.png`, `assets/icon-animated.svg`,
55
+ `.idea/icon.svg`, `.idea/icon_dark.svg`. Then check discovery
56
+ (`references/discovery.md`): a higher-priority file (e.g. a root
57
+ `favicon.svg`) wins in Conductor; a git-ignored `.idea/` needs
58
+ `!.idea/icon.svg` and `!.idea/icon_dark.svg` re-included.
59
+ 7. **Hand over:** show the PNG, list files written, and give the one manual
60
+ step tools don't read from the repo: the **GitHub avatar / social
61
+ preview** is uploaded in the repo or org settings (use `assets/icon.png`
62
+ at 512+; social preview is 1280×640).
63
+ 8. **Optional second opinion:** write a prompt for an external vector
64
+ generator (`references/external-prompt.md`) describing the *same* concept,
65
+ so the user can compare.
66
+
67
+ ## Don't
68
+
69
+ - Don't put the project name or letters in the mark; it's unreadable at
70
+ 16 px and duplicates the label every tool shows next to it.
71
+ - Don't use gradients, shadows or thin hairlines; they vanish when small.
72
+ - Don't recreate another product's logo or a well-known brand mark.
@@ -0,0 +1,22 @@
1
+ # Designing a mark that survives 16 px
2
+
3
+ - **Canvas:** 720×720 viewBox (`-f 1:1`). Tile inset ≈ 40, corner radius ≈
4
+ 0.25 × tile width (squircle feel). For a full-bleed avatar (GitHub crops
5
+ to a circle on some surfaces) set the inset to 0 and keep the motif inside
6
+ the central 70 %.
7
+ - **One motif, ≤ 3 shapes of note.** Strokes ≥ 4 % of the canvas (≥ 28 px at
8
+ 720) so they are ≥ 1 px at 32 px. Dots ≥ 10 % diameter.
9
+ - **Two colours + one accent:** tile = `accent`, motif = `onAccent`, a single
10
+ `emphasis` detail where the eye should land. Secondary detail at 0.5
11
+ opacity at most, and only if it still reads when removed.
12
+ - **Optical centre:** centre the motif's bounding box, then nudge up ~2 %.
13
+ - **Motion (the intro, 2–3.5 s):** tile settles (spring, ω ≈ 16), the motif
14
+ draws on (`drawOn` + `easeStandard`), one accent beat lands last
15
+ (`springTo` pop). The final frame is the logo and must hold. Same scene
16
+ rules as diagrams: tokens only, `num()` everything, no clock/randomness;
17
+ set `stepLabelsInFrame: false` and one step at `duration`.
18
+ - **Dark variant:** check `.idea/icon_dark.svg`. If `accent` is the same in
19
+ both themes, the tile carries the contrast; otherwise make sure the motif
20
+ still reads on the dark accent.
21
+ - **Review at three sizes:** 512 (detail), 64 (sidebar), 16–32 (tab/favicon).
22
+ If something only reads at 512, remove it.
@@ -0,0 +1,15 @@
1
+ # Where tools look for a project icon
2
+
3
+ `motion-kit icon` writes the files marked ✓.
4
+
5
+ | Tool | Path(s) | Format | Notes |
6
+ |------|---------|--------|-------|
7
+ | **Conductor** (conductor.build) | first match of: `public/apple-touch-icon.png`, `apple-touch-icon.png`, `public/favicon.svg`, `favicon.svg`, `public/favicon.png`, `public/icon.png`, `public/logo.png`, `favicon.png`, `app/icon.png`, `src/app/icon.png`, `public/favicon.ico`, `favicon.ico`, `app/favicon.ico`, `static/favicon.ico`, `src-tauri/icons/icon.png`, ✓ `assets/icon.png`, `src/assets/icon.png` | PNG / SVG / ICO | From Conductor's FAQ. An earlier match wins, so a web app's favicon beats `assets/icon.png`. Overridable per machine: right-click repo → *Change icon*. |
8
+ | **JetBrains IDEs** (IntelliJ, WebStorm, Rider…) | ✓ `.idea/icon.svg`, ✓ `.idea/icon_dark.svg` | SVG only | Shown on the Welcome screen / recent projects / project switcher. Set via Welcome screen → right-click → *Change Project Icon*, which writes `.idea/icon.svg`. The `_dark` variant follows JetBrains' icon convention; confirm in your IDE version. Commit by re-including it if `.idea/` is ignored. |
9
+ | **GitHub README** | ✓ `assets/icon-animated.svg`, ✓ `assets/icon.svg` | SVG | `<img src="assets/icon-animated.svg" width="112">`. The animation plays once in the README. |
10
+ | **GitHub avatar / social preview** | n/a | PNG | Not read from the repo: upload in Settings. Avatar from `assets/icon.png` (≥ 512); social preview 1280×640. |
11
+ | **Web app favicon** | `public/favicon.svg` | SVG | Not written by default: copy `assets/icon.svg` there if the project serves a site (Conductor will then prefer it). |
12
+ | **VS Code / Cursor** | n/a | | No per-project icon convention. |
13
+
14
+ Sources: https://www.conductor.build/docs/faq ·
15
+ https://www.jetbrains.com/help/idea/open-close-and-move-projects.html
@@ -0,0 +1,23 @@
1
+ # Prompt for an external vector generator (Quiver, etc.)
2
+
3
+ Fill the template from the chosen concept; keep it literal and geometric.
4
+ Generators drift towards gradients and extra detail, so forbid them.
5
+
6
+ ```text
7
+ Minimal flat vector app icon for "<project>", <one-line what it does>.
8
+ A rounded-square tile in solid <colour name> (<hex>). On it, <the motif,
9
+ described as shapes: "a single bold white S-shaped curve rising from the
10
+ bottom-left to the top-right, thick rounded caps">. <The accent detail:
11
+ "the end point is a solid amber (#D97706) dot with a white outline">.
12
+ <Optional secondary detail, semi-transparent>. Geometric, precise, generous
13
+ padding, no text, no gradients, no shadows, readable at 32 px. Clean SVG with
14
+ few paths.
15
+ ```
16
+
17
+ Variations to request: "tile edge-to-edge for a circular crop";
18
+ "monochrome, single colour on transparent".
19
+
20
+ To use a generated SVG instead: copy it to `assets/icon.svg` and
21
+ `.idea/icon.svg`, and rasterize `assets/icon.png` with any SVG rasterizer
22
+ (`rsvg-convert -w 512 -h 512`). It won't have the animated intro, the dark
23
+ variant or the gate's guarantees.
@@ -0,0 +1,26 @@
1
+ {
2
+ "name": "neutral",
3
+ "font": "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", \"Helvetica Neue\", Helvetica, Arial, sans-serif",
4
+ "radius": 10,
5
+ "stroke": 2,
6
+ "light": {
7
+ "bg": "#ffffff",
8
+ "surface": "#f3f4f6",
9
+ "ink": "#111827",
10
+ "muted": "#4b5563",
11
+ "line": "#8b929c",
12
+ "accent": "#2563eb",
13
+ "onAccent": "#ffffff",
14
+ "emphasis": "#d97706"
15
+ },
16
+ "dark": {
17
+ "bg": "#0f1115",
18
+ "surface": "#1c2029",
19
+ "ink": "#f3f4f6",
20
+ "muted": "#a7adb8",
21
+ "line": "#6b7280",
22
+ "accent": "#2563eb",
23
+ "onAccent": "#ffffff",
24
+ "emphasis": "#f59e0b"
25
+ }
26
+ }