HyperFrames Keyframes
Keyframes sind ein Pose-Vertrag: sichtbare Zustände, kontinuierliche Subjektidentität, seek-sichere Laufzeit, verifizierte Pixel.
Verwenden Sie hyperframes-animation für breite 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.
Vorgehensweise
- 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 seek-sichere Keyframes in der deklarierten Laufzeit. Bauen Sie synchron und registrieren Sie die Laufzeitinstanz.
- Verifizieren Sie mit Lint, Validate,
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.
- Keyframes für sichtbare Kanäle, nicht für versteckte Hilfszustände.
- Bewahren Sie die Objektidentität, wenn Kontinuität wichtig ist.
- Überblenden Sie nur, wenn die beabsichtigte Bewegung Ersetzung 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 angefordert.
- Enden Sie nicht auf Schwarz, es sei denn, es wird angefordert.
- Wenn Sie eine Starterszene bearbeiten, bewahren Sie Layout, Kopie, Assets, Farben und Endzustand, es sei denn, ein Redesign wird angefordert.
Laufzeitregeln
GSAP:
- synchron beim Laden der Seite erstellen
gsap.timeline({ paused: true })verwenden- als
window.__timelines[compositionId]registrieren - Registrierungsschlüssel muss mit
data-composition-idübereinstimmen tl.play()nicht für rendern-kritische 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 Erstellung
- Die Textoberfläche listet WAAPI nicht; mit
--shotverifizieren (es sucht WAAPI) und Snapshots
Niemals für rendern-kritische Bewegungen verwenden:
Date.now()performance.now()- ungeseetes
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()-Tweenings, die dieselbe Eigenschaft berühren.
Keyframe-Formen
- Array-Keyframes: Posenleiter mit Dauer/Easing pro Schritt.
- Prozent-Keyframes: exaktes Timing innerhalb eines Tweens.
- Eigenschafts-Arrays: kompakte Multi-Stopp-Änderungen.
ease: "none"auf dem Elternteil, wenn jeder Stopp sein eigenes Easing 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 von der tatsächlichen Zusammensetzungsgeometrie und -dauer ab.
Für ein Subjekt, das sich zwischen zwei Kästchen bewegt, bevorzugen Sie einen kontinuierlichen Transform-Tween oder FLIP. Teilen Sie x/y/scale nur dann in mehrere erweichte Keyframes auf, wenn der Betrachter einzelne Schläge spüren soll; jedes Segment ändert die Geschwindigkeit und kann als Ruckeln empfunden werden.
Kanäle
Bevorzugen Sie Kompositor-/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, Hilfsüberlagerungen, die Subjektbewegung ausführen.
Mechanismusauswahl
Wählen Sie den kleinsten Mechanismus, der die Anforderung beweist:
| Bedarf | Mechanismus |
|---|---|
| Gleiches Subjekt wechselt Kästchen oder Hierarchie | gemeinsames Element / FLIP |
| Subjekt legt eine sichtbare Route zurück | Pfadverlauf |
| 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 sich | 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 klärt.
- Beschleunigung verlässt den Ruhezustand.
- Spitzenbeweis zeigt den Mechanismus unverkennbar.
- Nachlaufen transportiert Energie und Richtung.
- Überschwingen nur, wenn sich das Subjekt elastisch oder taktil anfühlen soll.
- Konstantgeschwindigkeits-Pfadverlauf benötigt normalerweise
ease: "none". - Diskrete UI-Zustände benötigen normalerweise ein scharfes Ease-Out.
- Wiederholte Elemente benötigen geordnete Versätze, keine identischen Timings.
- Abschließende 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 es, große
clip-path/Masken-Änderungen zu animieren, während dieselbe Heldenfläche auch skaliert oder sich bewegt; verwenden Sie verschachtelte Aufdeckungen, nachdem sich die Hauptbewegung beruhigt hat.
Text
Bewahren Sie Zeilenboxen, 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 Snapshots von lesbaren Frames.
SVG
Für Strichwachstum bevorzugen Sie DrawSVGPlugin, dann stroke-dasharray/stroke-dashoffset.
Für Forminterpolation bevorzugen Sie MorphSVGPlugin; konvertieren Sie Primitive bei Bedarf in Pfade und teilen Sie komplexe Silhouetten in einfachere Teile auf.
3D
Skalierung allein ist keine echte Tiefe.
Verwenden Sie Perspektive auf einem stabilen Elternteil, transform-style: preserve-3d, z-Verlauf, Rotation, Kamera-/Weltbewegung, Okklusion und Ebenenreihenfolge, wenn sich Objekte kreuzen.
Verwenden Sie einen oder zwei Diagnosewinkel, die die Tiefenbeziehung offenlegen. Wenn der abgewinkelte Beweis keine Tiefenkreuzung zeigt, verbessern Sie z/Kamera/Okklusion.
Canvas / WebGL
Keyframe die Kameraposition, das Kamera-Ziel, die Objekttransformation, die Materialopazität, Shader-Uniforms und die Postprozess-Intensität durch deterministischen Zustand. Rendern Sie von der HyperFrames-Zeit. Verwenden Sie --ghost, weil Markierungsboxen 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 "<datei>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<datei>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<datei>" --ghost --angle <winkel>
npx hyperframes snapshot . --at <zeiten>
Wählen Sie <selector> für das tatsächliche animierte Subjekt.
Wählen Sie <zeiten> für ersten Frame, Beweispunkte, Endzustand-minus-Halte und exakten Endzustand.
Wählen Sie <winkel> 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, Zeitabstände, DOM 3D-Projektion, fokussierter Selektorbeweis |
--layout strip | Bewegung an Ort und Stelle, Überlappungen, Kontakt, subtile Skalierung/Opazität, Textwellen |
--ghost | Canvas, WebGL, Shader-Bewegung, gerendertes 3D |
snapshot --at | Masken, Textlesbarkeit, vollständiger Zustand, endgültige Verriegelung, Schwarz/Zurücksetzungs-Enden |
Wenn der Selektorbeweis falsch aussieht:
- führen Sie
--jsonerneut aus - finden Sie das tatsächliche animierte Ziel
- schießen Sie auf dieses Ziel
- machen Sie Snapshots von vollständigen Frames
- vertrauen Sie gemalten Pixeln mehr 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 Kindbewegung die Elternbewegung erbt.
Gleichmäßiger Geisterabstand bedeutet konstante Geschwindigkeit. Gruppierte Geister bedeuten langsames Einlaufen oder Einpendeln. Große Lücken bedeuten schnelle Bewegung.
Ein Hilfsselektor-Schuss ist kein Beweis. Ein Zwiebelschale-Schuss über einen kaputten Vollbild-Frame ist kein Beweis.
Fehlerbehandlung
| Fehler | Korrektur |
|---|---|
| nur-Endpunkt | Zwischenposen hinzufügen, Spitzenbeweis halten, --shot erneut ausführen |
| Identitätsbruch | ein Element am Leben halten, gemeinsame Quell-/Ziel-Boxen verwenden, Ersatz-Überblendung entfernen |
| Fake 3D | z/Kamera-Verlauf, Okklusion, abgewinkelten Beweis hinzufügen |
| falscher Endzustand | Endhalte hinzufügen, Snapshot von Endzustand-minus-Halte und exaktem Endzustand |
| nicht suchbare Laufzeit | Autoplay pausieren, Instanz registrieren, Timer entfernen, synchron erstellen |
| unlesbarer Text | Zeilenboxen bewahren, Verschiebung reduzieren, Endhalte hinzufügen, Snapshots von Textframes |
Fertig
Führen Sie Lint, Validate, Keyframes, einen fokussierten --shot und Snapshots aus. Bestätigen Sie ersten Frame, Beweispunkte, Endzustand-minus-Halte, exakten Endzustand, vom Subjekt getragene Bewegung und keine Debug-Überlagerungen.