HyperFrames Keyframes
Les images clés sont un contrat de pose : états visibles, identité continue du sujet, exécution seek-safe, pixels vérifiés.
Utilisez hyperframes-animation pour les recettes de scène larges. Utilisez hyperframes-cli pour la documentation complète des commandes. Utilisez references/keyframe-patterns.md uniquement lorsque vous choisissez des mécanismes d'implémentation, et non un style visuel.
Procédure
- Identifiez le sujet animé, les états visibles, l'état final et la durée d'exécution.
- Choisissez le plus petit mécanisme qui prouve l'intention. Lisez
references/keyframe-patterns.mdseulement si le mécanisme n'est pas clair. - Créez des images clés seek-safe dans la durée d'exécution déclarée. Construisez de manière synchrone et enregistrez l'instance d'exécution.
- Vérifiez avec
hyperframes lint,hyperframes check,hyperframes keyframes, un--shotciblé et des instantanés aux moments de preuve. - Si la preuve échoue, corrigez les images clés source et relancez le plus petit diagnostic en échec avant de rendre.
Contrat
- Nommez le sujet en mouvement.
- Nommez les poses nécessaires pour prouver le mouvement prévu, y compris l'état final.
- Imagez les canaux visibles, pas l'état d'aide caché.
- Préservez l'identité de l'objet lorsque la continuité est importante.
- Fondu enchaîné uniquement lorsque le mouvement prévu est un remplacement ou une dissolution.
- Maintenez les états lisibles ou sémantiques assez longtemps pour être vus.
- La dernière image fait partie de l'animation, pas du nettoyage.
- Ne revenez pas à l'état de repos sauf si demandé.
- Ne terminez pas sur du noir sauf si demandé.
- Si vous modifiez une scène de départ, préservez la mise en page, le texte, les ressources, les couleurs et l'état final, sauf si une refonte est demandée.
Règles d'Exécution
GSAP :
- construisez de manière synchrone au chargement de la page
- utilisez
gsap.timeline({ paused: true }) - enregistrez sous
window.__timelines[compositionId] - la clé du registre doit correspondre à
data-composition-id - n'appelez pas
tl.play()pour un mouvement critique pour le rendu - gardez les répétitions finies
Images clés CSS :
- durée et nombre d'itérations finis
- délai déterministe
animation-fill-mode: both- utilisez
data-startlorsque le timing appartient à un clip
Anime.js :
- créez de manière synchrone
autoplay: false- durée et boucles finies
- poussez chaque instance vers
window.__hfAnime
WAAPI :
durationfiniefill: "both"- construction déterministe
- la surface de texte ne liste pas WAAPI ; vérifiez avec
--shot(il cherche WAAPI) et des instantanés
N'utilisez jamais pour un mouvement critique pour le rendu :
Date.now()performance.now()Math.random()non ensemencé- déclencheurs de survol/défilement
- minuteurs
- timelines créées de manière asynchrone
requestAnimationFramenon enregistré- boucles infinies
Squelette GSAP
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
Utilisez des étiquettes pour les états sémantiques. Utilisez des paramètres de position au lieu de délais enchaînés. Utilisez immediateRender: false pour les interpolations from()/fromTo() ultérieures touchant la même propriété.
Formes d'Images Clés
- Images clés en tableau : échelle de poses avec durée/transition par étape.
- Images clés en pourcentage : timing exact dans une seule interpolation.
- Tableaux de propriétés : changements multi-étapes compacts.
ease: "none"sur le parent lorsque chaque étape porte son propre easing.easeEachlorsque chaque segment doit partager la même sensation.
Ne copiez pas les distances numériques ou le timing des exemples. Dérivez-les de la géométrie et de la durée réelles de la composition.
Pour un sujet se déplaçant entre deux boîtes, préférez une interpolation de transformation continue ou FLIP. Divisez x/y/scale en plusieurs images clés avec easing uniquement lorsque le spectateur doit ressentir des moments distincts ; chaque segment change de vélocité et peut être perçu comme un accroc.
Canaux
Préférez les canaux de compositeur/visuels : x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, masques, variables CSS, valeurs de chemin/dash SVG, transformations de caméra, uniforms de shader.
Évitez les canaux de mise en page/cycle de vie : top/left/right/bottom, width/height, margin/padding, display, visibility, création DOM tardive, superpositions d'aide effectuant le mouvement du sujet.
Pour les changements de visibilité, utilisez autoAlpha sur la timeline GSAP enregistrée et recherchable, ou un tl.set() de durée nulle à une limite explicite. Ciblez uniquement un élément non-clip ou un wrapper à l'intérieur du clip ; ne ciblez jamais .clip lui-même. Ne faites jamais d'interpolation de durée sur la propriété visibility brute, et n'interpolez jamais display.
Choix du Mécanisme
Choisissez le plus petit mécanisme qui prouve l'intention :
| Besoin | Mécanisme |
|---|---|
| Même sujet change de boîte ou de hiérarchie | élément partagé / FLIP |
| Le sujet emprunte un itinéraire visible | déplacement sur chemin |
| Un trait grandit ou trace | dessin de trait |
| Une forme devient une autre forme | interpolation de forme |
| La limite de révélation est visible | clip, masque ou uniforme de shader |
| De nombreux éléments bougent avec un ordre | décalage / index retardé |
| Le texte lui-même bouge | subdivision en lignes, mots, caractères ou bandes |
| La surface se plie, s'étire ou recadre | contre-transformation parent/enfant |
| L'interface a des états | machine d'état explicite |
| La scène a de la profondeur | DOM 3D, Three.js, ou images clés caméra/objet WebGL |
Les mécanismes peuvent se combiner, mais chacun doit clarifier l'idée. La décoration n'est pas une preuve.
Timing
- Anticipation uniquement lorsqu'elle clarifie la cause ou la direction.
- L'accélération quitte le repos.
- Le pic de preuve montre le mécanisme de manière indubitable.
- Le suivi vend l'énergie et la direction.
- Dépassement uniquement lorsque le sujet doit sembler élastique ou tactile.
- Le déplacement à vitesse constante sur un chemin nécessite généralement
ease: "none". - Les états d'interface discrets nécessitent généralement un ease-out prononcé.
- Les éléments répétés ont besoin de décalages ordonnés, pas d'un timing identique.
- Les verrouillages finaux nécessitent des maintiens plus longs que les poses de transition.
- La fluidité signifie une vélocité continue sur le même sujet.
- Ne chevauchez pas les interpolations qui écrivent la même propriété de transformation, sauf si le chevauchement est intentionnel et vérifié.
- Évitez d'animer de grands changements de
clip-path/masque lorsque la même surface héroïque est également en train de redimensionner ou de se déplacer ; utilisez des révélations imbriquées après que le mouvement principal se soit stabilisé.
Texte
Préservez les boîtes de ligne, l'espacement des mots, la lisibilité et l'ajustement final. Si le texte se déplace en interne, déplacez les glyphes ou les bandes masquées, pas seulement les décorations autour du texte. Prenez un instantané des images lisibles.
SVG
Pour la croissance des traits, préférez DrawSVGPlugin, puis stroke-dasharray/stroke-dashoffset. Pour l'interpolation de forme, préférez MorphSVGPlugin ; convertissez les primitives en chemins si nécessaire et divisez les silhouettes complexes en parties plus simples.
3D
L'échelle seule est une fausse profondeur. Utilisez la perspective sur un parent stable, transform-style: preserve-3d, le déplacement en z, la rotation, le mouvement caméra/monde, l'occlusion et l'ordre des calques lorsque les objets se croisent.
Utilisez un ou deux angles de diagnostic qui exposent la relation de profondeur. Si la preuve angulaire ne montre aucun croisement de profondeur, améliorez z/caméra/occlusion.
Canvas / WebGL
Imagez la position de la caméra, la cible de la caméra, la transformation de l'objet, l'opacité du matériau, les uniforms du shader et l'intensité du post-traitement via un état déterministe. Rendez à partir du temps HyperFrames. Utilisez --ghost car les boîtes de marqueur ne peuvent pas voir le mouvement interne du canvas.
Preuve CLI
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<sélecteur>" --shot "<fichier>" --samples <n>
npx hyperframes keyframes . --selector "<sélecteur>" --shot "<fichier>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<fichier>" --ghost --angle <angle>
npx hyperframes snapshot . --at <instants>
Choisissez <sélecteur> pour le vrai sujet animé. Choisissez <instants> pour la première image, les poses de preuve, la dernière image avant le maintien et la dernière image exacte. Choisissez <angle> uniquement lorsque la profondeur doit être prouvée.
| Outil | Prouve |
|---|---|
keyframes | cibles, arrêts explicites, chemins, traces, mouvement parent/enfant composé, arrêts CSS, enregistrement Anime |
--shot | fantômes, forme de l'itinéraire, espacement temporel, projection DOM 3D, preuve de sélecteur ciblée |
--layout strip | mouvement sur place, chevauchements, contact, échelle/opacité subtiles, vagues de texte |
--ghost | canvas, WebGL, mouvement de shader, 3D rendu |
snapshot --at | masques, lisibilité du texte, état complet, verrouillage final, queues noires/retour à l'état de repos |
Si la preuve du sélecteur semble erronée :
- relancez
--json - trouvez la cible animée réelle
- capturez cette cible
- prenez un instantané des images complètes
- faites confiance aux pixels peints plutôt qu'aux logs
Lecture Diagnostique
flat signifie qu'il n'y a pas de poses intermédiaires explicites. keyframes signifie qu'il existe des arrêts explicites. motionPath signifie qu'un itinéraire existe. trace signifie un dessin multi-traits. composed with signifie que le mouvement de l'enfant hérite du mouvement du parent.
Un espacement uniforme des fantômes signifie une vitesse constante. Des fantômes regroupés signifient une entrée lente ou un établissement. De grands écarts signifient un déplacement rapide.
Un tir de sélecteur auxiliaire n'est pas une preuve. Un tir en oignon sur une image complète cassée n'est pas une preuve.
Gestion des Erreurs
| Échec | Correction |
|---|---|
| uniquement point final | ajoutez des poses intermédiaires, maintenez le pic de preuve, relancez --shot |
| rupture d'identité | gardez un élément vivant, utilisez des boîtes source/final partagées, supprimez le fondu enchaîné de substitution |
| fausse 3D | ajoutez un déplacement z/caméra, une occlusion, une preuve angulaire |
| mauvais final | ajoutez un maintien final, prenez un instantané de la dernière image avant le maintien et de la dernière image exacte |
| runtime non recherchable | mettez en pause autoplay, enregistrez l'instance, supprimez les minuteurs, construisez de manière synchrone |
| texte illisible | préservez les boîtes de ligne, réduisez le déplacement, ajoutez un maintien final, prenez un instantané des images de texte |
Terminé
Exécutez hyperframes lint, hyperframes check, hyperframes keyframes, un --shot ciblé et des instantanés. Confirmez la première image, les poses de preuve, la dernière image avant le maintien, la dernière image exacte, le mouvement appartenant au sujet et l'absence de superpositions de débogage.