wiggle-that-diagram

wiggle-that-diagram : animation explicative en trois styles

Transformez une illustration statique « comment ça marche » en une animation courte, légendée et en boucle qui s'intègre dans un deck ou un rapport HTML, et proposez-la en trois formats afin que le lecteur puisse choisir. La méthode a été élaborée sur un vrai deck client (voir « Exemple concret »). Elle utilise huashu-art-motion pour la direction (listes de plans, règles de caméra, les six façons d'échouer) et, pour les styles A et B, comme moteur de rendu.

Quand l'utiliser, et quand ne pas l'utiliser

Utilisez-le quand :

• un deck ou un rapport HTML contient un schéma de mécanisme (flux de fichiers, vérifications de règles, une personne approuve) et que le lecteur doit voir ce qui se passe, étape par étape, avec des mots qu'il peut lire ;
• l'utilisateur souhaite des options dans des formats vraiment différents, et non pas trois variations de couleurs d'un même format ;
• une animation précédente était « trop rapide pour être lue » ou a besoin de légendes.

Ne l'utilisez pas pour : une micro-interaction unique (utilisez animate), une vidéo narrée avec voix off (utilisez huashu-art-motion directement), ou un graphique de nombres (utilisez dataviz).

Les trois styles (ils diffèrent par le format, pas par la palette)

	A · clip schéma	B · tableau blanc	C · SVG live
Image	Scène du moteur huashu, grammaire t1_3b1b, rendue en H.264 sans texte	Grammaire huashu y3_whiteboard, tableau sombre, le crayon dessine et écrit à la main (Kalam), vidéo carrée	Monde SVG inline filmé par une caméra virtuelle (viewBox animée par GSAP 3.12.5)
Mots sur l'image	Étiquettes HTML placées sur la vidéo à partir d'une piste de caméra exportée (toujours nettes)	Dessinés dans la vidéo (doivent être assez grands pour un téléphone)	Texte SVG réel (net, se réorganise en changeant les cadres de la caméra en fonction de la largeur)
Taille par film (exemple concret)	360–820 Ko (budget 900 Ko)	847–886 Ko (budget 900 Ko)	21–34 Ko (budget 40 Ko)
Rendu	un diagramme propre de style 3Blue1Brown	quelqu'un qui explique au tableau blanc	une animation de produit soignée
Risque principal	les étiquettes dérivent si la scène change sans nouveau rendu	budget de taille serré ; étiquettes téléphone 12–14 px	calculs de caméra fastidieux ; bizarreries de transformation GSAP

Les trois partagent UN SEUL script de légendes, les mêmes temps et le même contrat d'intégration, de sorte qu'un sélecteur de style montre la même histoire racontée de trois façons différentes.

La méthode, de bout en bout

Chaque étape se termine par la vérification qui prouve qu'elle est terminée.

1. Trouvez le mécanisme et un exemple concret. Lisez la page hôte (lecture seule). Choisissez le moment à montrer et UN exemple réel qui traverse chaque temps (une ligne, un enregistrement, un cas, avec ses valeurs réelles). Listez ce qui ne doit pas être inventé (identifiants, chiffres, images). → Vérification : vous pouvez dire chaque temps comme « cet objet fait ceci », avec un nom et un verbe.

2. Rédigez d'abord le script de légendes. Une phrase de légende par temps, 3–6 temps par film, dans beats.json (format : scripts/common/beats.example.json). Les légendes sont identiques dans tous les styles. Exécutez ensuite la porte de rythme et lisez le plancher qu'elle affiche :

   python3 ~/.claude/skills/wiggle-that-diagram/scripts/common/pace_check.py beats.json
   

   → Vérification : chaque temps est OK, et l'utilisateur a accepté les durées de boucle résultantes (ou des légendes plus courtes). Ne définissez jamais une cible de boucle séparément des légendes ; voir « Rythme ».

3. Rédigez le brief. Remplissez references/brief-template.md dans SPEC.md : commentaires cités, jetons, règle de rythme, script de légendes, temps, contrat d'intégration avec l'extrait textuel, budgets, livrables. → Vérification : un agent sans autre contexte pourrait construire à partir de celui-ci.

4. Tour d'orientations (facultatif, lorsque l'utilisateur n'a pas vu les styles). Trois agents en parallèle, un par style, chacun prototypant le MÊME moment d'un film (~8–12 s) et prenant des captures d'écran à 1280 et 390 px. Montrez les captures côte à côte ; l'utilisateur en choisit une ou les garde toutes. → Vérification : le choix de l'utilisateur est consigné par écrit.

5. Tour de construction. Un agent par style (chacun continuant son propre prototype), tous les films de ce style, écrivant uniquement sous <work>/<style>/final/. Briefs : references/agent-briefs.md. Indiquez le nombre d'agents et le niveau à l'utilisateur avant de lancer. → Vérification : chacun renvoie des fichiers, des captures, NOTES.md et une liste honnête des problèmes ouverts.

6. Recettes de construction (ce que chaque agent de style a réellement fait ; les scripts se trouvent dans scripts/style-a|b|c/) : Deux films neutres sont livrés dans les trois styles, chacun sous forme de beats.json plus style-a/, style-b/, style-c/ : examples/pizza/ (5 temps, simple) et examples/expenses/ (6 temps : cartes, raisons codées par couleur, flèches vers un deuxième et un troisième panneau). Commencez par le dossier de votre style.

   • A. cp -R ~/.claude/skills/huashu-art-motion/scripts/engine <A>/engine et touch <A>/engine/favicon.ico. Ajoutez engine/ways/way_make.js (depuis scripts/style-a/), exécutez beats_js.py beats.json --engine engine --var <VAR> (légendes et timing à partir du script partagé, jamais une copie manuelle), un fichier de scène engine/ways/<film>.js qui appelle WAY.make({poster, beats, camBase, cam, labels}) et enregistre SCENES['<film>'], et engine/eras_<film>.js définissant FILM_SIZE=[1280,720], PUNCH=0 (sinon le moteur ajoute un punch-in de 0.03 sur les transitions), SCENE_LIBS=['ways/way_make.js','ways/<film>_beats.js','ways/<film>.js'], SCENE_DIR='ways', ERAS=[{id:'<film>',dur:1}]. Ne dessinez AUCUN texte sur le canevas. Les assistants de dessin (boîtes arrondies, points, lignes, fondus, déplacements le long d'un chemin) sont écrits par film ; examples/pizza/style-a/pizza.js contient un petit ensemble à copier. Ensuite render_way.py <film> --scale 0.75 --crf 30 → build.py <film> --meta meta.json → pace_check.py work/<film>_data.json → test_embed.py final/<film>.html:<verdict beat> (ou tout à la fois : make.sh). Après toute modification de scène, re-rendez et exécutez midmove.py aux moments de mi-déplacement : les étiquettes doivent se trouver sur leurs objets.
   • B. Copiez le moteur de la même manière (avec le favicon.ico vide : sous un vrai Chrome, son 404 compte comme une erreur de page et render.py se termine par 1 après avoir écrit une bonne vidéo) et patchez render.py en chromium.launch(channel='chrome', …). Mettez kit.js dans engine/demos/_hb/, écrivez engine/demos/<film>/board.js (utilise HB.make(), ancre les événements à BEATS[k].t0 + offset) et engine/demos/<film>/eras.js (FILM_SIZE=[1080,1080], PUNCH=0, police Kalam, SCENE_LIBS=['demos/<film>/beats.js','demos/_hb/kit.js','demos/<film>/board.js']). Ensuite build_beats.py beats.json --engine engine → uv run --with playwright python engine/render.py --film demos/<film> --fps 30 --crf 12 --out work/<film>_master.mp4 → build_html.py <film> --beats beats.json (720², 24 ips, CRF le plus bas qui tienne) → test_contract.py final/<film>.html --beats beats.json. Chaque film se termine par un zoom arrière vers le tableau entier, une pause ≥ 1 s, puis un effacement ; le tableau vide est l'endroit où la boucle redémarre. Le still du dernier temps dans beats.json est partagé par tous les styles et doit atterrir avant le début de l'effacement, sinon l'affiche et l'image de mouvement réduit montrent un tableau à moitié effacé. Les objets qui bougent (une trottinette, une boîte) sont des éléments K.custom avec handed: false dont la position est fonction du temps ; donnez à chacun une heure de fin, sinon il reste sur le tableau après son travail.
   • C. Commencez par examples/pizza/style-c/ (SVG, timeline, thème). Écrivez src/<film>.svg (un `<svg id=