BerlinKing/craft-frontend-motion

Craft Frontend Motion

Build motion as part of the product interaction, not as decoration pasted onto it. Trace the real render owner, select the smallest suitable technique, preserve state semantics, and verify the result in a live browser.

Workflow

1. Inspect the target before proposing an implementation.
   • Locate the actual route, component, styles, state owner, event owner, and existing animation stack.
   • Read project instructions and preserve unrelated changes.
   • If the user asks to discuss first, stop at a concrete motion specification until approval.
2. Define the motion contract.
   • State the trigger, start and end states, duration, easing or spring, interruption behavior, repeat behavior, layering, and reduced-motion result.
   • Separate business state from visual feedback. A delete action, navigation, or form submission must not depend on an ornamental timeline completing unless the product explicitly requires it.
3. Select source material.
   • Run python3 scripts/query_catalog.py --need "<effect description>" --top 4.
   • Read references/motion-routing.md for technique selection.
   • Inspect the selected repository's current official README, relevant source, dependency/API version, and license before copying code or adding a dependency. Treat catalog metadata as a dated routing snapshot, not permanent truth.
4. Choose an adoption mode.
   • Prefer the target project's installed animation stack when it can satisfy the contract cleanly.
   • Copy and adapt a small component only when its code and license permit it; remove demo-shell assumptions and unused dependencies.
   • Add a library when its runtime model materially reduces complexity or risk.
   • Extract the technique rather than the package when a repository is old, framework-mismatched, or too heavy.
5. Implement the smallest coherent motion system.
   • Keep timing and easing tokens centralized.
   • Clean up RAF loops, observers, event handlers, canvases, timelines, textures, and GPU resources.
   • Handle remounts, rapid repeated input, interruption, route changes, resizing, hidden tabs, and React Strict Mode.
   • Gate browser-only code correctly in SSR applications and lazy-load heavy visual engines when practical.
6. Verify with references/quality-gates.md.
   • Run focused static checks and tests.
   • Exercise the real runtime at wide desktop, intermediate/tablet, and mobile sizes.
   • Check transition continuity, final geometry, console errors, horizontal overflow, input behavior, reduced motion, and realistic performance.
7. Report the outcome.
   • Lead with what now works.
   • Name the selected technique or source repository and why it fit.
   • State what was verified and any remaining limitation honestly.

Selection Rules

• Use CSS transitions/keyframes for a small number of composited properties and simple deterministic states.
• Use Motion for React presence, shared layout, gestures, values, and coordinated component transitions.
• Use React Spring for interruptible physics where velocity continuity and natural response matter more than a fixed timeline.
• Use GSAP for explicit multi-stage timelines, dense orchestration, SVG/path work, scroll choreography, or imperative integration.
• Use Anime.js for compact DOM/SVG/object/canvas tweening and staggered generative effects outside a React-specific abstraction.
• Use Disintegrate only as a technique/reference for DOM snapshot particleization; expect html2canvas fidelity limits and modernize its lifecycle.
• Use tsParticles for configurable ambient particles, confetti, fireworks, and backgrounds; do not mislabel it as precise DOM decomposition.
• Use PixiJS for large 2D particle counts, filters, sprite fields, shader-driven 2D effects, and explicit GPU resource control.
• Use React Bits, Magic UI, or Motion Primitives as source collections. Inspect the individual component because dependencies, rendering cost, and quality vary.

Product Guardrails

• Preserve spatial causality: motion should explain where an object came from, where it went, or what changed.
• Prefer transform and opacity; animate layout properties only with evidence that the cost is acceptable.
• Never hide broken layout behind motion.
• Avoid simultaneous ambient, scroll, hover, and entrance animations competing for attention.
• Provide keyboard-equivalent behavior and retain focus semantics.
• Respect prefers-reduced-motion; replace movement with an immediate state change or restrained crossfade.
• Do not claim smoothness from code inspection alone. Verify on the rendered path and report the tested scope.
• Do not alter proxy/routing rules or unrelated local environment configuration unless the user explicitly authorizes it in the current turn.

Resources

• references/repositories.json: dated catalog of the ten source repositories, licenses, strengths, risks, and source entry points.
• references/motion-routing.md: decision guide and product-ready architecture patterns.
• references/quality-gates.md: implementation and live visual verification checklist.
• scripts/query_catalog.py: validate and search the repository catalog by natural-language needs or tags.