hyperframes-keyframes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HyperFrames Keyframes

HyperFrames 关键帧

Keyframes are a pose contract: visible states, continuous subject identity, seek-safe runtime, verified pixels.

Use

hyperframes-animation

for broad scene recipes. Use

hyperframes-cli

for full command docs. Use

references/keyframe-patterns.md

only when choosing implementation mechanisms, not visual style.

关键帧是一种姿态约定：包含可见状态、连续的主体标识、可安全定位的运行时以及经过验证的像素效果。

如需通用场景方案，请使用

hyperframes-animation

。如需完整命令文档，请使用

hyperframes-cli

。仅在选择实现机制时参考

references/keyframe-patterns.md

，请勿用于视觉风格设计。

Procedure

操作流程

Identify the animated subject, visible states, final state, and runtime.
Choose the smallest mechanism that proves the prompt. Read
```
references/keyframe-patterns.md
```
only if the mechanism is unclear.
Author seek-safe keyframes in the declared runtime. Build synchronously and register the runtime instance.
Verify with lint, validate,
```
hyperframes keyframes
```
, one focused
```
--shot
```
, and snapshots at proof times.
If proof fails, fix the source keyframes and rerun the smallest failing diagnostic before rendering.

确定动画主体、可见状态、最终状态及运行时长。
选择能满足需求的最小实现机制。若对机制不明确，再阅读
```
references/keyframe-patterns.md
```
。
在指定运行时中编写支持安全定位的关键帧。同步构建并注册运行时实例。
通过lint校验、验证工具、
```
hyperframes keyframes
```
命令、聚焦式
```
--shot
```
命令以及关键时间点的快照进行验证。
若验证失败，修复源关键帧，并在渲染前重新运行最小范围的失败诊断。

Contract

约定规则

Name the moving subject.
Name the poses needed to prove the intended motion, including the final state.
Keyframe visible channels, not hidden helper state.
Preserve object identity when continuity matters.
Crossfade only when the intended motion is replacement or dissolve.
Hold readable or semantic states long enough to see.
Final frame is part of the animation, not cleanup.
Do not reset to rest unless requested.
Do not end on black unless requested.
If editing a starter scene, preserve layout, copy, assets, colors, and final state unless asked to redesign.

为运动主体命名。
为证明预期运动所需的姿态命名，包括最终状态。
为可见通道设置关键帧，而非隐藏的辅助状态。
当连续性至关重要时，保持对象标识一致。
仅当预期运动为替换或溶解效果时使用交叉淡入淡出。
可读性或语义化状态需保持足够长的显示时间。
最终帧属于动画的一部分，而非清理阶段。
除非明确要求，否则不要重置至初始状态。
除非明确要求，否则不要以黑屏结束。
若编辑初始场景，除非要求重新设计，否则需保留布局、文案、资源、颜色及最终状态。

Runtime Rules

运行时规则

GSAP:

build synchronously at page load
use
```
gsap.timeline({ paused: true })
```
register as
```
window.__timelines[compositionId]
```
registry key must match
```
data-composition-id
```
do not call
```
tl.play()
```
for render-critical motion
keep repeats finite

CSS keyframes:

finite duration and iteration count
deterministic delay
```
animation-fill-mode: both
```
use
```
data-start
```
when timing belongs to a clip

Anime.js:

create synchronously
```
autoplay: false
```
finite duration and loops
push every instance to
```
window.__hfAnime
```

WAAPI:

finite
```
duration
```
```
fill: "both"
```
deterministic construction
the text surface does not list WAAPI; verify with
```
--shot
```
(it seeks WAAPI) and snapshots

Never use for render-critical motion:

```
Date.now()
```
```
performance.now()
```
unseeded
```
Math.random()
```
hover/scroll triggers
timers
async-created timelines
unregistered
```
requestAnimationFrame
```
infinite loops

GSAP:

在页面加载时同步构建
使用
```
gsap.timeline({ paused: true })
```
注册为
```
window.__timelines[compositionId]
```
注册表键必须与
```
data-composition-id
```
匹配
对于渲染关键的运动，不要调用
```
tl.play()
```
保持重复次数为有限值

CSS关键帧:

有限的持续时间和迭代次数
确定的延迟时间
设置
```
animation-fill-mode: both
```
当时间属于片段时使用
```
data-start
```

Anime.js:

同步创建实例
设置
```
autoplay: false
```
有限的持续时间和循环次数
将每个实例推入
```
window.__hfAnime
```

WAAPI:

有限的
```
duration
```
设置
```
fill: "both"
```
确定的构建方式
文本表面不会列出WAAPI；需通过
```
--shot
```
（支持WAAPI定位）和快照进行验证

以下内容绝不能用于渲染关键的运动：

```
Date.now()
```
```
performance.now()
```
未设置种子的
```
Math.random()
```
悬停/滚动触发
定时器
异步创建的时间线
未注册的
```
requestAnimationFrame
```
无限循环

GSAP Skeleton

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;

Use labels for semantic states. Use position parameters instead of chained delays. Use

immediateRender: false

for later

from()

fromTo()

tweens touching the same property.

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;

为语义化状态使用标签。使用位置参数而非链式延迟。对于后续修改同一属性的

from()

fromTo()

补间，使用

immediateRender: false

。

Keyframe Forms

关键帧形式

Array keyframes: pose ladder with per-step duration/ease.
Percentage keyframes: exact timing inside one tween.
Property arrays: compact multi-stop changes.
```
ease: "none"
```
on the parent when each stop carries its own easing.
```
easeEach
```
when every segment should share the same feel.

Do not copy numeric distances or timing from examples. Derive them from the actual composition geometry and duration.

For one subject moving between two boxes, prefer one continuous transform tween or FLIP. Split

x/y/scale

into multiple eased keyframes only when the viewer should feel distinct beats; every segment changes velocity and can read as a hitch.

数组式关键帧：包含每一步时长/缓动的姿态阶梯。
百分比式关键帧：单个补间内的精确时间控制。
属性数组：紧凑的多阶段变化。
当每个阶段都有自己的缓动时，父级设置
```
ease: "none"
```
。
当所有段需要相同的动效时，使用
```
easeEach
```
。

不要从示例中复制数值距离或时间参数。需从实际合成内容的几何结构和时长中推导。

对于单个主体在两个容器间移动的场景，优先使用连续的变换补间或FLIP。仅当需要让观众感受到明显节奏变化时，才将

x/y/scale

拆分为多个带缓动的关键帧；每个段都会改变速度，可能会产生卡顿感。

Channels

通道选择

Prefer compositor/visual channels:

x/y/z

xPercent/yPercent

scale

rotationX/Y/Z

skew

transformOrigin

svgOrigin

opacity

autoAlpha

clip-path

, masks, CSS vars, SVG path/dash values, camera transforms, shader uniforms.

Avoid layout/lifecycle channels:

top/left/right/bottom

width/height

margin/padding

display

visibility

, late DOM creation, helper overlays doing subject motion.

优先使用合成/视觉通道：

x/y/z

xPercent/yPercent

scale

rotationX/Y/Z

skew

transformOrigin

svgOrigin

opacity

autoAlpha

clip-path

, 遮罩, CSS变量, SVG路径/虚线值, 相机变换, 着色器 uniforms。

避免使用布局/生命周期通道：

top/left/right/bottom

width/height

margin/padding

display

visibility

, 延迟创建DOM元素, 通过辅助层实现主体运动。

Mechanism Choice

机制选择

Choose the smallest mechanism that proves the prompt:

Need	Mechanism
Same subject changes box or hierarchy	shared element / FLIP
Subject travels a visible route	path travel
Stroke grows or traces	stroke draw
Shape becomes another shape	shape interpolation
Reveal boundary is visible	clip, mask, or shader uniform
Many items move with order	stagger / indexed delay
Text itself moves	line, word, character, or band subdivision
Surface bends, stretches, or crops	parent/child counter-transform
UI has states	explicit state machine
Scene has depth	DOM 3D, Three.js, or WebGL camera/object keyframes

Mechanisms can combine, but each one must clarify the idea. Decoration is not proof.

选择能满足需求的最小实现机制：

需求	实现机制
同一主体在容器或层级间切换	共享元素 / FLIP
主体沿可见路径移动	路径跟随
描边生长或轨迹绘制	描边绘制
形状转换为另一种形状	形状插值
显示边界可见	裁剪、遮罩或着色器uniform
多个元素按顺序移动	交错动画 / 索引延迟
文本自身运动	按行、单词、字符或区域拆分
表面弯曲、拉伸或裁剪	父/子反向变换
UI存在状态切换	显式状态机
场景包含深度效果	DOM 3D、Three.js或WebGL相机/对象关键帧

机制可以组合，但每个机制都必须明确表达设计意图。装饰性效果不属于必要证明内容。

Timing

时间控制

Anticipation only when it clarifies cause or direction.
Acceleration leaves rest.
Peak proof shows the mechanism unmistakably.
Follow-through sells energy and direction.
Overshoot only when the subject should feel elastic or tactile.
Constant-speed path travel usually needs
```
ease: "none"
```
.
Discrete UI states usually need a sharp ease-out.
Repeated elements need ordered offsets, not identical timing.
Final lockups need longer holds than transition poses.
Smoothness means continuous velocity on the same subject.
Do not overlap tweens that write the same transform property unless the overlap is intentional and verified.
Avoid animating large
```
clip-path
```
/mask changes while the same hero surface is also scaling or traveling; use nested reveals after the main move settles.

仅当能明确原因或方向时使用预备动作。
加速动作从静止状态开始。
核心证明帧需清晰展示实现机制。
跟随动作传递能量和方向感。
仅当主体需要体现弹性或触感时使用过冲效果。
匀速路径移动通常需要设置
```
ease: "none"
```
。
离散UI状态通常需要生硬的缓出效果。
重复元素需要有序的偏移，而非相同的时间参数。
最终锁定状态的保持时间需长于过渡姿态。
平滑意味着同一主体的速度连续变化。
除非是有意设计并经过验证的重叠，否则不要让修改同一变换属性的补间重叠。
避免在同一核心表面缩放或移动时，同时进行大规模
```
clip-path
```
/遮罩变化；应在主运动稳定后使用嵌套显示效果。

Text

文本处理

Preserve line boxes, word spacing, readability, and final fit. If text moves internally, move the glyphs or masked bands, not only decorations around the text. Snapshot readable frames.

保留行框、单词间距、可读性和最终适配效果。若文本内部需要运动，应移动字形或遮罩区域，而非仅移动文本周围的装饰元素。对可读帧进行快照。

SVG

SVG处理

For stroke growth prefer

DrawSVGPlugin

, then

stroke-dasharray

stroke-dashoffset

. For shape interpolation prefer

MorphSVGPlugin

; convert primitives to paths when needed and split complex silhouettes into simpler parts.

对于描边生长效果，优先使用

DrawSVGPlugin

，其次是

stroke-dasharray

stroke-dashoffset

。对于形状插值，优先使用

MorphSVGPlugin

；必要时将基本图形转换为路径，并将复杂轮廓拆分为更简单的部分。

3D

3D效果

Scale alone is fake depth. Use perspective on a stable parent,

transform-style: preserve-3d

, z travel, rotation, camera/world motion, occlusion, and layer order when objects cross.

Use one or two diagnostic angles that expose the depth relationship. If angled proof shows no depth crossing, improve z/camera/occlusion.

仅缩放属于伪深度效果。在稳定的父元素上使用透视、

transform-style: preserve-3d

、z轴移动、旋转、相机/世界运动、遮挡效果，以及对象交叉时的层级顺序。

使用一到两个诊断视角来展示深度关系。若角度证明帧未显示深度交叉，需优化z轴/相机/遮挡设置。

Canvas / WebGL

Keyframe camera position, camera target, object transform, material opacity, shader uniforms, and postprocess intensity through deterministic state. Render from HyperFrames time. Use

--ghost

because marker boxes cannot see internal canvas motion.

通过确定状态对相机位置、相机目标、对象变换、材质透明度、着色器uniforms和后期处理强度设置关键帧。根据HyperFrames时间进行渲染。使用

--ghost

命令，因为标记框无法识别Canvas内部的运动。

CLI Proof

CLI 验证命令

bash

npx hyperframes lint
npx hyperframes validate
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>

Choose

<selector>

for the real animated subject. Choose

<times>

for first frame, proof poses, final-minus-hold, and exact final. Choose

<angle>

only when depth must be proven.

Tool	Proves
`keyframes`	targets, explicit stops, paths, traces, composed parent/child motion, CSS stops, Anime registration
`--shot`	ghosts, route shape, time spacing, DOM 3D projection, focused selector proof
`--layout strip`	in-place motion, overlaps, contact, subtle scale/opacity, text waves
`--ghost`	canvas, WebGL, shader motion, rendered 3D
`snapshot --at`	masks, text readability, full state, final lockup, black/reset tails

If selector proof looks wrong:

rerun
```
--json
```
find the actual animated target
shoot that target
snapshot full frames
trust painted pixels over logs

bash

npx hyperframes lint
npx hyperframes validate
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>

为真实动画主体选择

<selector>

。为第一帧、核心证明姿态、最终保持前一帧和精确最终帧选择

<times>

。仅当需要证明深度效果时选择

<angle>

。

工具	验证内容
`keyframes`	目标元素、显式停顿、路径、轨迹、组合的父/子运动、CSS停顿、Anime实例注册
`--shot`	重影效果、路径形状、时间间隔、DOM 3D投影、聚焦选择器验证
`--layout strip`	原位运动、重叠效果、接触效果、细微缩放/透明度变化、文本波动
`--ghost`	Canvas、WebGL、着色器运动、渲染的3D效果
`snapshot --at`	遮罩、文本可读性、完整状态、最终锁定效果、黑屏/重置收尾

若选择器验证结果异常：

重新运行
```
--json
```
命令
找到实际的动画目标
对该目标执行shot命令
拍摄完整帧快照
以渲染的像素效果为准，而非日志

Diagnostic Reading

诊断结果解读

flat

means no explicit middle poses.

keyframes

means explicit stops exist.

motionPath

means a route exists.

trace

means multi-stroke drawing.

composed with

means child motion inherits parent motion.

Even ghost spacing means constant speed. Clustered ghosts mean slow-in or settle. Large gaps mean fast travel.

A helper-selector shot is not proof. An onion shot over a broken full frame is not proof.

flat

表示没有显式的中间姿态。

keyframes

表示存在显式停顿。

motionPath

表示存在路径。

trace

表示多描边绘制。

composed with

表示子运动继承了父运动。

均匀的重影间距表示匀速运动。密集的重影表示减速或停顿。较大的间距表示快速运动。

辅助选择器的shot结果不属于有效证明。在损坏的完整帧上的洋葱皮效果也不属于有效证明。

Error Handling

错误处理

Failure	Fix
endpoint-only	add middle poses, hold peak proof, rerun `--shot`
identity break	keep one element alive, use shared source/final boxes, remove substitute crossfade
fake 3D	add z/camera travel, occlusion, angled proof
wrong final	add final hold, snapshot final-minus-hold and exact final
unseekable runtime	pause autoplay, register instance, remove timers, build synchronously
unreadable text	preserve line boxes, reduce displacement, add final hold, snapshot text frames

故障类型	修复方案
仅端点帧	添加中间姿态、保持核心证明帧、重新运行 `--shot` 命令
主体标识断裂	保持单个元素存活、使用共享的起始/结束容器、移除替代元素的交叉淡入淡出效果
伪3D效果	添加z轴/相机移动、遮挡效果、角度证明帧
最终状态错误	添加最终保持帧、拍摄最终保持前一帧和精确最终帧的快照
不可定位的运行时	暂停自动播放、注册实例、移除定时器、同步构建
文本不可读	保留行框、减少位移、添加最终保持帧、拍摄文本帧快照

Done

完成标准

Run lint, validate, keyframes, one focused

--shot

, and snapshots. Confirm first frame, proof poses, final-minus-hold, exact final, subject-owned motion, and no debug overlays.

运行lint校验、验证工具、keyframes命令、一次聚焦式

--shot

命令，并拍摄快照。确认第一帧、核心证明姿态、最终保持前一帧、精确最终帧、主体自有运动，且无调试叠加层。