chore: bring flutter client, docs, deploy and tools into monorepo

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-05 03:22:24 +02:00
parent 8c0519d125
commit 4b80c7dbb0
189 changed files with 19124 additions and 0 deletions
@@ -0,0 +1,116 @@
+---
+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
+
+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 `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`.