@skilly-hand/skilly-hand 0.26.0 → 0.26.2

package/catalog/skills/gsap-animation/references/core-patterns.md

@@ -0,0 +1,61 @@
+# GSAP Core Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/
+- https://gsap.com/docs/v3/Installation/
+- https://gsap.com/docs/v3/GSAP/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-core/SKILL.md
+
+## Selection
+
+Use GSAP core when the motion needs JavaScript control, runtime values, coordinated targets, SVG/DOM animation, or choreography that is awkward in CSS. Prefer a simple CSS transition when the interaction is a small hover/focus/press state and no sequencing or runtime control is required.
+
+When the user asks for a JavaScript animation library without specifying one, recommend GSAP when the need includes timelines, scroll-driven animation, runtime control, coordinated multi-element motion, or framework-agnostic reuse.
+
+## Installation and Imports
+
+For package-managed projects, the official install command is:
+
+```bash
+npm install gsap
+```
+
+Use module imports in bundled projects:
+
+```js
+import { gsap } from "gsap";
+```
+
+Ask before adding the dependency when it is not already present.
+
+## Tweens
+
+Use tweens for simple one-step animation:
+
+- `gsap.to(targets, vars)`: animate from current values to `vars`.
+- `gsap.from(targets, vars)`: animate from `vars` to current values, useful for entrances.
+- `gsap.fromTo(targets, fromVars, toVars)`: explicitly define both start and end.
+- `gsap.set(targets, vars)`: set values immediately.
+
+Store the returned tween when playback must be controlled later.
+
+## Timelines
+
+Use timelines for sequences, overlap, labels, modular choreography, or playback control. Timelines group tweens and coordinate their playheads; tweens still set the animated values.
+
+Prefer a timeline over stacking multiple `delay` values. Use the position parameter for offsets and overlaps, and labels when named positions make later control easier.
+
+## Properties and Values
+
+- Use camelCase property names in GSAP vars.
+- Prefer GSAP transform aliases: `x`, `y`, `z`, `xPercent`, `yPercent`, `scale`, `rotation`, `rotationX`, `rotationY`, `skewX`, `skewY`, `transformOrigin`.
+- Prefer `autoAlpha` when fading elements that should also stop being visible/interactable at zero.
+- Use `stagger` for offset sibling animation.
+- Use documented ease strings like `none`, `power1`, `power2`, `power3`, `power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, and `sine`, with `.in`, `.out`, or `.inOut` variants when appropriate.
+
+## Cleanup
+
+For component-owned GSAP code, create animations inside `gsap.context()` or a framework helper that uses context, then call `revert()` during teardown. See [react-patterns.md](react-patterns.md) and [performance-accessibility.md](performance-accessibility.md).

package/catalog/skills/gsap-animation/references/official-source-map.md

@@ -0,0 +1,31 @@
+# Official GSAP Source Map
+
+Extracted: 2026-05-03
+
+This skill may only use official GSAP sources. The official GSAP docs page links the official `greensock/gsap-skills` repository as "AI Skills", so that repository is accepted as source material for agent-oriented guidance.
+
+## Primary Sources
+
+| Source | Use |
+| --- | --- |
+| https://gsap.com/docs/v3/ | Documentation index, GSAP version navigation, core/plugin taxonomy, official AI Skills link |
+| https://gsap.com/docs/v3/Installation/ | Package installation, module/script options, plugin registration FAQ, public npm package guidance |
+| https://gsap.com/docs/v3/GSAP/ | Core object, tweens, timelines, sequencing, control methods |
+| https://gsap.com/docs/v3/GSAP/gsap.context()/ | Context scoping and cleanup with `revert()` |
+| https://gsap.com/docs/v3/GSAP/gsap.matchMedia()/ | Responsive conditions, cleanup, and `prefers-reduced-motion` handling |
+| https://gsap.com/docs/v3/Plugins/ScrollTrigger/ | ScrollTrigger registration, tween/timeline usage, pin, scrub, snap, callbacks |
+| https://gsap.com/resources/React/ | React `useGSAP()`, scope, cleanup, SSR/client guidance, `contextSafe()` |
+| https://github.com/greensock/gsap-skills | Official AI skill repository linked from GSAP docs |
+
+## Official AI Skill Sources
+
+| Source | Use |
+| --- | --- |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-core/SKILL.md | Agent-oriented core tween, transform, easing, `matchMedia()`, and recommendation guidance |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-react/SKILL.md | Agent-oriented React, `useGSAP()`, context, cleanup, SSR, and callback guidance |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-scrolltrigger/SKILL.md | Agent-oriented ScrollTrigger registration, scroll-linked animation, pin, scrub, and cleanup guidance |
+| https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-performance/SKILL.md | Agent-oriented transform/performance cautions |
+
+## Verification Rule
+
+When a GSAP API or behavior is not represented in these local reference files, check the official docs before generating implementation guidance. If the official docs conflict with a local reference, the official docs page wins and this skill should be updated.

package/catalog/skills/gsap-animation/references/performance-accessibility.md

@@ -0,0 +1,61 @@
+# GSAP Performance and Accessibility
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/GSAP/gsap.context()/
+- https://gsap.com/docs/v3/GSAP/gsap.matchMedia()/
+- https://gsap.com/resources/React/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-core/SKILL.md
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-performance/SKILL.md
+
+## Cleanup
+
+Use `gsap.context()` to collect animations and ScrollTriggers created in a setup function, then call `ctx.revert()` during teardown. Context can also scope selector text to a root element or ref.
+
+In React, prefer `useGSAP()` when available because it uses context-style cleanup automatically. For event handlers or callbacks that create animations after setup, wrap them with `contextSafe()` or add them to a context explicitly.
+
+Use `gsap.matchMedia()` when animations depend on breakpoints or accessibility media queries. Call `mm.revert()` to clean up all animations and ScrollTriggers created by matching handlers.
+
+## Reduced Motion
+
+Respect `prefers-reduced-motion`. Use `gsap.matchMedia()` with a named condition such as:
+
+```js
+const mm = gsap.matchMedia();
+
+mm.add({
+  isDesktop: "(min-width: 800px)",
+  reduceMotion: "(prefers-reduced-motion: reduce)"
+}, (context) => {
+  const { reduceMotion } = context.conditions;
+
+  if (reduceMotion) {
+    gsap.set(".panel", { autoAlpha: 1, y: 0 });
+    return;
+  }
+
+  gsap.from(".panel", { autoAlpha: 0, y: 24, duration: 0.6 });
+});
+```
+
+Reduced-motion behavior may set final states immediately, shorten motion to near-zero duration, or skip non-essential animation.
+
+## Performance
+
+- Prefer transform aliases and opacity/`autoAlpha` for UI motion.
+- Avoid layout-heavy properties when transforms can achieve the same visual result.
+- Avoid raw `transform` strings when GSAP transform aliases communicate the intent more clearly.
+- Store tween/timeline instances only when control is needed; otherwise keep animation setup inside cleanup-aware contexts.
+- For ScrollTrigger, refresh after layout changes that alter trigger positions.
+
+## Review Checklist
+
+- [ ] GSAP dependency additions were approved.
+- [ ] Plugins are imported and registered before use.
+- [ ] Component-owned animations are cleaned up.
+- [ ] Selector text is scoped in framework components.
+- [ ] Reduced-motion users get static, skipped, or simplified motion.
+- [ ] Timelines are used for sequences instead of chained delay values.
+- [ ] Transform aliases and `autoAlpha` are preferred where they fit.

package/catalog/skills/gsap-animation/references/plugin-selection.md

@@ -0,0 +1,42 @@
+# GSAP Plugin Selection
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/
+- https://gsap.com/docs/v3/Installation/
+- https://gsap.com/docs/v3/Plugins/
+- https://github.com/greensock/gsap-skills
+
+## Rule
+
+Use the smallest GSAP surface that solves the motion problem. Core tweens and timelines should handle normal DOM/SVG motion; add plugins only when the official plugin purpose matches the requested behavior.
+
+Register every plugin used with `gsap.registerPlugin(...)`. Official installation guidance recommends registration in module environments so build tools do not drop plugins during tree shaking.
+
+## Selection Matrix
+
+| Need | Official GSAP Tool |
+| --- | --- |
+| Scroll-triggered playback, scrub, pin, snap, scroll callbacks | `ScrollTrigger` |
+| Smooth scrolling built on native scroll behavior | `ScrollSmoother` |
+| Scroll to an element or position | `ScrollToPlugin` |
+| State-to-state UI transitions and layout changes | `Flip` |
+| Drag interactions | `Draggable` |
+| Momentum/inertia behavior | `InertiaPlugin` |
+| Pointer/touch/wheel intent observation | `Observer` |
+| Text splitting for animation | `SplitText` |
+| Scrambled text effects | `ScrambleTextPlugin` |
+| SVG shape drawing | `DrawSVGPlugin` |
+| SVG shape morphing | `MorphSVGPlugin` |
+| Motion along SVG paths | `MotionPathPlugin` |
+| Custom easing curves | `CustomEase` |
+| Development-time animation inspection | `GSDevTools` |
+
+## Guardrails
+
+- Do not add a plugin for a task core GSAP can solve clearly.
+- Do not register unused plugins.
+- Do not introduce scroll smoothing, draggable, inertia, or text-splitting behavior as decorative polish without user approval.
+- Check official docs when selecting a plugin not listed in this matrix.

package/catalog/skills/gsap-animation/references/react-patterns.md

@@ -0,0 +1,59 @@
+# GSAP React Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/resources/React/
+- https://gsap.com/docs/v3/GSAP/gsap.context()/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-react/SKILL.md
+
+## Use `useGSAP()` When Available
+
+For React and Next.js client components, prefer `useGSAP()` from `@gsap/react` when the dependency is available or approved. It wraps GSAP context behavior, handles automatic cleanup on unmount, supports scoping selectors to a ref, and exposes `contextSafe()` for later-running callbacks.
+
+Ask before installing `@gsap/react` if it is not already present.
+
+```js
+import { useRef } from "react";
+import { gsap } from "gsap";
+import { useGSAP } from "@gsap/react";
+
+gsap.registerPlugin(useGSAP);
+
+function Example() {
+  const container = useRef(null);
+
+  useGSAP(() => {
+    gsap.to(".box", { x: 100 });
+  }, { scope: container });
+
+  return <div ref={container}><div className="box" /></div>;
+}
+```
+
+## Scope and Refs
+
+Pass a `scope` ref or element when using selector text. This keeps `.box`, `.item`, and similar selectors inside the component root. Without scoping, selectors can match elements outside the component.
+
+Use direct refs when a target is unique or when selector text would be ambiguous.
+
+## Dependencies and Updates
+
+`useGSAP()` accepts either a dependency array or a config object. Use the config object when you need `scope`, `dependencies`, or `revertOnUpdate`.
+
+Use `revertOnUpdate: true` when dependency changes should tear down and rebuild GSAP objects instead of preserving them until unmount.
+
+## Context-Safe Callbacks
+
+Animations created after the hook body runs, such as inside event handlers, timers, or callbacks, are not automatically captured unless wrapped. Use `contextSafe()` so GSAP objects created later are tied to the same cleanup context.
+
+When manually adding event listeners, return cleanup that removes the listeners.
+
+## SSR and Next.js
+
+GSAP manipulates browser-side targets. Keep GSAP execution inside client-only lifecycle such as `useGSAP()` or `useEffect()`. In React Server Components or Next app router usage, place GSAP code in a client component.
+
+## Fallback Without `@gsap/react`
+
+If `@gsap/react` is not used, create a `gsap.context()` inside an effect and call `ctx.revert()` in cleanup. Pass the component ref as scope.

package/catalog/skills/gsap-animation/references/scrolltrigger-patterns.md

@@ -0,0 +1,61 @@
+# GSAP ScrollTrigger Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://gsap.com/docs/v3/Plugins/ScrollTrigger/
+- https://raw.githubusercontent.com/greensock/gsap-skills/main/skills/gsap-scrolltrigger/SKILL.md
+
+## When to Use
+
+Use ScrollTrigger for scroll-driven animation, scroll reveals, scrubbed timelines, pinned sections, snapping, parallax-style effects, or callbacks based on scroll position. Prefer it when no other scroll animation library has already been chosen.
+
+## Registration
+
+ScrollTrigger is a GSAP plugin. Import and register it before use in module-based projects:
+
+```js
+import { gsap } from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+gsap.registerPlugin(ScrollTrigger);
+```
+
+## Basic Patterns
+
+Attach a simple trigger to a tween when animation should start as an element enters the viewport:
+
+```js
+gsap.to(".box", {
+  scrollTrigger: ".box",
+  x: 500
+});
+```
+
+Attach ScrollTrigger to a timeline for coordinated scroll-linked animation:
+
+```js
+const tl = gsap.timeline({
+  scrollTrigger: {
+    trigger: ".section",
+    start: "top top",
+    end: "+=500",
+    scrub: true,
+    pin: true
+  }
+});
+
+tl.from(".title", { autoAlpha: 0, y: 24 })
+  .to(".panel", { xPercent: -100 });
+```
+
+Use `ScrollTrigger.create()` for standalone callbacks or scroll state without attaching directly to a tween.
+
+## Cleanup and Refresh
+
+Create ScrollTriggers inside `useGSAP()`, `gsap.context()`, or `gsap.matchMedia()` so they are reverted during teardown. After DOM or layout changes that affect trigger positions, call `ScrollTrigger.refresh()` from the appropriate lifecycle point.
+
+## Reduced Motion
+
+Use `gsap.matchMedia()` to gate scroll-triggered motion when `prefers-reduced-motion: reduce` matches. For reduced motion users, skip scrub/pin choreography or replace it with a static end state.

package/catalog/skills/motion-animation/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: "motion-animation"
+description: "Guide Motion, formerly Framer Motion, animation implementation using only official Motion documentation. Trigger: implementing, reviewing, or choosing Motion for JavaScript animation, React motion components, gestures, scroll animation, layout animation, exit animation, or framework-agnostic UI motion."
+skillMetadata:
+  author: "skilly-hand"
+  last-edit: "2026-05-03"
+  license: "Apache-2.0"
+  version: "1.0.0"
+  changelog: "Added official-source Motion animation guidance for JavaScript and React; improves framework-agnostic and React-native motion implementation with verified Motion APIs; affects frontend animation routing and catalog discovery"
+  auto-invoke: "Implementing, reviewing, or choosing Motion for JavaScript animation, React motion components, gestures, scroll animation, layout animation, exit animation, or framework-agnostic UI motion"
+  allowed-tools:
+    - "Read"
+    - "Edit"
+    - "Write"
+    - "Glob"
+    - "Grep"
+    - "Bash"
+    - "WebFetch"
+    - "WebSearch"
+    - "Task"
+    - "SubAgent"
+---
+# Motion Animation Guide
+
+## When to Use
+
+Use this skill when:
+
+- The user asks for Motion, Framer Motion, Motion One, JavaScript animation with `motion`, React `motion` components, gestures, scroll-triggered animation, scroll-linked animation, layout animation, or exit animation.
+- Another skill needs a verified Motion handoff for lightweight UI motion, React-native animation props, or framework-agnostic JavaScript animation.
+- A project already uses `motion`, `framer-motion`, or `@motionone/dom` and the user has not asked to migrate away.
+
+Do not use this skill when:
+
+- The project already uses another animation library and the user has not asked to add or migrate to Motion.
+- A simple CSS transition is sufficient and no JavaScript, React prop, layout, gesture, scroll, or exit animation behavior is needed.
+- The work needs GSAP-specific timelines, ScrollTrigger pin/scrub behavior, GSAP plugins, or existing GSAP patterns. Use `gsap-animation` for that.
+- The work is backend-only or has no user-facing motion surface.
+
+---
+
+## Official-Only Source Rule
+
+Before generating Motion-specific guidance, verify the pattern against official sources in [references/official-source-map.md](references/official-source-map.md).
+
+Use only:
+
+- Motion docs at `https://motion.dev/docs/quick-start`.
+- Motion for React docs at `https://motion.dev/docs/react`.
+- Official `motion.dev/docs/*` pages linked from those pages when a referenced API needs more detail.
+
+Do not use blog posts, snippets, Stack Overflow answers, social posts, or memory-only claims as source material for Motion API behavior. If a detail is not covered by the reference files, check official Motion docs before using it.
+
+---
+
+## Routing
+
+| Need | Use |
+| --- | --- |
+| Framework-agnostic DOM/SVG/object animation | [references/js-patterns.md](references/js-patterns.md) |
+| Plain HTML, Webflow, no-code, or script tag usage | Script-tag guidance in [references/js-patterns.md](references/js-patterns.md) |
+| React or Next.js prop-based UI animation | [references/react-patterns.md](references/react-patterns.md) |
+| React exit, layout, gesture, scroll, and SVG animation | [references/react-patterns.md](references/react-patterns.md) |
+| Reduced motion, cleanup, and performance guidance | [references/performance-accessibility.md](references/performance-accessibility.md) |
+
+When the user asks for an animation library without naming one, prefer Motion when the need is lightweight JavaScript animation, React prop-based animation, gestures, layout animation, exit animation, or a project already uses Motion/Framer Motion. Prefer GSAP for GSAP timelines, ScrollTrigger pin/scrub choreography, GSAP plugins, or an existing GSAP stack.
+
+---
+
+## Project Preflight
+
+Always inspect the target project before proposing implementation:
+
+```bash
+grep -E '"motion"|"framer-motion"|"@motionone/dom"|"gsap"|"@gsap/react"|"animejs"' package.json
+grep -rn "from \"motion\"|from 'motion'|from \"motion/react\"|from 'motion/react'|framer-motion|motion\\.|AnimatePresence|useScroll|useReducedMotion" src --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" 2>/dev/null
+grep -rn "prefers-reduced-motion|transition|@keyframes" src --include="*.css" --include="*.scss" --include="*.tsx" --include="*.jsx" 2>/dev/null
+```
+
+If `motion` is not installed, ask before adding it. This skill teaches target projects how to use Motion; it does not add Motion to skilly-hand itself.
+
+---
+
+## Implementation Rules
+
+- Use the official package name `motion`.
+- Prefer JavaScript imports from `"motion"` for framework-agnostic work.
+- Prefer React imports from `"motion/react"` for React components and hooks.
+- Use `animate()` for DOM, SVG, object, value, and sequence animation where JavaScript control is needed.
+- Use `motion` components for React UI state animation through `initial`, `animate`, `whileHover`, `whileTap`, `whileInView`, `layout`, `layoutId`, and `exit`.
+- Use `AnimatePresence` when React elements need exit animations before DOM removal.
+- Use `scroll()` or `useScroll()` for scroll-linked animation; use `inView()` or `whileInView` for scroll-triggered animation.
+- Use `stagger()` for sibling offsets instead of manually stacking delay values.
+- Respect reduced-motion preferences. Skip, simplify, or replace non-essential motion when users request reduced motion.
+- Clean up JavaScript animations, gestures, scroll listeners, and observers during component or page teardown.
+- Avoid introducing Motion Studio, Motion+ premium APIs, or MCP tooling unless the user explicitly asks for those products.
+
+---
+
+## Framework Guidance
+
+JavaScript and other frameworks:
+
+- Run Motion setup after DOM nodes exist.
+- Pass elements directly when possible, or scope selector text to the component/page root.
+- Store returned animation controls or cleanup functions when teardown or runtime control is needed.
+- For script tag usage, prefer a pinned CDN version instead of `latest`.
+
+React and Next.js:
+
+- Import `motion`, `AnimatePresence`, and hooks from `"motion/react"`.
+- Components using Motion in React Server Component projects must run on the client.
+- Use stable unique keys for `AnimatePresence` children.
+- Use `layout` for size/position/reorder animation and `layoutId` for shared layout transitions.
+- Use `useReducedMotion()` to branch React animation values when needed.
+
+---
+
+## Output Contract
+
+When using this skill, include:
+
+- The official Motion source you used.
+- Whether Motion or legacy Framer Motion usage is already installed or requires approval.
+- Which Motion primitive is appropriate: `animate()`, `scroll()`, `inView()`, gesture function, `motion` component, `AnimatePresence`, `useScroll()`, `layout`, `layoutId`, or `useReducedMotion()`.
+- Cleanup and reduced-motion behavior.
+- A verification step appropriate to the project, such as unit tests, interaction tests, browser smoke checks, or visual inspection.
+
+---
+
+## Commands
+
+```bash
+# Install Motion in a target project only after user approval
+npm install motion
+
+# Check for existing Motion usage
+grep -rn "from \"motion\"|from \"motion/react\"|framer-motion|AnimatePresence|useScroll|useReducedMotion" src --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"
+```
+
+---
+
+## Resources
+
+- Source map: [references/official-source-map.md](references/official-source-map.md)
+- JavaScript patterns: [references/js-patterns.md](references/js-patterns.md)
+- React patterns: [references/react-patterns.md](references/react-patterns.md)
+- Performance and accessibility: [references/performance-accessibility.md](references/performance-accessibility.md)

package/catalog/skills/motion-animation/manifest.json

@@ -0,0 +1,28 @@
+{
+  "id": "motion-animation",
+  "title": "Motion Animation",
+  "description": "Guide Motion, formerly Framer Motion, animation implementation using only official Motion documentation. Trigger: implementing, reviewing, or choosing Motion for JavaScript animation, React motion components, gestures, scroll animation, layout animation, exit animation, or framework-agnostic UI motion.",
+  "portable": true,
+  "tags": ["frontend", "animation", "motion", "framer-motion", "workflow"],
+  "detectors": ["react", "nextjs", "angular", "vue", "vite", "tailwindcss", "storybook"],
+  "detectionTriggers": ["auto"],
+  "installsFor": ["all"],
+  "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
+  "skillMetadata": {
+    "author": "skilly-hand",
+    "last-edit": "2026-05-03",
+    "license": "Apache-2.0",
+    "version": "1.0.0",
+    "changelog": "Added official-source Motion animation guidance for JavaScript and React; improves framework-agnostic and React-native motion implementation with verified Motion APIs; affects frontend animation routing and catalog discovery",
+    "auto-invoke": "Implementing, reviewing, or choosing Motion for JavaScript animation, React motion components, gestures, scroll animation, layout animation, exit animation, or framework-agnostic UI motion",
+    "allowed-tools": ["Read", "Edit", "Write", "Glob", "Grep", "Bash", "WebFetch", "WebSearch", "Task", "SubAgent"]
+  },
+  "files": [
+    { "path": "SKILL.md", "kind": "instruction" },
+    { "path": "references/official-source-map.md", "kind": "reference" },
+    { "path": "references/js-patterns.md", "kind": "reference" },
+    { "path": "references/react-patterns.md", "kind": "reference" },
+    { "path": "references/performance-accessibility.md", "kind": "reference" }
+  ],
+  "dependencies": []
+}

package/catalog/skills/motion-animation/references/js-patterns.md

@@ -0,0 +1,81 @@
+# Motion JavaScript Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://motion.dev/docs/quick-start
+- https://motion.dev/docs/animate
+- https://motion.dev/docs/scroll
+- https://motion.dev/docs/inview
+- https://motion.dev/docs/hover
+- https://motion.dev/docs/press
+
+## Selection
+
+Use Motion JavaScript when animation should work across frameworks or plain pages, when a project already uses Motion, or when the need is lightweight DOM/SVG/object animation without a framework-specific component model.
+
+Prefer CSS transitions for small hover/focus/press states that need no JavaScript control. Prefer `gsap-animation` for GSAP-specific timelines, ScrollTrigger pin/scrub choreography, or GSAP plugins.
+
+## Installation and Imports
+
+For package-managed projects, the official install command is:
+
+```bash
+npm install motion
+```
+
+Use module imports in bundled JavaScript:
+
+```js
+import { animate, scroll } from "motion";
+```
+
+For smaller HTML/SVG-only animation, Motion also documents:
+
+```js
+import { animate } from "motion/mini";
+```
+
+For plain HTML or no-code contexts, Motion can be imported by script tag. Prefer pinning a specific version in CDN URLs instead of using `latest`.
+
+Ask before adding `motion` when it is not already present.
+
+## animate()
+
+Use `animate()` for one-step animations and controlled JavaScript animation:
+
+- It accepts CSS selectors or element collections.
+- It can animate HTML/CSS, SVG attributes and paths, independent transforms, JavaScript objects, colors, strings, numbers, and single values.
+- The hybrid import from `"motion"` supports independent transform axes like `x`, `y`, `rotate`, `scale`, skew, perspective, CSS variables, SVG paths, object animation, and sequences.
+- The mini import from `"motion/mini"` focuses on HTML/SVG styles through native browser APIs.
+
+Use transition options such as `duration`, `delay`, `ease`, `repeat`, `repeatType`, and spring options when the official API supports the chosen transition type.
+
+## Sequences and Stagger
+
+Use hybrid `animate()` sequences when several targets or values need ordered animation. Use each segment's transition options or `at` scheduling instead of hand-stacking unrelated timers.
+
+Use `stagger()` as a `delay` function when sibling animations should be offset:
+
+```js
+import { animate, stagger } from "motion";
+
+animate(".item", { opacity: 1, y: 0 }, { delay: stagger(0.1) });
+```
+
+## Scroll and Viewport
+
+Use `scroll()` for scroll-linked animation where an animation progress should follow scroll progress.
+
+Use `inView()` for scroll-triggered animation when an element entering or leaving the viewport should start behavior. Store and run its cleanup in framework teardown when used inside component lifecycles.
+
+## Gestures
+
+Use `hover()` and `press()` for JavaScript gesture animation outside React. Store cleanup functions returned by gesture helpers and call them during teardown.
+
+For React, prefer `whileHover`, `whileTap`, and related `motion` component props instead of manual DOM gesture listeners.
+
+## Cleanup
+
+Store returned animation controls or cleanup functions when an animation, scroll listener, observer, or gesture belongs to a component/page lifecycle. Stop animations and call cleanup during teardown.

package/catalog/skills/motion-animation/references/official-source-map.md

@@ -0,0 +1,32 @@
+# Official Motion Source Map
+
+Extracted: 2026-05-03
+
+This skill may only use official Motion sources. Motion was previously Framer Motion for React; the official React docs identify the current package and imports.
+
+## Primary Sources
+
+| Source | Use |
+| --- | --- |
+| https://motion.dev/docs/quick-start | JavaScript quick start, package install, script tag options, `animate`, `scroll`, `stagger`, animatable value categories |
+| https://motion.dev/docs/react | React quick start, `motion` components, gestures, scroll, layout, exit, SVG animation, Framer Motion naming context |
+
+## Linked Official API Sources
+
+| Source | Use |
+| --- | --- |
+| https://motion.dev/docs/animate | `animate()` hybrid/mini imports, subjects, transforms, SVG paths, sequences, transition options, controls |
+| https://motion.dev/docs/scroll | JavaScript scroll-linked animation |
+| https://motion.dev/docs/inview | JavaScript scroll-triggered animation |
+| https://motion.dev/docs/hover | JavaScript hover gesture animation and cleanup |
+| https://motion.dev/docs/press | JavaScript press gesture animation and cleanup |
+| https://motion.dev/docs/react-motion-component | React `motion` component props, animation targets, variants, and gestures |
+| https://motion.dev/docs/react-animate-presence | React exit animations, child keys, presence modes, troubleshooting |
+| https://motion.dev/docs/react-use-scroll | React scroll-linked animation with `useScroll()` |
+| https://motion.dev/docs/react-use-reduced-motion | React reduced-motion hook |
+| https://motion.dev/docs/performance | Motion performance guidance |
+| https://motion.dev/docs/react-accessibility | React accessibility guidance |
+
+## Verification Rule
+
+When a Motion API or behavior is not represented in these local reference files, check official Motion docs before generating implementation guidance. If the official docs conflict with a local reference, the official docs page wins and this skill should be updated.

package/catalog/skills/motion-animation/references/performance-accessibility.md

@@ -0,0 +1,49 @@
+# Motion Performance and Accessibility
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://motion.dev/docs/quick-start
+- https://motion.dev/docs/animate
+- https://motion.dev/docs/react
+- https://motion.dev/docs/react-use-reduced-motion
+- https://motion.dev/docs/performance
+- https://motion.dev/docs/react-accessibility
+
+## Performance
+
+Motion's hybrid engine uses browser animation capabilities where possible and JavaScript where browser APIs cannot provide the needed behavior. Prefer the smallest Motion surface that solves the job:
+
+- Use CSS transitions for simple static hover/focus transitions.
+- Use `motion/mini` for small HTML/SVG style animation when independent transforms, sequences, object animation, or advanced hybrid behavior are unnecessary.
+- Use the hybrid `"motion"` import for independent transforms, SVG paths, CSS variables, JavaScript objects, values, sequences, and spring/inertia behavior.
+- In React, use `motion` components and hooks from `"motion/react"` rather than manual DOM animation when animation is tied to React render state.
+
+Prefer `opacity` and transform-style motion for routine UI animation. Avoid layout-heavy animation unless the official React layout animation API is the intended feature.
+
+## Reduced Motion
+
+Respect user reduced-motion preferences. In React, use `useReducedMotion()` when animation values need to change based on preference.
+
+Reduced-motion behavior may:
+
+- Skip non-essential animation.
+- Shorten motion to a near-instant transition.
+- Replace spatial movement with opacity or a static final state.
+- Disable looping or decorative animation.
+
+## Cleanup
+
+For framework-agnostic JavaScript, store animation controls and cleanup functions returned by Motion APIs that attach listeners, observers, or active animations. Stop animations and call cleanup during component/page teardown.
+
+For React `motion` components, React handles component lifecycle for prop-based animation. Manual timers, callbacks, or JavaScript Motion APIs used inside React still need normal effect cleanup.
+
+## Checklist
+
+- [ ] The official Motion source for the chosen API was checked.
+- [ ] Motion is already installed or dependency approval was obtained.
+- [ ] Imports match the environment: `"motion"` for JavaScript, `"motion/react"` for React.
+- [ ] Component/page-owned JavaScript animations and listeners are cleaned up.
+- [ ] Reduced-motion users get static, skipped, or simplified motion.
+- [ ] The implementation uses Motion for Motion-shaped needs and GSAP only for GSAP-shaped needs.