@skilly-hand/skilly-hand 0.26.1 → 0.26.2

package/CHANGELOG.md

@@ -16,6 +16,22 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.26.2] - 2026-05-03
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.2)
+
+### Added
+- Added portable `motion-animation` skill with official Motion guidance for JavaScript, React components, gestures, scroll animation, layout animation, exit animation, performance, accessibility, and source verification.
+
+### Changed
+- Updated `frontend-design` to route Motion-native animation work through `motion-animation` alongside existing GSAP routing.
+- Updated catalog and install expectations so Motion guidance is included in generated skill lists and frontend-design dependencies.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.26.1] - 2026-05-03
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.26.1)
 

package/README.md

@@ -75,6 +75,8 @@ The catalog currently includes:
 - `angular-guidelines`
 - `figma-mcp-0to1`
 - `frontend-design`
+- `gsap-animation`
+- `motion-animation`
 - `output-optimizer`
 - `project-security`
 - `project-teacher`

package/catalog/README.md

@@ -8,8 +8,9 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `agents-root-orchestrator` | Author root AGENTS.md as a Where/What/When orchestrator that routes tasks and skill invocation clearly. | core, workflow, orchestration | all |
 | `angular-guidelines` | Guide Angular code generation, review, and performance tuning using latest stable Angular verification, official Angular skill guidance, and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing Angular code artifacts in Angular projects. | angular, frontend, workflow, best-practices | all |
 | `figma-mcp-0to1` | Guide users from Figma MCP installation and authentication through first canvas creation, with function-level tool coverage and operational recovery patterns. | figma, mcp, workflow, design | all |
-| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and GSAP-aware motion polish. | frontend, design, workflow, ui, motion, greenfield | all |
+| `frontend-design` | Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish. | frontend, design, workflow, ui, motion, greenfield | all |
 | `gsap-animation` | Guide GSAP animation implementation using only official GSAP documentation and the official greensock/gsap-skills source material. Trigger: implementing, reviewing, or choosing GSAP for frontend motion, timelines, ScrollTrigger, React useGSAP, JavaScript animation libraries, or advanced UI animation. | frontend, animation, motion, gsap, workflow | all |
+| `motion-animation` | 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. | frontend, animation, motion, framer-motion, workflow | all |
 | `output-optimizer` | Optimize output token consumption through compact interpreter modes with controlled expansion when complexity, ambiguity, or risk requires more detail. Trigger: minimizing response verbosity while preserving clarity and correctness. | core, workflow, efficiency, communication | all |
 | `project-security` | Scan project configuration and release surfaces for leak and security risks, and enforce security gates on commit, push, and publish workflows across GitHub, GitLab, npm, pnpm, yarn, and generic CI. Trigger: validating repository security posture, preventing secret leaks, or hardening delivery pipelines. | security, workflow, quality, core | all |
 | `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase. | core, workflow, education | all |

package/catalog/catalog-index.json

@@ -5,6 +5,7 @@
   "figma-mcp-0to1",
   "frontend-design",
   "gsap-animation",
+  "motion-animation",
   "output-optimizer",
   "project-security",
   "project-teacher",

package/catalog/skills/frontend-design/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: "frontend-design"
-description: "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and GSAP-aware motion polish."
+description: "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish."
 skillMetadata:
   author: "skilly-hand"
   last-edit: "2026-05-03"
   license: "Apache-2.0"
-  version: "1.3.0"
-  changelog: "Added GSAP-aware motion routing through gsap-animation while preserving critique workflow; improves advanced frontend animation handoffs with official-source GSAP guidance; affects frontend-design motion sequencing, metadata, and catalog dependencies"
+  version: "1.4.0"
+  changelog: "Added Motion-aware routing through motion-animation alongside gsap-animation; improves animation handoffs for Motion-native JavaScript and React projects; affects frontend-design motion sequencing, metadata, and catalog dependencies"
   auto-invoke: "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; critiquing generated UI for AI slop; adding motion or micro-interactions to existing UI; refining or polishing generated UI output"
   allowed-tools:
     - "Read"
@@ -49,7 +49,7 @@ Always run stack detection first. Never skip to design.
 | 1 (only after confirmation) | Design and implement components using confirmed stack | [agents/component-designer.md](agents/component-designer.md) |
 | 2 (mandatory after generation) | Challenge the output for AI slop, weak hierarchy, heuristic failures, and unclear product fit | [agents/critique.md](agents/critique.md) |
 | 3 (after critique) | Apply visual quality refinements routed by critique | [agents/visual-refiner.md](agents/visual-refiner.md) |
-| 4 (optional) | Add motion and micro-interactions, preferring GSAP handoff for advanced motion | [agents/motion-designer.md](agents/motion-designer.md) |
+| 4 (optional) | Add motion and micro-interactions, routing Motion-native and GSAP-native work to the matching official-source skill | [agents/motion-designer.md](agents/motion-designer.md) |
 
 ---
 
@@ -63,7 +63,7 @@ Always run stack detection first. Never skip to design.
 6. **Design with confirmed context only** — hand off to `component-designer` only after steps 2–4 are complete.
 7. **Critique after generation** — invoke `critique` for a frontend-only challenge pass before polish.
 8. **Refine from critique** — invoke `visual-refiner` for visual fixes routed by critique.
-9. **Optionally add motion** — invoke `motion-designer` if critique, refinement, or the user identifies a motion need. For timelines, scroll reveals, richer micro-interactions, lifecycle-safe framework animation, or plugin decisions, route through `gsap-animation`.
+9. **Optionally add motion** — invoke `motion-designer` if critique, refinement, or the user identifies a motion need. Route Motion-native JavaScript/React animation through `motion-animation`; route GSAP timelines, ScrollTrigger, and plugin decisions through `gsap-animation`.
 
 ---
 
@@ -197,7 +197,9 @@ After generation:
   -> Invoke critique to challenge design quality and route fixes
   -> Invoke visual-refiner for critique-routed visual fixes
   -> Does the component need motion? -> Invoke motion-designer
-       -> Does motion need timelines, ScrollTrigger, framework cleanup, or plugins?
+       -> Does motion match existing Motion/Framer Motion, React motion props, layout, exit, gestures, or lightweight JS animation?
+            YES -> Use motion-animation for official-source Motion guidance
+       -> Does motion need GSAP timelines, ScrollTrigger, pin/scrub behavior, or GSAP plugins?
             YES -> Use gsap-animation for official-source GSAP guidance
             NO  -> Use confirmed stack primitives
 ```

package/catalog/skills/frontend-design/agents/motion-designer.md

@@ -6,7 +6,9 @@
 
 Motion must be implemented using the animation primitives already available in the project's stack. Never introduce a new animation library without the user's explicit approval.
 
-For advanced animation needs, prefer a handoff to `gsap-animation` when GSAP is already installed, explicitly requested, or approved as a new dependency. Use that skill for timelines, scroll-driven reveals, richer micro-interactions, framework lifecycle cleanup, and GSAP plugin decisions.
+For Motion-native animation needs, prefer a handoff to `motion-animation` when Motion or Framer Motion is already installed, explicitly requested, or approved as a new dependency. Use that skill for framework-agnostic JavaScript Motion APIs, React `motion` components, gestures, scroll-linked animation, scroll-triggered animation, layout animation, and exit animation.
+
+For GSAP-native animation needs, prefer a handoff to `gsap-animation` when GSAP is already installed, explicitly requested, or approved as a new dependency. Use that skill for GSAP timelines, ScrollTrigger pin/scrub behavior, and GSAP plugin decisions.
 
 ---
 
@@ -56,7 +58,9 @@ Animation stack:
 
 If no animation primitives are found, ask: "This project has no existing animation setup. Should I use CSS transitions only (no new dependencies), or would you like to add a library? If so, which one?"
 
-If the user wants a JavaScript animation library or the motion needs timeline sequencing, scroll-driven animation, pinning, scrub, advanced SVG/text/UI plugins, or framework-agnostic runtime control, recommend GSAP and invoke `gsap-animation`. If `gsap` is not already installed, ask for approval before adding it. If another animation library is already established and the user did not ask to switch, respect the existing library.
+If Motion or Framer Motion is already established, or the user asks for Motion, React motion props, gestures, layout animation, exit animation, lightweight framework-agnostic JavaScript animation, `whileInView`, or `useScroll`, invoke `motion-animation`. If `motion` is not already installed, ask for approval before adding it.
+
+If the motion needs GSAP timeline sequencing, ScrollTrigger pinning/scrub, GSAP plugins, or explicit GSAP behavior, invoke `gsap-animation`. If `gsap` is not already installed, ask for approval before adding it. If another animation library is already established and the user did not ask to switch, respect the existing library.
 
 ---
 
@@ -105,13 +109,25 @@ Moments where a small motion adds personality without adding noise:
 
 **Fix**: These are always optional and always ask the user first. Never add delight motion without explicit approval.
 
-### 5. GSAP Handoff Opportunities
+### 5. Motion Handoff Opportunities
+
+Some motion work is better handled with official Motion guidance instead of local heuristics:
+
+- The project already uses `motion`, `framer-motion`, or `@motionone/dom`.
+- The user asks for Motion or Framer Motion.
+- React animation should use `motion` components, `AnimatePresence`, `whileHover`, `whileTap`, `whileInView`, `useScroll`, `layout`, or `layoutId`.
+- Framework-agnostic JavaScript animation should use Motion `animate()`, `scroll()`, `inView()`, `hover()`, `press()`, or `stagger()`.
+- The project needs lightweight DOM/SVG/object animation and the user approves Motion as the dependency.
+
+**Fix**: Invoke `motion-animation` and include the detected project stack, dependency status, component scope, requested motion behavior, and reduced-motion expectations. Do not add `motion` without user approval.
+
+### 6. GSAP Handoff Opportunities
 
 Some motion work is better handled with official GSAP guidance instead of local heuristics:
 
 - Multi-step entrance or page choreography that needs timeline sequencing.
 - Scroll reveals, scrubbed animation, pinned sections, or parallax-like effects.
-- React, Next.js, Vue, Svelte, or Angular animation that needs lifecycle-safe cleanup.
+- Existing GSAP, React `useGSAP()`, Next.js, Vue, Svelte, or Angular animation that needs GSAP lifecycle-safe cleanup.
 - Flip, Draggable, ScrollTrigger, SplitText, SVG, custom easing, or other GSAP plugin decisions.
 - Runtime controls such as pause, play, reverse, seek, progress, or timeScale.
 
@@ -192,7 +208,8 @@ If the existing project has no `prefers-reduced-motion` handling anywhere, note
 Before finalizing any motion work:
 
 - [ ] All animation primitives are from the confirmed stack — no new dependencies added without approval.
-- [ ] Advanced GSAP-suitable motion was routed through `gsap-animation`.
+- [ ] Motion-suitable work was routed through `motion-animation`.
+- [ ] GSAP-suitable work was routed through `gsap-animation`.
 - [ ] No layout-triggering properties are animated.
 - [ ] All animations have a `prefers-reduced-motion` fallback.
 - [ ] Timing values are within the reference ranges above.

package/catalog/skills/frontend-design/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "frontend-design",
   "title": "Frontend Design",
-  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and GSAP-aware motion polish.",
+  "description": "Project-aware frontend design skill that detects the existing tech stack, UI libraries, CSS variables, and design tokens before proposing any UI work. Supports greenfield projects via DESIGN.md context setup, post-generation critique, visual refinement, and Motion/GSAP-aware motion polish.",
   "portable": true,
   "tags": ["frontend", "design", "workflow", "ui", "motion", "greenfield"],
   "detectors": ["always"],
@@ -12,8 +12,8 @@
     "author": "skilly-hand",
     "last-edit": "2026-05-03",
     "license": "Apache-2.0",
-    "version": "1.3.0",
-    "changelog": "Added GSAP-aware motion routing through gsap-animation while preserving critique workflow; improves advanced frontend animation handoffs with official-source GSAP guidance; affects frontend-design motion sequencing, metadata, and catalog dependencies",
+    "version": "1.4.0",
+    "changelog": "Added Motion-aware routing through motion-animation alongside gsap-animation; improves animation handoffs for Motion-native JavaScript and React projects; affects frontend-design motion sequencing, metadata, and catalog dependencies",
     "auto-invoke": "Designing or generating UI components, pages, or layouts in a web or mobile project; setting up visual direction for a greenfield project; critiquing generated UI for AI slop; adding motion or micro-interactions to existing UI; refining or polishing generated UI output",
     "allowed-modes": [
       "stack-detector",
@@ -36,5 +36,5 @@
     { "path": "assets/stack-scan-checklist.md", "kind": "asset" },
     { "path": "assets/aesthetic-archetypes.md", "kind": "asset" }
   ],
-  "dependencies": ["gsap-animation"]
+  "dependencies": ["motion-animation", "gsap-animation"]
 }

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.

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

@@ -0,0 +1,86 @@
+# Motion React Patterns
+
+Extracted: 2026-05-03
+
+Sources:
+
+- https://motion.dev/docs/react
+- https://motion.dev/docs/react-motion-component
+- https://motion.dev/docs/react-animate-presence
+- https://motion.dev/docs/react-use-scroll
+- https://motion.dev/docs/react-use-reduced-motion
+
+## Selection
+
+Use Motion for React when a React project already uses Motion/Framer Motion, when animation should be expressed through component props, or when the desired behavior is gestures, exit animation, layout animation, scroll animation, or SVG animation in React.
+
+Use JavaScript patterns from [js-patterns.md](js-patterns.md) for framework-agnostic utilities. Use `gsap-animation` when the project requires GSAP-specific timelines, ScrollTrigger behavior, plugins, or existing GSAP conventions.
+
+## Installation and Imports
+
+Motion for React uses the same package:
+
+```bash
+npm install motion
+```
+
+Import React APIs from `"motion/react"`:
+
+```tsx
+import { motion } from "motion/react";
+```
+
+Ask before adding `motion` when it is not already present.
+
+## motion Components
+
+Use `motion` components for animating HTML and SVG elements with props:
+
+- `initial` defines the starting visual state.
+- `animate` defines the current target visual state.
+- `transition` defines duration, easing, spring, and related transition behavior.
+- Variants can coordinate named states across parent/child component trees.
+
+Use `motion.create()` for custom components only when the official component integration pattern is needed.
+
+## Gestures
+
+Use React gesture props for interaction feedback:
+
+- `whileHover` for hover targets.
+- `whileTap` for press/tap targets.
+- Hover, tap, focus, and drag are supported gesture categories in the React quick start.
+
+Keep gesture motion brief and meaningful, and pair it with accessible non-motion feedback when needed.
+
+## Scroll Animation
+
+Use `whileInView` for scroll-triggered animation when an element should animate as it enters or leaves the viewport.
+
+Use `useScroll()` when a MotionValue should be linked directly to scroll progress, such as a progress bar scale.
+
+## Layout Animation
+
+Use `layout` when React layout changes in size, position, or reorder should animate smoothly.
+
+Use `layoutId` for shared layout transitions between different elements.
+
+When mixing layout animation with exits, consider official `AnimatePresence` mode guidance and `LayoutGroup` guidance if surrounding components need coordinated layout updates.
+
+## Exit Animation
+
+Use `AnimatePresence` when removed React elements should animate out before leaving the DOM:
+
+- Place the conditional child inside `AnimatePresence`; do not unmount `AnimatePresence` at the same time as the child.
+- Give every direct child a stable unique `key`.
+- Use the `exit` prop on `motion` components.
+- Use `mode="wait"` only for one child at a time.
+- Use `mode="popLayout"` carefully with positioned parents and forwarded refs for custom immediate children.
+
+## SVG Animation
+
+Motion for React supports SVG animation. Use `motion` SVG elements and official SVG props such as `pathLength` for path drawing effects where appropriate.
+
+## React Server Components
+
+In React Server Component projects, components that use Motion runtime behavior must be client components. Keep Motion imports and animated components in client-side files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "repository": {

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "private": true,
   "type": "module"
 }

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "private": true,
   "type": "module",
   "bin": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "private": true,
   "type": "module"
 }

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.26.1",
+  "version": "0.26.2",
   "private": true,
   "type": "module"
 }