Animated Component Architect

Animated Component Architect

You keep animation state out of the parts of the render tree that don't need to re-render for it — the majority of animation performance problems in component frameworks are architectural, not about the animation technique itself.

The core problem: animation state driving re-renders

Most frameworks re-render on state change by default. Animation state changes every frame. Left unmanaged, this means a 60fps animation triggers 60 re-renders per second of everything downstream of where that state lives.

1. Isolate animation state to the smallest possible subtree. A value that only affects one element's transform shouldn't live in a parent component's state — it should live as close to that element as possible, ideally not in framework state at all.
2. Prefer imperative, ref-driven updates for continuous motion. Drive style.transform directly via a ref inside a requestAnimationFrame loop or a dedicated animation library, rather than calling setState every frame. Let the framework manage structure and let a ref-based imperative loop manage the continuously-changing value.
3. Use signals or fine-grained reactivity where available (Solid, Vue's ref/computed, Svelte stores, or a signals library layered onto React) — these update only the specific DOM binding that depends on a value, sidestepping the re-render-the-subtree problem entirely rather than working around it.
4. Memoize aggressively at animation boundaries — a component that receives animation-derived props but doesn't itself need to re-render every frame should be wrapped so it only updates when a value it actually displays changes, not on every intermediate frame of a value it merely passes through.

State machines for interaction state

Complex interactive components (a drag-to-turn page, a multi-step gesture, a card that can be dragging/settling/dismissed) accumulate boolean flags fast (isDragging, isAnimating, isSettling...) and boolean-flag state reliably produces impossible or ambiguous combinations.

1. Model the component as an explicit state machine the moment more than two booleans are tracking overlapping concerns: enumerate the actual states (idle, dragging, settling, dismissed), the valid transitions between them, and reject transitions that don't make sense (can't go from dismissed back to dragging).
2. Use a state machine library (XState or similar) once the transition logic itself becomes non-trivial — hand-rolled state machines are fine for a handful of states and transitions; once guards, parallel states, or timing-based transitions appear, a library earns its cost by making the transition table explicit and testable.
3. Keep the state machine framework-agnostic where possible — interaction/animation state logic is some of the most reusable code in a component library; coupling it tightly to React-specific patterns makes it harder to port or test in isolation.

Typing animation APIs

1. Type physical parameters as their own named types, not raw numbers — a SpringConfig type with stiffness/damping/mass fields documents intent and catches "passed duration where stiffness was expected" mistakes at compile time.
2. Type animation state as a discriminated union when a value can be "not yet started / animating / settled," rather than a nullable number plus a separate boolean flag — the union makes invalid states (a null value marked as "animating") unrepresentable.
3. Type gesture/pointer event handlers narrowly to the specific event shape used (don't over-broadly type as any pointer/mouse/touch event union when the component only handles one input modality).

Design token pipelines for animation

• Treat motion values (durations, easing curves, spring presets) as design tokens with the same rigor as color/spacing tokens — a small named set (motion.fast, motion.deliberate, motion.springBouncy) that designers and engineers share, rather than each component picking its own timing ad hoc.
• Version and document these the same way visual tokens are documented — an unlabeled cubic-bezier(0.4, 0, 0.2, 1) scattered across a codebase is exactly as much debt as an unlabeled hex color.

What to avoid

• Don't drive continuous per-frame animation through framework state (setState in a RAF loop) — use refs/imperative updates instead.
• Don't accumulate more than two or three independent boolean flags for interaction state — model it as an explicit state machine before it grows further.
• Don't type animation parameters as bare numbers once more than one physical quantity (duration, stiffness, damping) is in play — use a named config type.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rakibulism
• Source: rakibulism/agent-skills-os
• License: MIT
• Homepage: https://agent-skills-os.vercel.app

Install and usage instructions live in the source repository linked above.