HyperFrames Keyframes
Les images clés sont un contrat de pose : états visibles, identité continue du sujet, exécution sécurisée pour la recherche, pixels vérifiés.
Utilisez hyperframes-animation pour les recettes de scène générales.
Utilisez hyperframes-cli pour la documentation complète des commandes.
Utilisez references/keyframe-patterns.md uniquement pour choisir les mécanismes d'implémentation, pas le style visuel.
Procédure
- Identifiez le sujet animé, les états visibles, l'état final et la durée d'exécution.
- Choisissez le mécanisme le plus petit qui prouve l'intention. Lisez
references/keyframe-patterns.mduniquement si le mécanisme n'est pas clair. - Créez des images clés seek-safe dans l'exécution déclarée. Construisez de manière synchrone et enregistrez l'instance d'exécution.
- Vérifiez avec lint, validate,
hyperframes keyframes, un--shotciblé et des instantanés aux moments de preuve. - Si la preuve échoue, corrigez les images clés source et réexécutez 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.
- Animez les canaux visibles, pas les états d'aide cachés.
- Préservez l'identité de l'objet lorsque la continuité est importante.
- Utilisez le fondu enchaîné uniquement lorsque le mouvement prévu est un remplacement ou une dissolution.
- Maintenez les états lisibles ou sémantiques suffisamment longtemps pour être vus.
- La dernière image fait partie de l'animation, pas un nettoyage.
- Ne revenez pas à l'état de repos sauf demande explicite.
- Ne terminez pas sur du noir sauf demande explicite.
- Si vous modifiez une scène de départ, conservez la mise en page, le texte, les actifs, 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 comme
window.__timelines[compositionId] - la clé d'enregistrement doit correspondre à
data-composition-id - n'appelez pas
tl.play()pour le mouvement critique du rendu - gardez les répétitions finies
Animations CSS :
- durée finie et nombre d'itérations fini
- 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 les instantanés
N'utilisez jamais pour le mouvement critique du rendu :
Date.now()performance.now()Math.random()non initialisé- 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 from()/fromTo() ultérieurs touchant la même propriété.
Formes d'images clés
- Images clés tableau : échelle de poses avec durée/temps par étape.
- Images clés pourcentage : timing exact à l'intérieur d'une seule interpolation.
- Tableaux de propriétés : changements multi-étapes compacts.
ease: "none"sur le parent lorsque chaque étape a son propre easing.easeEachlorsque chaque segment doit partager la même sensation.
Ne copiez pas les distances numériques ou les timings 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 seule interpolation de transformation continue ou FLIP. Divisez x/y/scale en plusieurs images clés avec easing uniquement lorsque le spectateur doit ressentir des temps distincts ; chaque segment change de vélocité et peut être perçu comme un à-coup.
Canaux
Préférez les canaux de composition/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.
Choix du mécanisme
Choisissez le mécanisme le plus petit qui prouve l'intention :
| Besoin | Mécanisme |
|---|---|
| Le même sujet change de boîte ou de hiérarchie | élément partagé / FLIP |
| Le sujet parcourt un itinéraire visible | chemin de déplacement |
| Le 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 |
| Plusieurs éléments se déplacent en ordre | décalage / délai indexé |
| Le texte lui-même se déplace | subdivision de ligne, mot, caractère ou bande |
| La surface se plie, s'étire ou recadre | contre-transformation parent/enfant |
| L'interface utilisateur a des états | machine à états explicite |
| La scène a de la profondeur | DOM 3D, Three.js, ou images clés de 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.
- La preuve maximale montre le mécanisme de manière indubitable.
- Le suivi vend l'énergie et la direction.
- Le 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 utilisateur discrets nécessitent généralement un ease-out brusque.
- Les éléments répétés ont besoin de décalages ordonnés, pas de timings identiques.
- 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 superposez pas les interpolations qui écrivent la même propriété de transformation, sauf si la superposition est intentionnelle et vérifiée.
- Évitez d'animer de grandes modifications de
clip-path/masque pendant que la même surface héroïque se met également à l'échelle ou se déplace ; utilisez des révélations imbriquées après que le mouvement principal s'est 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 à l'intérieur, déplacez les glyphes ou les bandes masquées, pas seulement les décorations autour du texte. Prenez des instantanés des images lisibles.
SVG
Pour la croissance du trait, 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 de la caméra/monde, l'occlusion et l'ordre des couches 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 le z/caméra/occlusion.
Canvas / WebGL
Animez 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 "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
Choisissez <selector> pour le véritable sujet animé.
Choisissez <times> pour la première image, les poses de preuve, final-moins-maintien, et la toute dernière image.
Choisissez <angle> uniquement lorsque la profondeur doit être prouvée.
| Outil | Prouve |
|---|---|
keyframes | cibles, arrêts explicites, chemins, traces, mouvement composé parent/enfant, 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/de réinitialisation |
Si la preuve de sélecteur semble erronée :
- réexécutez
--json - trouvez la cible animée réelle
- ciblez cette cible
- prenez des instantanés des images complètes
- faites confiance aux pixels peints plutôt qu'aux journaux
Lecture du diagnostic
flat signifie qu'il n'y a pas de poses intermédiaires explicites. keyframes signifie que des arrêts explicites existent. 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 groupés signifient un ralentissement ou un palier. De grands écarts signifient un déplacement rapide.
Un plan avec un sélecteur d'aide n'est pas une preuve. Un plan en oignon sur une image complète cassée n'est pas une preuve.
Gestion des erreurs
| Échec | Correction |
|---|---|
| point final uniquement | ajoutez des poses intermédiaires, maintenez la preuve maximale, réexécutez --shot |
| rupture d'identité | gardez un élément vivant, utilisez des boîtes source/finale partagées, supprimez le fondu 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é final-moins-maintien et du final exact |
| exécution non cherchable | mettez en pause la lecture automatique, 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 des instantanés des images de texte |
Terminé
Exécutez lint, validate, keyframes, un --shot ciblé et des instantanés. Confirmez la première image, les poses de preuve, final-moins-maintien, le final exact, le mouvement appartenant au sujet et l'absence de superpositions de débogage.