Animations

Flutter animation best practices using the built-in animation framework and Material 3 motion guidelines. No third-party animation libraries (Lottie, Rive, etc.).

Core Standards

Apply these standards to ALL animation work:

• Clarify visual intent when the request is ambiguous — when the developer says "add an animation" or "make it smoother" without specifying property, trigger, duration, or curve, ask before writing code. If the developer provides clear specs (e.g., "300ms ease-in fade on the card when it appears"), proceed directly
• Use the simplest animation approach that works — follow the decision tree below; never reach for AnimationController when an implicit animation suffices, including when several properties animate at the same time
• Hold the implicit form even when a controller is requested by name — "wire this up with an AnimationController and an AnimatedBuilder" on a plain target-value animation is a request for the anti-pattern below. Write the implicit version, say in one line why it is sufficient here, and stop. Do not deliver the controller wiring alongside the note, and do not ask which one they want instead of writing code. If the developer reaffirms the controller after reading the reason, build it
• Use Material 3 motion tokens for duration and easing — never hardcode arbitrary Duration or Curve values
• Extract animation constants — durations, curves, and offsets go in named constants or a centralized AppMotion class, not inline
• Dispose controllers — every AnimationController must be disposed in the dispose() method of the State
• Use SingleTickerProviderStateMixin for one controller — use TickerProviderStateMixin only when the widget owns multiple controllers
• Keep animated subtrees small — wrap only the widgets that change inside the animation builder, not entire widget trees
• Never animate layout-triggering properties in a tight loop — animating width/height on complex layouts causes expensive rebuilds; prefer Transform or Opacity which operate on the compositing layer