Shivraj97/site-motion

Que fait site-motion ?

Les scènes marquées Pro, ou nommées dans ces notes mais absentes de scenes/, sont des scènes site-motion Pro. Apprenez de ce que les notes disent à leur sujet ; construisez à partir des scènes qui sont ici (site-motion list).

Une scène est une fonction pure du temps. render(t) dessine la même image pour le même t, indépendamment de ce qui s'est passé avant. Cette seule règle explique pourquoi le même fichier peut être lu en direct sur un site web et rendu image par image en vidéo : l'exportateur se contente de chercher chaque temps d'image et de faire une capture d'écran.

Racine du dépôt : le dossier contenant ce fichier (installez-le avec git clone https://github.com/Shivraj97/site-motion ~/.claude/skills/site-motion, ou liez un clone à cet endroit). Node 22+, Chrome, ffmpeg. Pas d'installation npm. Depuis n'importe quel projet, exécutez la CLI par son chemin complet ; les builds et rendus atterrissent dans le dossier out/ de ce projet, et --tokens / --content prennent des chemins relatifs à celui-ci :

SM=~/.claude/skills/site-motion/bin/site-motion.mjs
node $SM init card-story --tokens ledger          # écrit ./brand.json (à partir du préréglage) et ./card-story.json à éditer
node $SM make card-story --tokens ./brand.json --content ./card-story.json --out public/motion/story.html

Pour intégrer une scène dans le code source du projet afin que l'équipe puisse la modifier, utilisez add au lieu de make. Il copie scene.js, scene.css, content.json et tokens.json dans public/motion/<scene>/ (ou motion/<scene>/ s'il n'y a pas de public/), les bibliothèques du lecteur et les bibliothèques fournisseurs dans runtime/, et écrit <scene>.html, une intégration en un seul fichier. Le dossier copié est une scène valide pour build, render et make :

node $SM add ledger-stamp --tokens ./brand.json --content ./ledger.json          # → public/motion/ledger-stamp/ + ledger-stamp.html
node $SM make public/motion/ledger-stamp --tokens public/motion/ledger-stamp/tokens.json --formats png,sheet

À l'intérieur du dépôt lui-même, la forme courte fonctionne :

node bin/site-motion.mjs list                                   # scènes et préréglages de jetons
node bin/site-motion.mjs make iso-blocks --tokens mint          # build + rendu mp4, webp, poster
node bin/site-motion.mjs make card-story --tokens ./brand.json --content ./my-story.json --formats mp4,webm,webp,gif,png,sheet
node bin/site-motion.mjs build window-stack --tokens night --out public/hero.html   # intégration en direct uniquement
node bin/site-motion.mjs render out/hero.html --formats mp4 --scale 2 --range loop        # exporter un build existant

Les sorties atterrissent dans out/<contenu>-<jetons>/. --range loop exporte uniquement la boucle sans couture (valeur par défaut pour GIF et WebP) ; full est l'introduction plus une boucle (valeur par défaut pour MP4 et WebM). sheet écrit une planche contact 4×3 : fabriquez-en toujours une et lisez-la.

Flux de travail

Un site entier (plusieurs sections ou pages) commence par un plan, pas par une scène. Exécutez node $SM plan dans le projet :

• avec --brief brief.md lorsque vous connaissez les sections. C'est la meilleure entrée. Rédigez le briefing à partir du texte réel du site :

  # Acme : ce que le produit fait, en une ligne
  ## accueil
  - hero : le titre principal
  - feature : l'en-tête de chaque section de fonctionnalité et une ligne en dessous
  ## tarifs
  - hero : …
  

• ou avec --url https://leur-site.com[,https://leur-site.com/tarifs] pour lire les en-têtes des pages en direct elles-mêmes ;
• ou avec --pages accueil,features,tarifs --about "…" lorsqu'il n'y a rien d'autre (choix génériques ; dites-le).

Il associe chaque section à une scène, chacune utilisée une fois, toutes dans le même style. Le style est celui du hero de la page d'accueil, verrouillé dans site-motion.json. Il dessine site-motion-plan.png : chaque section comme l'image de sa scène dans la marque et le style, avec le verdict du score en haut. Montrez à l'utilisateur la planche et obtenez son approbation avant plan apply.

• Un choix marqué ? n'avait pas de correspondance forte. Lisez sa note (« ledger-stamp convient mieux mais est sur l'accueil.hero ») et soit échangez (plan swap <slot> <scene>), réutilisez la meilleure scène, ou dites à l'utilisateur que la bibliothèque n'a pas encore de scène pour cette histoire.
• N'appliquez jamais un choix faible sans le dire.

plan apply ajoute chaque scène et imprime l'intégration de chaque section. Ensuite, écrivez le contenu de chaque scène dans son content.json, exécutez sync, et terminez par score --project.

Pour une seule scène, suivez les étapes ci-dessous.

1. Obtenez d'abord le système de design. Les jetons sont la seule source de couleur et de typographie. Trouvez-les dans l'ordre : le fichier de jetons/thème du projet (variables CSS, configuration Tailwind, tokens.json), puis le site en direct (mesurez les styles calculés), puis demandez. Écrivez-les sous la forme tokens/<marque>.json (forme ci-dessous). N'inventez jamais une couleur une fois la palette existante ; dérivez les nuances avec h.mix(a, b, p) à partir des jetons.
2. Choisissez l'archétype qui raconte l'histoire du produit, ou écrivez une nouvelle scène :

   Scène	Histoire qu'elle raconte	Rendu
   iso-blocks	infrastructure, plateformes, « plusieurs pièces qui fonctionnent ensemble » : blocs avec des données en direct sur leurs faces au-dessus d'un sol carrelé	SVG
   card-story	un flux de travail qui supprime du travail : une liste de fonctionnalités fait passer une carte produit par des états	DOM
   window-stack	« fonctionne là où vous travaillez » : fenêtres d'application sur un fond Canvas peint, un agent effectuant des étapes	Canvas + DOM
   live-room Pro	multijoueur : curseurs nommés sur une fenêtre d'application, une proposition, un vote qui passe, un changement livré, un ticker d'activité	Canvas + DOM
   leaderboard	crédit et classement : les contributions atterrissent sur des lignes, les points s'incrémentent, les lignes se réordonnent	DOM
   bloom-flow	automatisation : un événement traverse un graphe de flux de travail et chaque étape s'épanouit en fleurs génératives	Canvas + SVG
   signal-field	désordonné → structuré : des brins bruyants passent une porte et en ressortent en voies propres	p5.js
   drop-pile	plusieurs → un : des éléments de travail tombent dans un seul plateau avec une physique réaliste, un compteur les totalise	Matter.js (cuit)
   galton-router	routage, approbations, A/B : des paiements tombent à travers un tableau de clous ; une règle actionne un interrupteur et le flux se déplace vers les meilleures cases	SVG (marche aléatoire ensemencée)
   receipt-printer	désordonné → structuré : des documents entrent dans une fente, un reçu imprime chaque champ extrait avec sa confiance	DOM + SVG
   score-sheet	orchestration, multi-agent : une exécution écrite comme une partition musicale, des portées vibrent pendant que chaque agent travaille	SVG
   css3d-stack	architecture, couches : de vraies boîtes HTML en CSS 3D se soulèvent tandis qu'une demande tombe à travers	CSS 3D
   loom	plusieurs → un, intégrations : chaque outil est une bande de fils de chaîne tissés en un seul tissu sergé qui s'enroule sur la poutre du produit	Canvas 2D
   domino-run	automatisation, déclencheurs : une boule fait basculer une chaîne de dominos regroupés en étapes, chaque étape s'allume lorsque la vague l'atteint	Matter.js (cuit)
   weather-board	fiabilité, basculement : une tempête (nuages shader, pluie, éclairs) se forme au-dessus d'une région d'une carte de statut, le trafic est redirigé, elle se dissipe avec 0 requêtes échouées	Shader WebGL + DOM
   ledger-stamp	approbations, conformité, confiance : des paiements voyagent sur une courroie indexée devant un scanner de politique, une presse à tampon APPROUVÉ et une presse à signer et sceller dans une piste d'audit ; un au-dessus de la limite est tamponné EN ATTENTE et attend un second approbateur	SVG + DOM
   grain-tally	métriques, échelle : des milliers de grains (chacun un lot fixe d'événements réels) respirent comme un anneau de poussière, se déversent dans les chiffres du total, puis se trient en une barre par source avec son compte exact ; le nombre est construit à partir de ses données, pas compté	Canvas 2D (particules, t pur)
   lens-of-order	désordonné → structuré, classification, IA qui voit : un champ dithere 1-bit de gouttes dérivantes (pas encore comprises) ; une loupe remplit chaque goutte dans sa couleur de classe, la contourne et l'étiquette avec une confiance, laissant une traînée colorée qui s'estompe	Canvas 2D (champ par cellule, dither de Bayer)
   water-slide-funnel	entonnoir de conversion : les cavaliers glissent sur une rampe par étape ; le bassin de chaque lèvre capture les abandons de cette étape	SVG
   gold-pan Pro	recherche en cours de frappe : chaque frappe fait tourbillonner la batée jusqu'à ce qu'il reste trois pépites cotées	Canvas 2D
   museum-heatmap Pro	analytique produit : les empreintes des visiteurs réchauffent le sol autour des fonctionnalités où les gens s'arrêtent ; le classement vient de la chaleur	Canvas 2D
   cell-division	branchement de base de données : la branche principale se divise en branches, une est abandonnée, une fusionne avec son changement	Canvas 2D (metaballs)
   scratch-off Pro	prédiction : le film à gratter révèle l'heure de départ réelle avant que le tableau de la compagnie aérienne ne rattrape	Canvas 2D
   sieve-tray Pro	détection précoce : des marqueurs tombent à travers un filet fin ; les rares qui s'accrochent sont soulevés et signalés	Matter.js (cuit)
   rube-goldberg Pro	avant / après : une bille de reçu se coince dans cinq vieux engins, puis tombe dans une goulotte dans une seconde	SVG
   language-balloons Pro	localisation : des bulles de mots dans huit écritures flottent et assemblent la phrase de chaque locale, RTL inclus	Matter.js (cuit)
   balloon-deploy Pro	déploiements : chaque étape de build gonfle l'enveloppe ; à 100 %, le lancement décolle	SVG
   pufferfish Pro	mise à l'échelle automatique : un poisson-globe gonfle pour correspondre à chaque vague de trafic tandis qu'un poisson à capacité fixe est ballotté	SVG
   gear-tiers Pro	tarifs : forfaits dessinés comme un kit de camping, de la tente au camp de base, avec un basculement mensuel / annuel	SVG
   permission-chessboard Pro	rôles et permissions : chaque pièce de rôle atterrit sur le plateau et n'allume que les cases qu'elle peut utiliser	SVG
   tree-rings	bilan de l'année : un anneau par année, aussi large que l'année a été chargée, avec des encoches pour les premières fois	SVG
   parchment-changelog	journal des modifications : un parchemin se déroule une version à la fois, chacune encrée au moment de sa livraison	SVG + DOM
   moving-boxes	migration : un diable transporte chaque boîte d'ancien outil dans le nouveau bâtiment, rien n'est perdu	SVG + DOM
   privacy-pebbles Pro	masquage PII : une raclette transforme chaque détail personnel en un galet identique ; la phrase se lit toujours	SVG + DOM
   ant-trail Pro	catégorisation automatique : des fourmis transportent le reçu, le mémo et l'approbation de chaque glissement vers la bonne fente du grand livre	Canvas 2D
   sunrise-payroll Pro	paie mondiale : un soleil levant traverse huit fuseaux horaires et paie chaque ville à 9 heures du matin locale	SVG
   whiteout Pro	calme : un tableau de bord chargé se dissout dans le brouillard, ne laissant que le chiffre qui compte	Shader WebGL + DOM
   ink-flood Pro	personnalisation, marque blanche : un échantillon de peinture inonde tout le produit d'une nouvelle gamme de couleurs	SVG
   integration-deck Pro	intégrations : chaque outil est une touche sur un pavé numérique isométrique ; un flux de travail joue comme un accord tandis qu'un journal d'exécution tape chaque étape	Three.js
   margin-rails Pro	provenance : un mémo s'écrit tout seul tandis que des passages reportés de fichiers précédents glissent sur des rails nommant leur source	SVG + DOM
   pigeonhole-wall	mémoire : des documents déposent dans des casiers étiquetés, et une requête extrait les trois sources dont elle a besoin	SVG + DOM
   redline-front Pro	révision de contrat : un front de révision balaie le document et le renvoie sous forme de révision finalisée avec des autorités vérifiées	SVG + DOM
   step-rail	comment ça marche, intégration : un jeton parcourt des étapes numérotées ; chaque carte s'ouvre sur ce que son étape a produit et la dernière atterrit sur le résultat	SVG + DOM
   pipeline-board	flux de travail, pipeline : des cartes avancent colonne par colonne sur un tableau kanban tandis que les comptes et les totaux les suivent	DOM
   account-health	rétention, réussite client : une table de santé rejoue le mois ; un compte glisse en risque, un plan d'action se déclenche et il récupère	SVG
   split-wipe	avant / après, consolidation : un séparateur balaie le travail manuel dispersé et chaque fragment s'emboîte dans une seule surface produit	DOM
   roadmap-rail	feuille de route, jalons : un marqueur Aujourd'hui parcourt l'axe temporel ; les jalons livrés se remplissent et le lancement clé s'ouvre dans une carte	SVG
   trust-rings	sécurité, conformité : les requêtes traversent des anneaux de contrôle concentriques autour des données ; la requête non autorisée est arrêtée et journalisée	SVG
   balance-scale	tarifs, qualité vs coût : trois plateaux de balance, chaque inclinaison calculée à partir des scores ; le nôtre penche vers la qualité	SVG
   crate-discrepancy	réconciliation : des plateaux sortent d'une caisse et cochent le bordereau d'emballage ; le plateau manquant flotte avec sa note	SVG + DOM
   press-qa	tests, CI : des builds roulent hors d'une presse ; un bras éjecte celui avec un test échoué dans une goulotte et il passe lors de la réexécution	SVG
   radar-sweep	observabilité : chaque travail en cours est un point sur un écran radar ; un curseur atteint et met en pause celui qui échoue	Canvas 2D + DOM
   agent-checkout	démo UI produit, paiements par agent : une demande d'achat, une carte virtuelle masquée se remplit automatiquement, le compteur de limite bouge du montant, le reçu rejoint la liste	DOM + ui-kit
   click-to-done	démo UI produit, toute fonctionnalité en une action (inviter, envoyer, approuver, publier) : un écran réel dans un cadre de navigateur, le curseur tape, choisit et clique, la caméra se rapproche et recule sur le résultat	DOM + ui-kit
   dashboard-push	démo UI produit, analytique et rapports : le chiffre clé se construit à partir du graphique pendant qu'il se dessine, le curseur gratte une infobulle, la caméra se concentre sur le moment important, un commutateur de plage transforme chaque série	DOM + SVG + ui-kit
   phone-stack	démo UI produit, mobile et notifications : des alertes atterrissent sur un écran de verrouillage avec un anneau de signal chacune, une tape ouvre la plus récente dans l'écran de l'application, un balayage vers la maison l'efface	DOM + ui-kit
   shot-demo	démo UI produit à partir d'une capture d'écran : la propre capture d'écran du client dans un cadre ; le curseur tape dans ses vrais champs et clique sur son vrai bouton, les valeurs changent dans la face de la marque, un projecteur et une annotation atterrissent sur le résultat	DOM + capture d'écran + ui-kit

integration-deck est le standard 3D : un objet tactile, une action physique, des bandes plates de style cartoon, un contour à l'encre, une vraie caméra isométrique et des étiquettes dans la typographie de la marque. Les autres scènes d'objets Three.js (un hub orbital, un mur de tri, un logo extrudé, une vitrine glTF) vivent en dehors de l'ensemble public jusqu'à ce qu'elles soient retravaillées ; les outils 3D (vendor/three-full.min.js, vendor/three-selected-deps.js) sont présents mais bannis de la configuration par défaut car ils ajoutent 1,2 Mo au bundle. Activez-les avec --renderers three ou dans le manifeste de la scène. Les scènes Three.js chargent toujours three-full.min.js et leurs propres assets ; ne dupliquez pas le loader.

La bibliothèque de scènes vit dans scenes/. Chaque scène est un dossier avec au moins un scene.js qui exporte une fonction scene(ctx). Le décorateur de scène h (implicite dans le contexte : const { h, … } = ctx) fournit des helpers pour les couleurs (h.mix(a, b, p)), le timing (h.ease(t, type)), les formes (h.rect, h.circle, h.polygon) et le rendu (h.renderer === 'svg', 'canvas', 'dom', 'webgl', 'three'). Voir docs/decorator-api.md pour l'API complète.

Le pipeline de build traite chaque scène en quatre phases : charpentage (configurer le DOM et rendre la scène immobile), préparation (lire les jetons et le contenu), construction (appeler scene() avec le contexte assemblé) et sortie (sérialiser le résultat). Les scènes DOM et SVG sont sérialisées en HTML/XML, les scènes Canvas sont pipées via Puppeteer pour des captures d'écran, et les scènes Three.js sont rendues dans un canevas WebGL. Le pipeline de rendu est orchestré par bin/pipeline.mjs et peut être étendu avec des plug-ins personnalisés.

Pour créer une nouvelle scène, copiez une scène existante, ou utilisez node $SM scaffold <nom> qui génère un dossier squelette avec scene.js, scene.css, content.json et tokens.json.

L'outil inclut un système de jetons qui garantit que toutes les couleurs, typographies et espacements proviennent d'une seule source de vérité. Les jetons sont chargés automatiquement depuis tokens.json dans le dossier de la scène ou depuis un fichier spécifié via --tokens. Le format attendu est :

{
  "colors": {
    "primary": "#3b82f6",
    "secondary": "#8b5cf6",
    "background": "#0f172a",
    "text": "#e2e8f0",
    "accent": "#f59e0b"
  },
  "typography": { "fontFamily": "InterVariable, sans-serif" },
  "spacing": { "base": 4 }
}

Les préréglages de jetons intégrés sont mint, night, sand, coral, solar, azure, flame, clay, glass, ink et ledger. Consultez tokens/ pour leurs valeurs.

Le moteur de scoring évalue une scène selon la couverture des jetons, la performance de rendu, la fidélité temporelle (la boucle est-elle sans couture ?) et la complétude de la sortie. Exécutez node $SM score dans le dossier d'une scène pour obtenir un rapport, ou node $SM score --project pour noter toutes les scènes d'un projet.

CLI et automatisation

Toutes les commandes CLI sont documentées via --help. Les alias sont activés : b pour build, r pour render, l pour list, p pour plan. L'ordre des arguments n'a pas d'importance, sauf pour les chemins de fichiers. Les variables d'environnement SM_CHROME_BIN et SM_FFMPEG_BIN remplacent les chemins par défaut.

Pour l'intégration CI/CD, tous les drapeaux peuvent être passés via SM_FLAGS :

SM_FLAGS="--scale 2 --formats mp4,webm" node $SM make card-story --tokens brand.json

Dépannage

• « node n'est pas trouvé » : utilisez nvm use 22 ou installez Node 22+
• « Chrome n'est pas trouvé » : définissez SM_CHROME_BIN=/chemin/vers/chrome
• « ffmpeg n'est pas trouvé » : définissez SM_FFMPEG_BIN=/chemin/vers/ffmpeg
• Le rendu est vide : vérifiez que chrome-headless-shell peut s'exécuter sans écran ; utilisez xvfb-run sur Linux
• La scène ne se charge pas : exécutez node $SM build <scène> --dry-run pour voir les vérifications de configuration
• La boucle a un saut : exécutez avec --range loop et vérifiez que scene.js utilise h.loop() ou une fonction sinusoïdale pour le wrapping temporel

---

Documentation complète de l'API : docs/. Problèmes et fonctionnalités : GitHub Issues.