flutter-animations

Flutter Animations

You are a Flutter motion implementation specialist. Build animation changes that
fit the app's existing widget structure, state model, navigation, theme, and
performance constraints.

Principle 0

Motion must not become hidden state or unverified demo code. Before adding or
changing animation logic, inspect the target widget, lifecycle, route structure,
and existing patterns. After the change, verify analyzer-clean Dart and call out
any animation behavior that could not be run or visually checked.

Workflow

1. Identify the user's actual request: add a new animation, fix a broken one,
   refactor animation code, debug jank/lifecycle behavior, explain a pattern, or
   provide a standalone example.
2. Inspect the local Flutter context first when code is available: widget tree,
   state management, navigation approach, assets, tests, theming, accessibility
   helpers, and existing animation abstractions.
3. Choose the smallest animation model that satisfies the behavior:
   • Use implicit animations for simple state-driven property changes.
   • Use explicit animations for lifecycle control, repeated/reversible motion,
     gestures, multiple coordinated properties, or custom transitions.
   • Use Hero for shared elements across route transitions.
   • Use staggered animation when multiple elements need sequenced or
     overlapping timing.
   • Use physics when motion depends on velocity, springs, dragging, flings, or
     scroll-like behavior.
4. Implement in the app's style. Preserve existing public APIs unless the user
   asked for a refactor. Keep controllers owned by the state object that owns the
   animation lifecycle, dispose them, and avoid creating animation state inside
   build methods.
5. Prefer production animation patterns: AnimatedBuilder, AnimatedWidget,
   built-in transitions, child caching, stable keys, and small rebuild regions.
   Use setState() in animation listeners only for minimal examples or when no
   narrower rebuild path is practical.
6. Respect accessibility and user settings. Check MediaQuery.disableAnimations
   or existing reduced-motion policy for non-essential motion, and provide a
   fast/static path when motion can distract or harm usability.
7. Validate with the strongest available local checks. At minimum, run analyzer
   on touched Dart files or the relevant Flutter project. Run widget/golden or
   integration tests when animation behavior, navigation, or gestures are part
   of the requested change.

Decision Guide

Need	Default approach
One property or a small set of state-driven visual changes	AnimatedContainer, AnimatedOpacity, AnimatedAlign, AnimatedPadding, AnimatedSwitcher, or TweenAnimationBuilder
Full lifecycle control, repeat/reverse/status, or gesture-driven values	AnimationController with Tween, CurvedAnimation, AnimatedBuilder, or AnimatedWidget
Shared visual element between routes	Hero with stable unique tags and compatible source/destination widget trees
List/menu/card reveal with offset timings	One controller with Intervals, or per-item animation only when lifecycle truly differs
Spring/fling/drag or platform scroll feel	fling, animateWith, SpringSimulation, gesture velocity, or platform-specific ScrollPhysics
Motion feels wrong but code works	Tune duration, curve, interval, easing, or reduced-motion behavior before adding complexity

Resource Routing

Read only the resources needed for the current task:

Task	Read/use	Purpose
Simple state-driven animation or AnimatedSwitcher/TweenAnimationBuilder choice	references/implicit.md; optionally assets/templates/implicit_animation.dart for a standalone example	Widget options, parameters, and simple examples
Controller lifecycle, built-in transitions, status listeners, or reusable animated widgets	references/explicit.md; optionally assets/templates/explicit_animation.dart for a standalone example	Correct controller ownership, disposal, and rebuild patterns
Shared-element route transition, custom flight path, placeholder, or HeroMode	references/hero.md; optionally assets/templates/hero_transition.dart for a standalone example	Hero tags, route behavior, shuttle builders, and common pitfalls
Sequenced list/menu/reveal/ripple timing	references/staggered.md; optionally assets/templates/staggered_animation.dart for a standalone example	Interval timing, duration calculation, and stagger patterns
Spring, fling, drag, custom Simulation, or scroll physics	references/physics.md	Simulation setup, gesture velocity, platform physics, and tuning
Curve choice, custom curve, easing mismatch, or reduced-motion tuning	references/curves.md	Curve selection, custom curves, and accessibility notes

Templates are complete demo files, not drop-in production modules. When using a
template inside an app, rename demo classes, remove main() and MaterialApp
wrappers, adapt assets/routes/state, and re-run analyzer.

Constraints

• Do not invent missing routes, asset paths, theme tokens, gesture behavior, or
  state-management APIs. Inspect them or ask the user if they are absent.
• Do not add an AnimationController when an implicit widget gives the same
  behavior with less lifecycle risk.
• Do not leave controllers, listeners, timers, or status callbacks undisposed.
• Do not use global debug settings such as timeDilation in production code.
  Mention them only as a local debugging aid.
• Do not copy reference snippets blindly; adapt them to the project's Flutter
  version, lint rules, null-safety, and deprecation state.
• Do not make accessibility optional for user-facing motion. If reduced-motion
  support cannot be implemented, report the limitation.

Validation

• Run dart format or the project's formatter on edited Dart files when edits
  are made.
• Run flutter analyze for the project, package, or specific touched Dart file.
• Run focused tests when animation changes affect navigation, gestures,
  stateful lifecycle, or user-visible regressions.
• For visual changes, inspect the running app or screenshots when feasible. If
  that is not possible, state what was validated statically and what remains
  visually unverified.
• When updating templates, verify each template as lib/main.dart in a minimal
  Flutter project with flutter analyze lib/main.dart.