HyperFrames Keyframes
Keyframes sind ein Pose-Vertrag: sichtbare Zustände, kontinuierliche Subjektidentität, suchsichere Laufzeit, verifizierte Pixel.
Verwenden Sie hyperframes-animation für übergreifende Szenenrezepte. Verwenden Sie hyperframes-cli für die vollständige Befehlsdokumentation. Verwenden Sie references/keyframe-patterns.md nur, wenn Sie Implementierungsmechanismen auswählen, nicht den visuellen Stil.
Vorgehen
- Identifizieren Sie das animierte Subjekt, die sichtbaren Zustände, den Endzustand und die Laufzeit.
- Wählen Sie den kleinsten Mechanismus, der die Anforderung beweist. Lesen Sie
references/keyframe-patterns.mdnur, wenn der Mechanismus unklar ist. - Erstellen Sie suchsichere Keyframes in der deklarierten Laufzeit. Bauen Sie synchron auf und registrieren Sie die Laufzeitinstanz.
- Überprüfen Sie mit
hyperframes lint,hyperframes check,hyperframes keyframes, einem fokussierten--shotund Snapshots zu Beweiszeitpunkten. - Wenn der Beweis fehlschlägt, korrigieren Sie die Quell-Keyframes und führen Sie die kleinste fehlschlagende Diagnose erneut aus, bevor Sie rendern.
Vertrag
- Benennen Sie das sich bewegende Subjekt.
- Benennen Sie die Posen, die benötigt werden, um die beabsichtigte Bewegung zu beweisen, einschließlich des Endzustands.
- Keyframen Sie sichtbare Kanäle, keinen versteckten Helferstatus.
- Bewahren Sie die Objektidentität, wenn Kontinuität wichtig ist.
- Überblenden Sie nur, wenn die beabsichtigte Bewegung Ersatz oder Auflösung ist.
- Halten Sie lesbare oder semantische Zustände lange genug an, um sie zu sehen.
- Der letzte Frame ist Teil der Animation, keine Bereinigung.
- Setzen Sie nicht auf Ruhe zurück, es sei denn, es wird verlangt.
- Beenden Sie nicht mit Schwarz, es sei denn, es wird verlangt.
- Wenn Sie eine Startszene bearbeiten, bewahren Sie Layout, Text, Assets, Farben und Endzustand, es sei denn, ein Redesign wird verlangt.
Laufzeitregeln
GSAP:
- Synchron beim Seitenaufbau erstellen
gsap.timeline({ paused: true })verwenden- Als
window.__timelines[compositionId]registrieren - Registrierungsschlüssel muss mit
data-composition-idübereinstimmen tl.play()nicht für renderkritische Bewegungen aufrufen- Wiederholungen endlich halten
CSS-Keyframes:
- Endliche Dauer und Iterationsanzahl
- Deterministische Verzögerung
animation-fill-mode: bothdata-startverwenden, wenn das Timing zu einem Clip gehört
Anime.js:
- Synchron erstellen
autoplay: false- Endliche Dauer und Schleifen
- Jede Instanz zu
window.__hfAnimehinzufügen
WAAPI:
- Endliche
duration fill: "both"- Deterministische Konstruktion
- Die Textoberfläche listet WAAPI nicht auf; mit
--shotüberprüfen (es sucht WAAPI) und Snapshots
Nie für renderkritische Bewegungen verwenden:
Date.now()performance.now()- ungesähtes
Math.random() - Hover/Scroll-Trigger
- Timer
- asynchron erstellte Timelines
- nicht registriertes
requestAnimationFrame - Endlosschleifen
GSAP-Gerüst
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;
Verwenden Sie Labels für semantische Zustände. Verwenden Sie Positionsparameter anstelle von verketteten Verzögerungen. Verwenden Sie immediateRender: false für spätere from()/fromTo()-Tweens, die dieselbe Eigenschaft berühren.
Keyframe-Formen
- Array-Keyframes: Posenleiter mit Dauer/Ease pro Schritt.
- Prozent-Keyframes: exaktes Timing innerhalb eines Tweens.
- Eigenschafts-Arrays: kompakte Multi-Stop-Änderungen.
ease: "none"auf dem Elternelement, wenn jeder Stop seine eigene Easung trägt.easeEach, wenn jedes Segment das gleiche Gefühl haben soll.
Kopieren Sie keine numerischen Abstände oder Timings aus Beispielen. Leiten Sie sie aus der tatsächlichen Kompositionsgeometrie und -dauer ab.
Bevorzugen Sie für ein Subjekt, das sich zwischen zwei Kästchen bewegt, einen kontinuierlichen Transform-Tween oder FLIP. Teilen Sie x/y/scale nur dann in mehrere abgemilderte Keyframes auf, wenn der Betrachter einzelne Beats spüren soll; jedes Segment ändert die Geschwindigkeit und kann als Ruckeln empfunden werden.
Kanäle
Bevorzugen Sie Compositor-/visuelle Kanäle: x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, Masken, CSS-Variablen, SVG-Pfad-/Strichwerte, Kameratransformationen, Shader-Uniforms.
Vermeiden Sie Layout-/Lebenszyklus-Kanäle: top/left/right/bottom, width/height, margin/padding, display, visibility, späte DOM-Erstellung, Helfer-Overlays, die Subjektbewegungen ausführen.
Verwenden Sie für Sichtbarkeitsänderungen autoAlpha auf der registrierten suchbaren GSAP-Timeline oder ein tl.set() mit Nulldauer an einer expliziten Grenze. Zielen Sie nur auf ein Nicht-Clip-Element oder einen Wrapper innerhalb des Clips; zielen Sie niemals auf .clip selbst. Tweenen Sie niemals visibility mit Dauer und niemals display.
Mechanismusauswahl
Wählen Sie den kleinsten Mechanismus, der die Anforderung beweist:
| Bedarf | Mechanismus |
|---|---|
| Gleiches Subjekt wechselt Kästchen/Hierarchie | geteiltes Element / FLIP |
| Subjekt legt einen sichtbaren Weg zurück | Pfadreise |
| Strich wächst oder zeichnet nach | Strichzeichnung |
| Form wird zu einer anderen Form | Forminterpolation |
| Enthüllungsgrenze ist sichtbar | Clip, Maske oder Shader-Uniform |
| Viele Elemente bewegen sich mit Reihenfolge | Stagger / indizierte Verzögerung |
| Text selbst bewegt sich | Zeilen-, Wort-, Zeichen- oder Bandunterteilung |
| Oberfläche biegt, streckt oder beschneidet | Eltern/Kind-Gegentransform |
| UI hat Zustände | explizite Zustandsmaschine |
| Szene hat Tiefe | DOM 3D, Three.js oder WebGL-Kamera/Objekt-Keyframes |
Mechanismen können kombiniert werden, aber jeder muss die Idee verdeutlichen. Dekoration ist kein Beweis.
Timing
- Antizipation nur, wenn sie Ursache oder Richtung verdeutlicht.
- Beschleunigung verlässt die Ruhe.
- Spitzenbeweis zeigt den Mechanismus unmissverständlich.
- Nachlaufen verkauft Energie und Richtung.
- Überschwingen nur, wenn sich das Subjekt elastisch oder taktil anfühlen soll.
- Konstantgeschwindigkeits-Pfadreise benötigt normalerweise
ease: "none". - Diskrete UI-Zustände benötigen normalerweise ein scharfes Ease-Out.
- Wiederholte Elemente benötigen geordnete Versätze, nicht identisches Timing.
- Endgültige Verriegelungen benötigen längere Haltezeiten als Übergangsposen.
- Glätte bedeutet kontinuierliche Geschwindigkeit auf demselben Subjekt.
- Überlappen Sie keine Tweens, die dieselbe Transform-Eigenschaft schreiben, es sei denn, die Überlappung ist beabsichtigt und verifiziert.
- Vermeiden Sie die Animation großer
clip-path/Masken-Änderungen, während dieselbe Heldenoberfläche auch skaliert oder reist; verwenden Sie verschachtelte Enthüllungen, nachdem sich die Hauptbewegung gesetzt hat.
Text
Bewahren Sie Zeilenkästen, Wortabstände, Lesbarkeit und endgültige Passform. Wenn sich Text intern bewegt, bewegen Sie die Glyphen oder maskierten Bänder, nicht nur Dekorationen um den Text. Machen Sie Schnappschüsse von lesbaren Frames.
SVG
Bevorzugen Sie für Strichwachstum DrawSVGPlugin, dann stroke-dasharray/stroke-dashoffset. Bevorzugen Sie für Forminterpolation MorphSVGPlugin; konvertieren Sie Primitive bei Bedarf in Pfade und teilen Sie komplexe Silhouetten in einfachere Teile auf.
3D
Alleinige Skalierung ist falsche Tiefe. Verwenden Sie Perspektive auf einem stabilen Elternelement, transform-style: preserve-3d, Z-Reisen, Rotation, Kamera-/Weltbewegung, Okklusion und Ebenenreihenfolge, wenn Objekte sich kreuzen.
Verwenden Sie ein oder zwei Diagnosewinkel, die die Tiefenbeziehung offenlegen. Wenn der angewinkelte Beweis keine Tiefenkreuzung zeigt, verbessern Sie Z/Kamera/Okklusion.
Canvas / WebGL
Keyframen Sie Kameraposition, Kameraziel, Objekttransformation, Materialdeckkraft, Shader-Uniforms und Nachbearbeitungsintensität durch deterministischen Zustand. Rendern Sie von der HyperFrames-Zeit. Verwenden Sie --ghost, da Markerboxen keine interne Canvas-Bewegung sehen können.
CLI-Beweis
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>
Wählen Sie <selector> für das tatsächliche animierte Subjekt. Wählen Sie <times> für den ersten Frame, Beweispackungen, Final-Minus-Halt und exaktes Finale. Wählen Sie <angle> nur, wenn Tiefe bewiesen werden muss.
| Werkzeug | Beweist |
|---|---|
keyframes | Ziele, explizite Stopps, Pfade, Spuren, zusammengesetzte Eltern/Kind-Bewegung, CSS-Stopps, Anime-Registrierung |
--shot | Geister, Routenform, Zeitabstand, DOM-3D-Projektion, fokussierter Selektorbeweis |
--layout strip | Bewegung am Ort, Überlappungen, Kontakt, subtile Skalierung/Deckkraft, Textwellen |
--ghost | Canvas, WebGL, Shader-Bewegung, gerendertes 3D |
snapshot --at | Masken, Textlesbarkeit, vollständiger Zustand, endgültige Verriegelung, Schwarz/Rücklauf-Enden |
Wenn der Selektorbeweis falsch aussieht:
--jsonerneut ausführen- das tatsächliche animierte Ziel finden
- dieses Ziel schießen
- vollständige Frames erfassen
- gemalten Pixeln mehr vertrauen als Logs
Diagnose lesen
flat bedeutet keine expliziten Zwischenposen. keyframes bedeutet, dass explizite Stopps existieren. motionPath bedeutet, dass eine Route existiert. trace bedeutet mehrstrichiges Zeichnen. composed with bedeutet, dass die Kind-Bewegung die Eltern-Bewegung erbt.
Gleichmäßiger Geisterabstand bedeutet konstante Geschwindigkeit. Geclusterte Geister bedeuten langsames Einlaufen oder Setzen. Große Lücken bedeuten schnelle Reise.
Ein Helfer-Selektor-Schuss ist kein Beweis. Ein Zwiebelschalen-Schuss über einem defekten Vollbild ist kein Beweis.
Fehlerbehandlung
| Fehler | Korrektur |
|---|---|
| Nur Endpunkt | Fügen Sie mittlere Posen hinzu, halten Sie den Spitzenbeweis, führen Sie --shot erneut aus |
| Identitätsbruch | Halten Sie ein Element am Leben, verwenden Sie gemeinsame Quell-/Zielkästen, entfernen Sie Ersatz-Überblendung |
| Falsches 3D | Fügen Sie Z/Kamera-Reise, Okklusion, angewinkelten Beweis hinzu |
| Falsches Ende | Fügen Sie finalen Halt hinzu, erfassen Sie Final-Minus-Halt und exaktes Finale |
| Nicht suchbare Laufzeit | Stoppen Sie die Autowiedergabe, registrieren Sie die Instanz, entfernen Sie Timer, bauen Sie synchron auf |
| Unlesbarer Text | Bewahren Sie Zeilenkästen, reduzieren Sie Verschiebung, fügen Sie finalen Halt hinzu, erfassen Sie Textframes |
Fertig
Führen Sie hyperframes lint, hyperframes check, hyperframes keyframes, einen fokussierten --shot und Snapshots aus. Bestätigen Sie ersten Frame, Beweisposen, Final-Minus-Halt, exaktes Finale, subjekteigene Bewegung und keine Debug-Overlays.