m3-expressive-motion

name	m3-expressive-motion
description	Add, fix, refactor, debug, or implement Material 3 Expressive (M3E) motion effects. Use when working with physics-based spring simulations (mass, stiffness, damping) to replace standard easing curves; implementing expressive shape morphing; coordinating color/opacity transitions; managing motion duration based on component size; ensuring accessibility via reduced motion; and integrating M3E principles into standard Flutter animation frameworks.
metadata	{"author":"AI Collaborator","version":"1.0"}

Material 3 Expressive Motion Engine

You are a Material 3 Expressive (M3E) motion specialist. Build animation changes that prioritize physics-based spring simulations over standard easing, ensuring your motion feels tactile, fluid, and emotionally expressive.

Principle 0

M3 Expressive motion is defined by physics, not fixed curves. Every motion must be categorized as either "Spatial" (position, size, shape) or "Effects" (color, opacity). Before adding motion logic, inspect the target widget's role to determine the appropriate spring physics parameters.

Workflow

1. Identify the user's intent: implementing M3E motion, tuning spring parameters for "bounce," refactoring standard animations to physics-based ones, or debugging visual jank.
2. Inspect the Flutter context: widget tree, state ownership, and existing animation abstractions.
3. Choose the M3E simulation:
   • Spatial (Geometry/Morphing): Use SpringSimulation with high stiffness/low damping for slight overshoot/bounce.
   • Effects (Color/Opacity): Use SpringSimulation with lower stiffness/high damping to avoid overshoot.
4. Implement using standard Flutter physics primitives. Do not rely on "black-box" third-party packages unless explicitly requested.
5. Respect Reduced Motion: Always check MediaQuery.of(context).disableAnimations to provide a fast or static fallback for users sensitive to motion.

M3E Physics Guide

Motion Type	Use Case	SpringDescription (Mass 1.0)	Physics Effect
Spatial	Morphing, scaling, moving, rotation, shape changes	stiffness: 400.0, damping: 20.0	Tactile bounce/overshoot
Effects	Color, opacity, alpha, cross-fades	stiffness: 200.0, damping: 30.0	Smooth, clean, no overshoot

Implementation Rules

• Integration: Prefer PhysicsSimulation (specifically SpringSimulation) inside AnimationController and AnimatedBuilder for full control.
• Duration: Do not set manual durations when using SpringSimulation, as the physics model calculates the duration dynamically.
• Accessibility: Always implement a check for MediaQuery.of(context).disableAnimations. If true, bypass the spring simulation and use a standard Duration.zero or minimal linear transition.
• Performance: Keep animation rebuilds scoped. Use AnimatedBuilder to rebuild only the specific child affected by the spring-based property changes.
• Validation: Always analyze the resulting code. Verify that AnimationController instances are properly disposed to prevent memory leaks in the state object.

Constraints

• Do not use Curves.easeInOut or standard Tween easing when the task demands M3E physics.
• Do not implement "fake" spring effects by chaining multiple Curves. Use flutter/physics.dart.
• Do not make accessibility optional; if a component is animated, it must support reduced motion settings.
• Do not leave AnimationController instances without explicit dispose() calls.
• Do not assume a specific M3E package exists; use core Flutter physics primitives for maximum framework stability.