@mehshekari/gsap-motion 3.1.0 → 3.2.0

package/skill/reference/interaction.md

@@ -1,183 +1,183 @@
-# Interaction
-
-Pointer-driven motion. The engineering constraint is that these fire at 60–120Hz,
-so the wrong architecture costs a frame budget rather than a few milliseconds.
-
-Every interaction has three parts, and the third is the one people skip:
-
-```text
-input → response → recovery
-```
-
-The recovery is what makes it feel physical. A button that springs toward the
-cursor and snaps back on leave feels broken; the same button easing back over
-0.6s feels alive.
-
-## The rule: `quickTo`, not a tween per event
-
-```ts
-// Wrong — allocates a tween per pointer event, and they fight each other
-onMouseMove = (e) => gsap.to(el, { x: e.clientX, duration: 0.5 });
-
-// Right — one tween, retargeted
-const moveX = gsap.quickTo(el, "x", { duration: 0.5, ease: "power3" });
-const moveY = gsap.quickTo(el, "y", { duration: 0.5, ease: "power3" });
-onMouseMove = (e) => { moveX(e.clientX); moveY(e.clientY); };
-```
-
-Create the `quickTo` functions once, inside the `useGSAP` body. This is the
-single most important performance decision in pointer work.
-
-## Magnetic element
-
-The element leans toward the cursor while it is near, and returns when it
-leaves.
-
-```ts
-const xTo = gsap.quickTo(el, "x", { duration: 0.6, ease: "power3" });
-const yTo = gsap.quickTo(el, "y", { duration: 0.6, ease: "power3" });
-
-const onMove = (e: PointerEvent) => {
-  const r = el.getBoundingClientRect();
-  xTo((e.clientX - (r.left + r.width / 2)) * 0.35);
-  yTo((e.clientY - (r.top + r.height / 2)) * 0.35);
-};
-
-const onLeave = () => { xTo(0); yTo(0); };
-```
-
-- **Strength 0.2–0.4.** Above that the element outruns the cursor and feels
-  unmoored.
-- **Measure in the handler, not once.** Scroll and layout change the rect. If
-  that shows up as cost, cache it on enter and invalidate on scroll.
-- **The hit area should be larger than the element** — a padded wrapper listens,
-  the inner element moves. That is what makes the pull feel like a field rather
-  than a hover state.
-
-## Cursor follower
-
-```ts
-const xTo = gsap.quickTo(dot, "x", { duration: 0.35, ease: "power3" });
-const yTo = gsap.quickTo(dot, "y", { duration: 0.35, ease: "power3" });
-
-window.addEventListener("pointermove", (e) => { xTo(e.clientX); yTo(e.clientY); });
-```
-
-- Two layers at different durations (0.1 and 0.5) give the trailing-ring look
-  without a trail of elements.
-- `pointer-events: none` on the follower, always.
-- **Only on devices that have a cursor.** Gate on
-  `(hover: hover) and (pointer: fine)` — a follower on a touch device is dead
-  weight and sits in the corner.
-- Hiding the native cursor is a real accessibility cost. Do it only if the
-  replacement is at least as legible over every surface, and never over text
-  inputs.
-
-## Observer
-
-One unified handler for wheel, touch, and pointer — the right tool when you want
-a gesture rather than a scroll position.
-
-```ts
-import { Observer } from "gsap/Observer";
-gsap.registerPlugin(Observer);
-
-const obs = Observer.create({
-  target: window,
-  type: "wheel,touch,pointer",
-  onUp: () => next(),
-  onDown: () => prev(),
-  tolerance: 10,
-  preventDefault: true,
-});
-
-obs.kill();   // only needed outside a useGSAP body — see react-nextjs.md
-```
-
-This is how full-screen section-snapping and swipe carousels are built without
-ScrollTrigger. `preventDefault: true` takes over native scrolling — a large
-commitment, and it must not trap a keyboard or screen-reader user.
-
-## Draggable and Inertia
-
-```ts
-import { Draggable } from "gsap/Draggable";
-import { InertiaPlugin } from "gsap/InertiaPlugin";
-gsap.registerPlugin(Draggable, InertiaPlugin);
-
-Draggable.create(el, {
-  type: "x",
-  bounds: container,
-  inertia: true,
-  snap: { x: (v) => Math.round(v / 320) * 320 },
-  onDragEnd() { /* ... */ },
-});
-```
-
-`inertia: true` gives the flick-and-settle that makes a drag feel native.
-`Draggable.create` returns instances — `.kill()` them on unmount.
-
-Anything draggable needs a keyboard path to the same outcome. A carousel that
-only responds to drag is unusable without a pointer.
-
-## Hover with a timeline
-
-Build once, play and reverse. Better than creating tweens per event, and the
-return matches the arrival for free.
-
-```ts
-const hover = gsap.timeline({ paused: true })
-  .to(el, { scale: 1.04, duration: 0.3, ease: "power2.out" })
-  .to(label, { y: -2, duration: 0.3 }, "<");
-
-onEnter = () => hover.play();
-onLeave = () => hover.reverse();
-```
-
-In React, if the timeline is built inside `useGSAP` and only *played* from the
-handler, no `contextSafe` is needed — see [react-nextjs.md](react-nextjs.md).
-
-## `overwrite: "auto"`
-
-The classic bug: enter, leave, enter fast, and the element sits halfway.
-Whatever retriggers needs `overwrite: "auto"` so the conflicting tween is killed
-rather than blended.
-
-## Spotlight
-
-A pointer-tracked gradient. Drive CSS variables rather than re-rendering:
-
-```ts
-const setX = gsap.quickSetter(card, "--spot-x", "px");
-const setY = gsap.quickSetter(card, "--spot-y", "px");
-```
-
-```css
-background: radial-gradient(
-  240px at var(--spot-x) var(--spot-y),
-  var(--glow), transparent 70%
-);
-```
-
-Cheap, and the styling stays in CSS where it can follow the theme.
-
-## Accessibility
-
-- **Everything reachable by pointer must be reachable by keyboard.** Hover state
-  and focus state should be the same visual.
-- Never destroy the focus ring with a transform that moves the element out from
-  under it.
-- Gate hover effects on `(hover: hover)`. On touch, `:hover` sticks after a tap.
-- Under `prefers-reduced-motion: reduce`, keep the state change and drop the
-  travel — see [accessibility.md](accessibility.md).
-
-## Failures
-
-| Symptom | Cause |
-|---|---|
-| Janky on move | a tween per event, or React state in the handler |
-| Element sticks halfway | missing `overwrite: "auto"` |
-| Magnetic pull feels wrong | strength too high, or rect measured once |
-| Follower stuck in a corner | mounted on a touch device |
-| Hover sticks after tap | no `(hover: hover)` gate |
-| Effects survive navigation | `Observer`/`Draggable` not killed, listeners not removed |
+# Interaction
+
+Pointer-driven motion. The engineering constraint is that these fire at 60–120Hz,
+so the wrong architecture costs a frame budget rather than a few milliseconds.
+
+Every interaction has three parts, and the third is the one people skip:
+
+```text
+input → response → recovery
+```
+
+The recovery is what makes it feel physical. A button that springs toward the
+cursor and snaps back on leave feels broken; the same button easing back over
+0.6s feels alive.
+
+## The rule: `quickTo`, not a tween per event
+
+```ts
+// Wrong — allocates a tween per pointer event, and they fight each other
+onMouseMove = (e) => gsap.to(el, { x: e.clientX, duration: 0.5 });
+
+// Right — one tween, retargeted
+const moveX = gsap.quickTo(el, "x", { duration: 0.5, ease: "power3" });
+const moveY = gsap.quickTo(el, "y", { duration: 0.5, ease: "power3" });
+onMouseMove = (e) => { moveX(e.clientX); moveY(e.clientY); };
+```
+
+Create the `quickTo` functions once, inside the `useGSAP` body. This is the
+single most important performance decision in pointer work.
+
+## Magnetic element
+
+The element leans toward the cursor while it is near, and returns when it
+leaves.
+
+```ts
+const xTo = gsap.quickTo(el, "x", { duration: 0.6, ease: "power3" });
+const yTo = gsap.quickTo(el, "y", { duration: 0.6, ease: "power3" });
+
+const onMove = (e: PointerEvent) => {
+  const r = el.getBoundingClientRect();
+  xTo((e.clientX - (r.left + r.width / 2)) * 0.35);
+  yTo((e.clientY - (r.top + r.height / 2)) * 0.35);
+};
+
+const onLeave = () => { xTo(0); yTo(0); };
+```
+
+- **Strength 0.2–0.4.** Above that the element outruns the cursor and feels
+  unmoored.
+- **Measure in the handler, not once.** Scroll and layout change the rect. If
+  that shows up as cost, cache it on enter and invalidate on scroll.
+- **The hit area should be larger than the element** — a padded wrapper listens,
+  the inner element moves. That is what makes the pull feel like a field rather
+  than a hover state.
+
+## Cursor follower
+
+```ts
+const xTo = gsap.quickTo(dot, "x", { duration: 0.35, ease: "power3" });
+const yTo = gsap.quickTo(dot, "y", { duration: 0.35, ease: "power3" });
+
+window.addEventListener("pointermove", (e) => { xTo(e.clientX); yTo(e.clientY); });
+```
+
+- Two layers at different durations (0.1 and 0.5) give the trailing-ring look
+  without a trail of elements.
+- `pointer-events: none` on the follower, always.
+- **Only on devices that have a cursor.** Gate on
+  `(hover: hover) and (pointer: fine)` — a follower on a touch device is dead
+  weight and sits in the corner.
+- Hiding the native cursor is a real accessibility cost. Do it only if the
+  replacement is at least as legible over every surface, and never over text
+  inputs.
+
+## Observer
+
+One unified handler for wheel, touch, and pointer — the right tool when you want
+a gesture rather than a scroll position.
+
+```ts
+import { Observer } from "gsap/Observer";
+gsap.registerPlugin(Observer);
+
+const obs = Observer.create({
+  target: window,
+  type: "wheel,touch,pointer",
+  onUp: () => next(),
+  onDown: () => prev(),
+  tolerance: 10,
+  preventDefault: true,
+});
+
+obs.kill();   // only needed outside a useGSAP body — see adapter/react.md
+```
+
+This is how full-screen section-snapping and swipe carousels are built without
+ScrollTrigger. `preventDefault: true` takes over native scrolling — a large
+commitment, and it must not trap a keyboard or screen-reader user.
+
+## Draggable and Inertia
+
+```ts
+import { Draggable } from "gsap/Draggable";
+import { InertiaPlugin } from "gsap/InertiaPlugin";
+gsap.registerPlugin(Draggable, InertiaPlugin);
+
+Draggable.create(el, {
+  type: "x",
+  bounds: container,
+  inertia: true,
+  snap: { x: (v) => Math.round(v / 320) * 320 },
+  onDragEnd() { /* ... */ },
+});
+```
+
+`inertia: true` gives the flick-and-settle that makes a drag feel native.
+`Draggable.create` returns instances — `.kill()` them on unmount.
+
+Anything draggable needs a keyboard path to the same outcome. A carousel that
+only responds to drag is unusable without a pointer.
+
+## Hover with a timeline
+
+Build once, play and reverse. Better than creating tweens per event, and the
+return matches the arrival for free.
+
+```ts
+const hover = gsap.timeline({ paused: true })
+  .to(el, { scale: 1.04, duration: 0.3, ease: "power2.out" })
+  .to(label, { y: -2, duration: 0.3 }, "<");
+
+onEnter = () => hover.play();
+onLeave = () => hover.reverse();
+```
+
+In React, if the timeline is built inside `useGSAP` and only *played* from the
+handler, no `contextSafe` is needed — see [react.md](../adapter/react.md).
+
+## `overwrite: "auto"`
+
+The classic bug: enter, leave, enter fast, and the element sits halfway.
+Whatever retriggers needs `overwrite: "auto"` so the conflicting tween is killed
+rather than blended.
+
+## Spotlight
+
+A pointer-tracked gradient. Drive CSS variables rather than re-rendering:
+
+```ts
+const setX = gsap.quickSetter(card, "--spot-x", "px");
+const setY = gsap.quickSetter(card, "--spot-y", "px");
+```
+
+```css
+background: radial-gradient(
+  240px at var(--spot-x) var(--spot-y),
+  var(--glow), transparent 70%
+);
+```
+
+Cheap, and the styling stays in CSS where it can follow the theme.
+
+## Accessibility
+
+- **Everything reachable by pointer must be reachable by keyboard.** Hover state
+  and focus state should be the same visual.
+- Never destroy the focus ring with a transform that moves the element out from
+  under it.
+- Gate hover effects on `(hover: hover)`. On touch, `:hover` sticks after a tap.
+- Under `prefers-reduced-motion: reduce`, keep the state change and drop the
+  travel — see [accessibility.md](accessibility.md).
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Janky on move | a tween per event, or React state in the handler |
+| Element sticks halfway | missing `overwrite: "auto"` |
+| Magnetic pull feels wrong | strength too high, or rect measured once |
+| Follower stuck in a corner | mounted on a touch device |
+| Hover sticks after tap | no `(hover: hover)` gate |
+| Effects survive navigation | `Observer`/`Draggable` not killed, listeners not removed |

package/skill/reference/routing.md

@@ -1,119 +1,119 @@
-# Routing
-
-What to load, and what to do when the request is a feeling rather than a
-command.
-
-## No argument
-
-Do not guess a target and do not invent an animation. Ask what should move, and
-offer the menu below — grouped, so the question is easy to answer.
-
-> What are we animating?
->
-> - **Entrance** — something appearing: a hero, a section, a list, an image
-> - **Scroll** — something driven by scroll position: a sequence, a pin, a
->   horizontal run
-> - **Interaction** — something answering the pointer: a button, a cursor, a
->   card
-> - **Continuous** — something always moving: a marquee, an orbit, ambient drift
-> - **Transition** — moving between two states: a route, a modal, a layout
-> - **Loading** — a loader, a progress indicator, a site intro
-> - **Existing** — something already animated that feels wrong, costs too much,
->   or should go
-
-## Classifying a description
-
-Most requests are a feeling, not a command. Classify, then route.
-
-| What they say | What they mean | Route to |
-|---|---|---|
-| "make it cinematic" | slow, weighted, sequenced, one thing at a time | `intro` · [cinematic](../preset/cinematic.md) |
-| "make it feel premium" | fewer moving parts, longer eases, no bounce | `tune` · [motion-design](motion-design.md) |
-| "make it feel alive" | ambient continuous motion under static content | `ambient` · [marquee](../preset/marquee.md) |
-| "make it pop / bolder" | more contrast in timing, not more elements moving | `tune` · [motion-design](motion-design.md) |
-| "like Apple" | scroll-scrubbed, pinned, one idea per screen | `scroll` · [scroll-storytelling](../preset/scroll-storytelling.md) |
-| "futuristic / technical" | scramble, draw-on, mechanical easing, grid reveals | `text` + `svg` |
-| "liquid / organic" | morph, path motion, overlapping soft easing | `svg` · [loader](../preset/loader.md) |
-| "something crazy" | layered techniques with one clear concept | see below |
-| "smooth image reveal" | clip-path or mask, not opacity | [reveal](../preset/reveal.md) |
-| "the hero is boring" | hierarchy problem before a motion problem | `tune`, then `reveal` |
-| "it feels janky" | cost or trigger problem | `audit` · [performance](performance.md) |
-
-### "Something crazy"
-
-A fade-and-scale is a failure of nerve; twelve techniques at once is a failure
-of taste. Pick **one concept** and let three techniques serve it. The concept is
-the thing you can say in a sentence — "the logo writes itself, then the dot that
-drew it runs off and writes the word" — and every technique either serves that
-sentence or is cut.
-
-## Load map
-
-The project's own rules come first, then the size tiers in SKILL.md, setup step
-3: a one-element change loads [motion-design](motion-design.md) and the
-command's own reference only. The table applies from component size up — a
-single hover takes [interaction](interaction.md) and nothing else from its row.
-
-| Request | Add |
-|---|---|
-| SVG draw / morph / path | [svg](svg.md), [timeline](timeline.md) |
-| Scroll sequence, pin, scrub | [scrolltrigger](scrolltrigger.md), [timeline](timeline.md), [performance](performance.md) |
-| Horizontal scroll | [scrolltrigger](scrolltrigger.md), [scroll-storytelling](../preset/scroll-storytelling.md) |
-| Text reveal, kinetic type | [text](text.md), [timeline](timeline.md) |
-| Magnetic, cursor, hover | [interaction](interaction.md), [performance](performance.md) |
-| Drag, flick, inertia | [interaction](interaction.md) |
-| Layout / shared element / modal | [flip](flip.md) |
-| Page or route transition | [flip](flip.md), [page-transition](../preset/page-transition.md), [react-nextjs](react-nextjs.md) or [frameworks](frameworks.md) |
-| Loader, splash, intro | [svg](svg.md), [timeline](timeline.md), [accessibility](accessibility.md) |
-| Marquee, orbit, ambient | [timeline](timeline.md), [performance](performance.md) |
-| Three.js / R3F | [three-r3f](three-r3f.md), [performance](performance.md) |
-| Audit an existing animation | [performance](performance.md), [accessibility](accessibility.md), [react-nextjs](react-nextjs.md) or [frameworks](frameworks.md) |
-| Retime / re-ease | [motion-design](motion-design.md) only |
-
-Do not load a domain file "for completeness". Loading `three-r3f.md` for a
-button hover is the failure this map exists to prevent.
-
-## `audit`
-
-**Run the checker first.** It is deterministic, it costs a second, and it finds
-the mechanical failures before you spend attention on them:
-
-```bash
-node .claude/skills/gsap-creative-animation/scripts/audit-gsap.mjs <path>
-```
-
-**When an animation is not visible, ask whether it was ever built.** Before
-touching timings or transforms, check that the code which creates it actually
-runs. Animation is routinely built behind a condition — an image decode race, a
-`ready.then()`, a ScrollTrigger that has not fired, a `matchMedia` branch that
-does not match, an early `return` on a missing ref — and a tween that was never
-created looks exactly like one that is mis-timed. A typical case: an image wipe
-added only once the image decodes inside a short budget. On a first visit the
-image is never cached, the branch never runs, and every hypothesis about the
-wipe's geometry is wasted effort.
-
-Then read for what it cannot see. Check in this order — the first two are where
-real bugs live:
-
-1. **Lifecycle** — is every animation inside a `useGSAP`/`gsap.context` scope?
-   Are ScrollTriggers killed? Are listeners removed? Does a `matchMedia` get
-   reverted? See [react-nextjs](react-nextjs.md).
-2. **Cost** — layout-triggering properties, per-frame React state, filters on
-   large areas, one ScrollTrigger per item where one would do. See
-   [performance](performance.md).
-3. **Reduced motion** — is there a branch, and does it still communicate?
-4. **Craft** — rhythm, easing on loops, contrast. See [motion-design](motion-design.md).
-
-Report findings most-severe first, with the file and line. Do not rewrite
-unless asked.
-
-## `strip`
-
-Removing motion is a legitimate outcome and often the right one. Cut an
-animation when it answers none of hierarchy, causality, continuity, state, or
-personality; when it delays content the visitor came for; when it repeats on
-every route and stopped being noticed on the second one; or when it exists
-because a plugin was available.
-
-Say what you removed and what it was costing. Do not replace it with a smaller
-animation unless the user asks.
+# Routing
+
+What to load, and what to do when the request is a feeling rather than a
+command.
+
+## No argument
+
+Do not guess a target and do not invent an animation. Ask what should move, and
+offer the menu below — grouped, so the question is easy to answer.
+
+> What are we animating?
+>
+> - **Entrance** — something appearing: a hero, a section, a list, an image
+> - **Scroll** — something driven by scroll position: a sequence, a pin, a
+>   horizontal run
+> - **Interaction** — something answering the pointer: a button, a cursor, a
+>   card
+> - **Continuous** — something always moving: a marquee, an orbit, ambient drift
+> - **Transition** — moving between two states: a route, a modal, a layout
+> - **Loading** — a loader, a progress indicator, a site intro
+> - **Existing** — something already animated that feels wrong, costs too much,
+>   or should go
+
+## Classifying a description
+
+Most requests are a feeling, not a command. Classify, then route.
+
+| What they say | What they mean | Route to |
+|---|---|---|
+| "make it cinematic" | slow, weighted, sequenced, one thing at a time | `intro` · [cinematic](../preset/cinematic.md) |
+| "make it feel premium" | fewer moving parts, longer eases, no bounce | `tune` · [motion-design](motion-design.md) |
+| "make it feel alive" | ambient continuous motion under static content | `ambient` · [marquee](../preset/marquee.md) |
+| "make it pop / bolder" | more contrast in timing, not more elements moving | `tune` · [motion-design](motion-design.md) |
+| "like Apple" | scroll-scrubbed, pinned, one idea per screen | `scroll` · [scroll-storytelling](../preset/scroll-storytelling.md) |
+| "futuristic / technical" | scramble, draw-on, mechanical easing, grid reveals | `text` + `svg` |
+| "liquid / organic" | morph, path motion, overlapping soft easing | `svg` · [loader](../preset/loader.md) |
+| "something crazy" | layered techniques with one clear concept | see below |
+| "smooth image reveal" | clip-path or mask, not opacity | [reveal](../preset/reveal.md) |
+| "the hero is boring" | hierarchy problem before a motion problem | `tune`, then `reveal` |
+| "it feels janky" | cost or trigger problem | `audit` · [performance](performance.md) |
+
+### "Something crazy"
+
+A fade-and-scale is a failure of nerve; twelve techniques at once is a failure
+of taste. Pick **one concept** and let three techniques serve it. The concept is
+the thing you can say in a sentence — "the logo writes itself, then the dot that
+drew it runs off and writes the word" — and every technique either serves that
+sentence or is cut.
+
+## Load map
+
+The project's own rules come first, then the size tiers in SKILL.md, setup step
+3: a one-element change loads [motion-design](motion-design.md) and the
+command's own reference only. The table applies from component size up — a
+single hover takes [interaction](interaction.md) and nothing else from its row.
+
+| Request | Add |
+|---|---|
+| SVG draw / morph / path | [svg](svg.md), [timeline](timeline.md) |
+| Scroll sequence, pin, scrub | [scrolltrigger](scrolltrigger.md), [timeline](timeline.md), [performance](performance.md) |
+| Horizontal scroll | [scrolltrigger](scrolltrigger.md), [scroll-storytelling](../preset/scroll-storytelling.md) |
+| Text reveal, kinetic type | [text](text.md), [timeline](timeline.md) |
+| Magnetic, cursor, hover | [interaction](interaction.md), [performance](performance.md) |
+| Drag, flick, inertia | [interaction](interaction.md) |
+| Layout / shared element / modal | [flip](flip.md) |
+| Page or route transition | [flip](flip.md), [page-transition](../preset/page-transition.md), this project's adapter |
+| Loader, splash, intro | [svg](svg.md), [timeline](timeline.md), [accessibility](accessibility.md) |
+| Marquee, orbit, ambient | [timeline](timeline.md), [performance](performance.md) |
+| Three.js / R3F | [three](../adapter/three.md) or [r3f](../adapter/r3f.md), [performance](performance.md) |
+| Audit an existing animation | [performance](performance.md), [accessibility](accessibility.md), this project's adapter |
+| Retime / re-ease | [motion-design](motion-design.md) only |
+
+Do not load a domain file "for completeness". Loading `adapter/three.md` for a
+button hover is the failure this map exists to prevent.
+
+## `audit`
+
+**Run the checker first.** It is deterministic, it costs a second, and it finds
+the mechanical failures before you spend attention on them:
+
+```bash
+node .claude/skills/gsap-creative-animation/scripts/audit-gsap.mjs <path>
+```
+
+**When an animation is not visible, ask whether it was ever built.** Before
+touching timings or transforms, check that the code which creates it actually
+runs. Animation is routinely built behind a condition — an image decode race, a
+`ready.then()`, a ScrollTrigger that has not fired, a `matchMedia` branch that
+does not match, an early `return` on a missing ref — and a tween that was never
+created looks exactly like one that is mis-timed. A typical case: an image wipe
+added only once the image decodes inside a short budget. On a first visit the
+image is never cached, the branch never runs, and every hypothesis about the
+wipe's geometry is wasted effort.
+
+Then read for what it cannot see. Check in this order — the first two are where
+real bugs live:
+
+1. **Lifecycle** — is every animation inside a `useGSAP`/`gsap.context` scope?
+   Are ScrollTriggers killed? Are listeners removed? Does a `matchMedia` get
+   reverted? See this project's adapter.
+2. **Cost** — layout-triggering properties, per-frame React state, filters on
+   large areas, one ScrollTrigger per item where one would do. See
+   [performance](performance.md).
+3. **Reduced motion** — is there a branch, and does it still communicate?
+4. **Craft** — rhythm, easing on loops, contrast. See [motion-design](motion-design.md).
+
+Report findings most-severe first, with the file and line. Do not rewrite
+unless asked.
+
+## `strip`
+
+Removing motion is a legitimate outcome and often the right one. Cut an
+animation when it answers none of hierarchy, causality, continuity, state, or
+personality; when it delays content the visitor came for; when it repeats on
+every route and stopped being noticed on the second one; or when it exists
+because a plugin was available.
+
+Say what you removed and what it was costing. Do not replace it with a smaller
+animation unless the user asks.

package/skill/reference/scrolltrigger.md

@@ -176,7 +176,7 @@ useGSAP(() => {
 
 After a route change in the App Router, the new page's layout is measured before
 images settle. `ScrollTrigger.refresh()` on mount is usually needed. See
-[react-nextjs.md](react-nextjs.md).
+[react.md](../adapter/react.md).
 
 ## Failures
 

package/skill/reference/svg.md

@@ -24,7 +24,7 @@ as JSX.
 
 Without them you end up at `querySelectorAll("path")[3]`, which breaks on the
 next export. Prefix them, and namespace per instance — see
-[react-nextjs.md](react-nextjs.md). For a set animated together, one
+[react.md](../adapter/react.md). For a set animated together, one
 `data-*` attribute beats a run of ids:
 
 ```tsx

package/skill/reference/timeline.md

@@ -103,7 +103,7 @@ onMouseLeave = () => hover.reverse();
 
 `reverse()` uses the same easing backwards, so the return matches the arrival
 without a second definition. In React, anything built outside the `useGSAP`
-body must go through `contextSafe` — see [react-nextjs.md](react-nextjs.md).
+body must go through `contextSafe` — see [react.md](../adapter/react.md).
 
 ## Holds