Add more information about animations for both users of Slint and developers working on Slint.

docs/animations.md

@@ -0,0 +1,36 @@
+# Animation System Internals
+
+This document covers Slint's animation system architecture for developers working on the runtime.
+
+For user-facing documentation on using animations, see:
+- [Animation guide](astro/src/content/docs/guide/language/coding/animation.mdx)
+- [Debugging techniques](astro/src/content/docs/guide/development/debugging_techniques.mdx)
+- [Easing types reference](astro/src/content/docs/reference/primitive-types.mdx)
+
+## Animation Timing System
+
+Slint animations use a **mocked time system** rather than real-time clocks. This provides:
+- Deterministic animation behavior for testing
+- Frame-rate independence
+- Consistent behavior across platforms
+
+The animation driver (`internal/core/animations.rs`) manages a global instant that advances each frame:
+
+```
+AnimationDriver
+├── global_instant: Property<Instant>  // Current animation time
+├── active_animations: bool            // Whether animations are running
+└── update_animations(new_tick)        // Called per frame by the backend
+```
+
+**Key components:**
+- `Instant` - Milliseconds since animation driver started
+- `current_tick()` - Get current animation time (registers as dependency)
+- `animation_tick()` - Same as above, but signals a frame is needed
+- `update_timers_and_animations()` - Called by the platform each frame
+
+## Easing Curve Implementation
+
+Easing curves are defined in the `EasingCurve` enum in `internal/core/items.rs`. The interpolation logic is in `internal/core/animations.rs`.
+
+For `cubic-bezier(a, b, c, d)`, Slint uses a binary search algorithm to find the t parameter for a given x value, then evaluates the y component of the bezier curve.

docs/astro/src/content/docs/guide/development/debugging_techniques.mdx

@@ -11,11 +11,55 @@ On this page we share different techniques and tools we've built into Slint that
 
 Use the <Link type="DebugFn" label="debug()" /> function to print the values of properties to stderr.
 
-## Slow Motion Animations
+## Debugging Animations
 
 Animations in the user interface need to be carefully designed to have the correct duration and changes in element positioning or size need to follow an easing curve.
 
-To inspect the animations in your application, set the `SLINT_SLOW_ANIMATIONS` environment variable before running the program. This variable accepts an unsigned integer value that is the factor by which to globally slow down the steps of all animations, automatically. This means that you don't have to make any manual changes to the `.slint` markup and recompile. For example,`SLINT_SLOW_ANIMATIONS=4` slows down animations by a factor of four.
+### Slow Motion Animations
+
+To inspect the animations in your application, set the `SLINT_SLOW_ANIMATIONS` environment variable before running the program. This variable accepts an unsigned integer value that is the factor by which to globally slow down the steps of all animations, automatically. This means that you don't have to make any manual changes to the `.slint` markup and recompile.
+
+```sh
+# Slow animations by a factor of 2
+SLINT_SLOW_ANIMATIONS=2 cargo run
+
+# Slow by a factor of 10 for detailed inspection
+SLINT_SLOW_ANIMATIONS=10 cargo run
+```
+
+This is particularly useful for:
+- Verifying easing curves look correct
+- Checking that animation start and end states are correct
+- Debugging timing issues between multiple animations
+- Inspecting complex state transitions
+
+### Checking for Active Animations
+
+In Rust, you can programmatically check if animations are currently running:
+
+```rust
+if window.has_active_animations() {
+    // Animations are in progress
+}
+```
+
+This is useful when you need to synchronize application logic with animation completion.
+
+### Mock Time in Tests
+
+For automated testing, Slint provides a mock time system that allows precise control over animation timing. Instead of waiting for real time to pass, you can advance the animation clock directly:
+
+```rust
+use slint_testing::mock_elapsed_time;
+
+// Advance animation time by 100ms
+mock_elapsed_time(100);
+
+// Advance to complete a 300ms animation
+mock_elapsed_time(300);
+```
+
+This enables deterministic animation testing without slow, flaky time-based waits.
 
 ## User Interface Scaling
 

docs/astro/src/content/docs/guide/language/coding/animation.mdx

@@ -70,3 +70,30 @@ Can be any of the following. See [`easings.net`](https://easings.net/) for a vis
 Use this to set or change the direction of the animation.
 </SlintProperty>
 
+## Performance Considerations
+
+Each animated property re-evaluates its binding every frame, marks dependents dirty, and triggers re-rendering of affected items. For best performance, avoid animating properties that cause layout recalculations.
+
+```slint
+export component Example inherits Window {
+    preferred-width: 200px;
+    preferred-height: 100px;
+
+    Rectangle {
+        // Good: Animate position (no layout recalculation)
+        x: 0px;
+        animate x { duration: 300ms; }
+    }
+
+    Rectangle {
+        // Avoid: Animating width/height causes layout recalculation
+        width: area.pressed ? 100px : 200px;
+        animate width { duration: 300ms; }
+
+        area := TouchArea {}
+    }
+}
+```
+
+Properties like `x`, `y`, `opacity`, `rotation-angle`, and `background` are efficient to animate. Properties like `width`, `height`, `preferred-width`, and `preferred-height` trigger layout recalculations and should be animated sparingly.
+

docs/readme.md

@@ -7,6 +7,7 @@ docs/
 ├── README.md       # This file
 ├── building.md     # How to build Slint
 ├── development.md  # How to develop Slint
+├── animations.md   # Internals of the animation system in Slint
 ├── embedded-tutorials.md       # Embedded tutorials template
 ├── install_qt.md   # How to install Qt
 ├── nightly-release-notes.md    # Release note template