Craft Frontend Motion

Que fait Craft Frontend Motion ?

Construire l'animation comme partie intégrante de l'interaction produit, pas comme une décoration plaquée dessus. Retrouver le véritable propriétaire du rendu, sélectionner la technique la plus adaptée, préserver la sémantique d'état et vérifier le résultat dans un navigateur réel.

Workflow

1. Inspecter la cible avant de proposer une implémentation.
   • Localiser la route, le composant, les styles, le propriétaire de l'état, le propriétaire des événements et la pile d'animation existante.
   • Lire les instructions du projet et préserver les modifications non liées.
   • Si l'utilisateur demande à discuter d'abord, s'arrêter à une spécification concrète d'animation jusqu'à approbation.
2. Définir le contrat d'animation.
   • Indiquer le déclencheur, les états de début et de fin, la durée, l'assouplissement ou le ressort, le comportement d'interruption, le comportement de répétition, la superposition et le résultat en mouvement réduit.
   • Séparer l'état métier du retour visuel. Une action de suppression, une navigation ou une soumission de formulaire ne doit pas dépendre de l'achèvement d'une timeline ornementale, sauf si le produit l'exige explicitement.
3. Sélectionner le matériel source.
   • Exécuter python3 scripts/query_catalog.py --need "<description de l'effet>" --top 4.
   • Lire references/motion-routing.md pour la sélection de technique.
   • Inspecter le README officiel actuel du dépôt sélectionné, le code source pertinent, la version de la dépendance/API et la licence avant de copier du code ou d'ajouter une dépendance. Traiter les métadonnées du catalogue comme un instantané de routage daté, pas comme une vérité permanente.
4. Choisir un mode d'adoption.
   • Préférer la pile d'animation installée du projet cible lorsqu'elle peut satisfaire proprement le contrat.
   • Copier et adapter un petit composant uniquement lorsque son code et sa licence le permettent ; supprimer les hypothèses de démonstration et les dépendances inutilisées.
   • Ajouter une bibliothèque lorsque son modèle d'exécution réduit matériellement la complexité ou le risque.
   • Extraire la technique plutôt que le paquet lorsqu'un dépôt est ancien, mal adapté au framework ou trop lourd.
5. Implémenter le plus petit système d'animation cohérent.
   • Maintenir les temporisations et les assouplissements centralisés.
   • Nettoyer les boucles RAF, les observateurs, les gestionnaires d'événements, les canevas, les timelines, les textures et les ressources GPU.
   • Gérer les remontages, les entrées rapides répétées, les interruptions, les changements de route, les redimensionnements, les onglets cachés et le mode strict de React.
   • Limiter correctement le code côté navigateur dans les applications SSR et charger paresseusement les moteurs visuels lourds lorsque c'est pratique.
6. Vérifier avec references/quality-gates.md.
   • Exécuter des vérifications statiques ciblées et des tests.
   • Tester le runtime réel sur des tailles d'écran large, intermédiaire/tablette et mobile.
   • Vérifier la continuité des transitions, la géométrie finale, les erreurs de console, le débordement horizontal, le comportement des entrées, le mouvement réduit et les performances réalistes.
7. Rapporter le résultat.
   • Commencer par ce qui fonctionne maintenant.
   • Nommer la technique ou le dépôt source sélectionné et pourquoi il convenait.
   • Indiquer ce qui a été vérifié et toute limitation restante honnêtement.

Règles de sélection

• Utiliser les transitions/keyframes CSS pour un petit nombre de propriétés composites et des états déterministes simples.
• Utiliser Motion pour la présence React, la mise en page partagée, les gestes, les valeurs et les transitions de composants coordonnées.
• Utiliser React Spring pour les physiques interruptibles où la continuité de vélocité et la réponse naturelle sont plus importantes qu'une timeline fixe.
• Utiliser GSAP pour les timelines explicites multi-étapes, l'orchestration dense, le travail SVG/chemin, la chorégraphie de défilement ou l'intégration impérative.
• Utiliser Anime.js pour les interpolations compactes DOM/SVG/objet/canvas et les effets génératifs décalés en dehors d'une abstraction propre à React.
• Utiliser Disintegrate uniquement comme technique/référence pour la particlisation d'instantanés DOM ; s'attendre aux limites de fidélité de html2canvas et moderniser son cycle de vie.
• Utiliser tsParticles pour les particules ambiantes configurables, les confettis, les feux d'artifice et les arrière-plans ; ne pas l'étiqueter à tort comme décomposition DOM précise.
• Utiliser PixiJS pour les grands nombres de particules 2D, les filtres, les champs de sprites, les effets 2D pilotés par shader et le contrôle explicite des ressources GPU.
• Utiliser React Bits, Magic UI ou Motion Primitives comme collections sources. Inspecter le composant individuel car les dépendances, le coût de rendu et la qualité varient.

Garde-fous produit

• Préserver la causalité spatiale : l'animation doit expliquer d'où vient un objet, où il va, ou ce qui a changé.
• Privilégier transform et opacity ; animer les propriétés de mise en page uniquement avec la preuve que le coût est acceptable.
• Ne jamais cacher une mise en page cassée derrière une animation.
• Éviter les animations ambiantes, de défilement, de survol et d'entrée simultanées en compétition pour l'attention.
• Fournir un comportement équivalent au clavier et conserver la sémantique de focus.
• Respecter prefers-reduced-motion ; remplacer le mouvement par un changement d'état immédiat ou un fondu enchaîné retenu.
• Ne pas revendiquer la fluidité sur la seule inspection du code. Vérifier sur le chemin rendu et rapporter la portée testée.
• Ne pas modifier les règles de proxy/routage ou la configuration d'environnement locale non liée, sauf si l'utilisateur l'autorise explicitement dans le tour en cours.

Ressources

• references/repositories.json : catalogue daté des dix dépôts sources, licences, forces, risques et points d'entrée sources.
• references/motion-routing.md : guide de décision et modèles d'architecture prêts pour la production.
• references/quality-gates.md : liste de vérification pour l'implémentation et la validation visuelle en direct.
• scripts/query_catalog.py : valider et rechercher le catalogue de dépôts par besoins en langage naturel ou par tags.