Animation and timelines

A Component timeline connects visual properties to time. It can play on mount, respond to Component state, follow scroll progress, start when an element appears, or be controlled explicitly by logic. The canvas identifies what changes; the Animate inspector and bottom timeline describe when and how it changes.

Timeline anatomy

Timeline
├── playback configuration
├── element layers
│   └── animated property tracks
│       └── keyframes and easing
├── state-action segments
└── audio layers and clips

The timeline itself is stored below the Component root. It is separate from the Timeline Player data-structure slot. A mount-, scroll-, or appear-driven animation can work without enabling Timeline Player; explicit state-driven commands require the player relationship.

The construct timeline shows its element layers, stored keyframes, time ruler, play control, and playhead. This pilot verified the surface without editing the timeline.

What can animate

Ordinary element tracks support current numeric visual properties such as position, translation, scale, rotation, opacity, size, padding, margin, and gap. Specialized captures animate a Path's geometry or a Mesh Gradient's grid. A Code Component can expose declared numeric or color Animatable Properties for timeline control, and a parent can synchronize a nested Component timeline through a sync track.

Shader parameters can be keyed and interpolated in the editor and preview, but current generated output does not serialize shader animation. The exported Shader remains at its static parameters.

Choose how a timeline starts

• Mode: Mount · Behavior: Plays when the Component renders.

• Mode: States · Behavior: Accepts Timeline Player commands such as play, replay, pause, or reverse.

• Mode: Scroll · Behavior: Scrubs timeline progress from scroll position and configured thresholds.

• Mode: Appear · Behavior: Plays once when the target enters the configured view range.

• Mode: None · Behavior: Excludes the timeline from exported output.

Loop, direction, duration, listener behavior, and screen mode are additional configuration. Scroll and Appear can configure axis, smoothness, target, container, and enter/leave thresholds.

Choose one trigger model deliberately. A Timeline Player command does not make a None timeline run; the timeline must use States for player-driven output.

Create an animation in the editor

1. Open a Page or Component and choose Animate.

2. Create or select a named timeline.

3. Set duration and the intended start mode before building many tracks.

4. Select an element and add only properties that should animate.

5. Establish the initial and final keyframes, then add intermediate values only when they improve the motion.

6. Configure easing per property/keyframe where needed.

7. Add state-action segments or audio clips only when timing must be part of the sequence.

8. Play the timeline, then verify it again in runtime Preview using the real trigger.

The bottom timeline contains layers, tracks, keyframes, segments, audio, the time ruler, playhead, zoom, and scroll controls. The right Animate inspector configures the selected timeline and element context.

Keyframes and easing

A keyframe stores a property's value at a time in seconds. At least two meaningful values are normally required for visible interpolation. Named easing values and custom cubic Bézier values control the transition from one keyframe to the next.

Path, Mesh Gradient, and Shader tracks capture their complete current shape/grid/parameter snapshot rather than one ordinary scalar style field. Capture after setting the canvas to the exact state you intend.

Timeline names do not need to be unique in storage, but duplicate names require generated suffixes and make logic harder to read. Use distinct, descriptive names such as enter, expand, or loadingLoop.

State actions and audio

A timeline segment runs supported state/action commands at a configured time range. The same action model is also used by element events, so a sequence can update state, call an exposed event/function, navigate, focus, scroll, play sound, or run a configured database action where supported.

Audio layers and clips refer to token IDs from design-system/audios. Store timing, source token, and clip configuration in the timeline; keep the audio asset or URL valid in the design system.

Timeline segments can cause application or network side effects. Scrubbing or replaying a timeline that includes an action is not equivalent to previewing a purely visual track.

Ask an agent to build a bounded animation

Coverage: UI + MCP for stored timelines; Partial MCP for editor playhead and manual gesture state.

Select the Website project and inspect <component reference> and <element reference>. Read existing timelines first. Add a two-second timeline named fadeIn with mount autoplay. Keyframe the element's opacity from 0 at 0 seconds to 1 at 2 seconds and set an ease-out easing. Do not change its static base style, logic, responsive styles, or other timelines. Read the timeline back, show preview screenshots near the start and finish if supported, inspect generated output, and run diagnostics.

The agent can use get-timelines, add-timeline, set-keyframe, set-keyframe-easing, preview operations, export-code, and get-diagnostics. Use current timeline/node IDs and verify that the property is supported for the selected node.

For a state-driven timeline, first set autoplay: "states", then use set-timeline-command to connect a player command. Mount, Scroll, and Appear modes do not need a Timeline Player command.

Verify animation

1. Read timeline duration, trigger, direction, loop, tracks, keyframes, and easing back.

2. Exercise the actual trigger in Preview rather than dragging only the editor playhead.

3. Check start, intermediate, interrupted, repeated, and completed states.

4. Test responsive container sizes and meaningful Component variants.

5. Inspect generated output for the timeline and required runtime helpers.

6. Confirm external audio loads and that state/action segments run only when intended.

7. Confirm one stored editing action produces the expected Undo result.

Undo, playback, and side effects

Timeline configuration, layers, keyframes, easing, segments, and audio clips are persisted Component content and should be undoable. The current playhead, playback progress, scroll position, and timeline zoom can remain view/session state.

Dragging a stored keyframe should commit one transaction at the gesture boundary. Exported files, Git changes, network requests, database writes, navigation, and media playback are outside the Component's content Undo history.

Current limitations

• Shader keyframes work in the editor and Preview but are not emitted into generated code; exported Shader parameters remain static.

• Separate per-screen timeline configuration is stored and serialized, but current exported element targets are not scoped to the corresponding container-query breakpoint. Treat exported per-screen animation as unfinished.

• A timeline configured as None is excluded from export and cannot be activated by Timeline Player.

• Code Component timelines can animate only fields declared as supported Animatable Properties.

• A visual playback result does not prove that action segments, audio, scroll thresholds, or consuming-app dependencies work.

• The complete timeline gesture workflow still needs runtime verification before website synchronization.