Skill

Pass

Audit score 90

flutter-animations

madteacher/mad-agents-skills

Add, fix, refactor, debug, test, and explain Flutter animations and motion effects.

What is flutter-animations?

A Flutter motion implementation specialist skill for working with implicit animations (AnimatedContainer, AnimatedOpacity, AnimatedSwitcher, TweenAnimationBuilder), explicit animations (AnimationController, Tween, CurvedAnimation, AnimatedWidget, AnimatedBuilder), Hero transitions, staggered animations, physics-based motion, gestures, curves, and performance optimization. Use when building or troubleshooting animation behavior, lifecycle management, accessibility, and reduced-motion support.

Implement implicit animations for state-driven property changes using AnimatedContainer, AnimatedOpacity, AnimatedSwitcher, and TweenAnimationBuilder
Build explicit animations with full lifecycle control using AnimationController, Tween, CurvedAnimation, AnimatedBuilder, and AnimatedWidget
Create shared-element route transitions with Hero and custom flight paths
Design staggered and sequenced animations with coordinated timing using Interval patterns
Implement physics-based motion including springs, flings, drag gestures, and scroll physics
Debug animation jank, lifecycle bugs, performance issues, and accessibility concerns including reduced-motion support

How to install flutter-animations

npx skills add https://github.com/madteacher/mad-agents-skills --skill flutter-animations

Prerequisites

Flutter project with Dart analyzer available
Understanding of Flutter widget lifecycle and state management approach used in the project
Access to the target widget tree, route structure, and existing animation patterns

Claude Code

Cursor

Windsurf

Cline

How to use flutter-animations

1.Identify the animation need: add new animation, fix broken animation, refactor code, debug jank, or explain a pattern
2.Inspect the local Flutter context including widget tree, state management, navigation, and existing animation abstractions
3.Choose the smallest animation model: implicit for simple state changes, explicit for lifecycle control, Hero for shared elements, staggered for sequenced timing, or physics for gesture-driven motion
4.Implement the animation in the app's existing style, preserving public APIs and keeping controllers owned by the appropriate state object
5.Validate with dart format, flutter analyze, and run relevant widget or integration tests to verify animation behavior
6.Check accessibility by respecting MediaQuery.disableAnimations and providing fast/static paths for reduced-motion users

Use cases

Good for

Add a smooth fade-in or scale animation to a newly appearing widget using implicit animations
Fix an AnimationController that is not being disposed properly, causing memory leaks
Refactor a complex multi-property animation into a reusable AnimatedWidget or AnimatedBuilder pattern
Create a staggered list reveal where items animate in sequence with offset timings
Implement a spring-based drag gesture or fling animation with custom physics simulation

Who it's for

Flutter developers building custom motion and transitions
UI/UX engineers implementing design animations and micro-interactions
Performance-focused developers optimizing animation lifecycle and rebuild regions
Accessibility-conscious teams ensuring reduced-motion support and non-essential motion handling

flutter-animations FAQ

When should I use implicit animations vs. explicit animations?

Use implicit animations (AnimatedContainer, AnimatedOpacity, AnimatedSwitcher) for simple state-driven property changes. Use explicit animations (AnimationController with Tween, CurvedAnimation, AnimatedBuilder) when you need full lifecycle control, repeat/reverse behavior, gesture-driven values, or multiple coordinated properties.

How do I avoid memory leaks with AnimationController?

Keep the controller owned by the state object that owns the animation lifecycle. Always dispose the controller in the state's dispose() method. Never create animation state inside build() methods.

What is the best way to animate multiple items in sequence?

Use a single AnimationController with Interval patterns for staggered timing, or use per-item animation only when the lifecycle truly differs. This approach is more efficient than creating separate controllers for each item.

How do I support reduced-motion accessibility?

Check MediaQuery.disableAnimations in your animation logic and provide a fast or static alternative path for users who have reduced-motion enabled. This ensures motion does not distract or harm usability for users with motion sensitivity.

What should I do if an animation feels wrong but the code works?

Before adding complexity, tune the duration, curve, interval, easing, or reduced-motion behavior. Most animation issues are resolved by adjusting these parameters rather than changing the underlying animation model.

Full instructions (SKILL.md)

Source of truth, from madteacher/mad-agents-skills.

name: flutter-animations description: >- Add, fix, refactor, debug, test, or explain Flutter animations and motion effects. Use when working with implicit animations such as AnimatedContainer, AnimatedOpacity, AnimatedSwitcher, and TweenAnimationBuilder; explicit animations using AnimationController, Tween, CurvedAnimation, AnimatedWidget, AnimatedBuilder, and built-in transitions; Hero/shared-element route transitions; staggered or sequenced animations; physics-based motion, gestures, springs, flings, scroll physics, curves, performance, accessibility, reduced motion, and animation lifecycle bugs. metadata: author: Stanislav [MADTeacher] Chernyshev version: "2.0"

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

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.
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.
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.
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.
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.
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.
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 `Interval`s, 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.

Related skills

More from madteacher/mad-agents-skills and the wider catalog.

flutter-adaptive-ui