@mehshekari/gsap-motion 2.1.0

package/skill/preset/scroll-storytelling.md

@@ -0,0 +1,176 @@
+# Scroll storytelling
+
+A pinned section where scrolling drives a sequence. The "Apple product page"
+pattern. Expensive in build time and in the visitor's attention, so it has to
+be carrying a story that genuinely has an order.
+
+Mechanics are in [scrolltrigger.md](../reference/scrolltrigger.md); this is how
+to compose one.
+
+## Decide the beats first
+
+Write them out before any code. Each beat is one idea, and scroll distance is
+your pacing:
+
+```text
+0.0 – 0.2   the product, whole
+0.2 – 0.45  it opens; the first claim arrives
+0.45 – 0.7  detail view; the second claim
+0.7 – 1.0   it closes; the CTA
+```
+
+Roughly 600–1000px of scroll per beat. Less and it flicks past; more and the
+visitor thinks the page is stuck.
+
+## One timeline, one trigger
+
+Every element in the sequence belongs to the same timeline. Separate triggers
+drift apart the moment you retime anything.
+
+```ts
+const tl = gsap.timeline({
+  defaults: { ease: "none" },        // scrubbed — the scrollbar owns the feel
+  scrollTrigger: {
+    trigger: section,
+    start: "top top",
+    end: "+=3000",
+    pin: true,
+    scrub: 1,
+    anticipatePin: 1,
+    invalidateOnRefresh: true,
+    markers: process.env.NODE_ENV === "development",
+  },
+});
+
+tl.addLabel("open")
+  .to("[data-lid]", { rotationX: -110, duration: 1 })
+  .from("[data-claim-1]", { autoAlpha: 0, y: 20, duration: 0.4 }, "open+=0.4")
+
+  .addLabel("detail")
+  .to("[data-claim-1]", { autoAlpha: 0, duration: 0.3 }, "detail")
+  .to("[data-product]", { scale: 1.6, x: "-20%", duration: 1 }, "detail")
+  .from("[data-claim-2]", { autoAlpha: 0, y: 20, duration: 0.4 }, "detail+=0.4");
+```
+
+`ease: "none"` on every child. Easing inside a scrubbed timeline fights the
+visitor's own scrolling and reads as lag — `scrub: 1` is where the smoothing
+belongs.
+
+## Horizontal
+
+```ts
+const panels = gsap.utils.toArray<HTMLElement>("[data-panel]");
+
+gsap.to(panels, {
+  xPercent: -100 * (panels.length - 1),
+  ease: "none",
+  scrollTrigger: {
+    trigger: track,
+    pin: true,
+    scrub: 1,
+    end: () => `+=${track.offsetWidth}`,
+    snap: { snapTo: 1 / (panels.length - 1), duration: 0.4 },
+    invalidateOnRefresh: true,
+  },
+});
+```
+
+`end` as a function is re-evaluated on refresh, which keeps it correct after a
+resize. `xPercent` avoids measuring widths.
+
+In RTL the direction inverts — `+100 *` rather than `-100 *`. Read `dir` from
+the document; see [project-rules.md](../reference/project-rules.md).
+
+Horizontal scroll costs the visitor their scroll intuition. Justify it with
+content that is genuinely a sequence.
+
+## Snapping
+
+```ts
+snap: { snapTo: "labels", duration: 0.4, ease: "power2.inOut", delay: 0.1 }
+```
+
+`"labels"` snaps to the timeline's own labels, which is why naming the beats
+pays off twice. Snapping suits discrete steps and fights continuous motion —
+do not snap a scrubbed camera move.
+
+## Progress
+
+A scrubbed indicator is cheap and orients the visitor inside a long pin:
+
+```ts
+.to("[data-progress]", { scaleX: 1, transformOrigin: "0% 50%" }, 0);
+```
+
+Placed at position `0` with the timeline's full duration, it tracks overall
+progress regardless of what else is happening.
+
+## Mobile
+
+**Do not scale the desktop sequence down.** A 3000px pin on a phone is a long
+time to be stuck, and pinning fights the address bar collapsing.
+
+```ts
+mm.add({ desktop: "(min-width: 768px)", mobile: "(max-width: 767px)" }, (c) => {
+  if (c.conditions!.mobile) {
+    // Each beat becomes its own in-view reveal. Same content, no pin.
+    gsap.utils.toArray("[data-beat]").forEach((beat) =>
+      gsap.from(beat as HTMLElement, {
+        autoAlpha: 0, y: 24,
+        scrollTrigger: { trigger: beat as HTMLElement, start: "top 75%" },
+      }),
+    );
+    return;
+  }
+  // the pinned sequence
+});
+```
+
+This is the single most important decision in this preset. A different strategy,
+not a smaller one.
+
+## Reduced motion
+
+Drop the pin and the scrub. Each beat appears on entry:
+
+```ts
+if (reduced) {
+  gsap.set("[data-claim-1], [data-claim-2]", { autoAlpha: 1, y: 0 });
+  return;
+}
+```
+
+Scroll-scrubbed pinning is a textbook vestibular trigger — the content moves
+while the page does not. The content must still be reachable and readable.
+
+## Image sequences
+
+Frame-by-frame scrubbing looks expensive because it is. Before committing:
+30–120 frames at a sensible resolution, preloaded, drawn to a `<canvas>` — not
+120 `<img>` elements.
+
+```ts
+const frame = { i: 0 };
+gsap.to(frame, {
+  i: images.length - 1,
+  snap: "i",
+  ease: "none",
+  scrollTrigger: { trigger: section, start: "top top", end: "+=3000",
+                   pin: true, scrub: 1 },
+  onUpdate: () => ctx.drawImage(images[frame.i], 0, 0),
+});
+```
+
+Do not start this until every frame is decoded, or the first scroll shows gaps.
+On a slow connection, offer a static hero instead.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Pin does nothing | an ancestor has `overflow: hidden` |
+| Motion lags behind scroll | easing inside a scrubbed timeline |
+| Beats drift after an edit | separate triggers instead of one timeline |
+| Wrong positions after load | images without dimensions — refresh |
+| Unusable on mobile | desktop sequence scaled instead of replaced |
+| Flicker when the pin engages | missing `anticipatePin` |

package/skill/reference/accessibility.md

@@ -0,0 +1,143 @@
+# Accessibility
+
+Reduced motion is the part people get wrong, and they get it wrong in the same
+way: they treat it as an off switch.
+
+## Reduced motion is a design
+
+`prefers-reduced-motion: reduce` is set by people who get motion sickness,
+vertigo, or migraines from movement — and by people who simply find it
+distracting. Vestibular triggers are specific: **large travel, parallax,
+zooming, spinning, and anything the visitor did not initiate.** A cross-fade is
+usually fine. A modal scaling from 0.96 to 1 is usually fine.
+
+So the question is never "animate or not". It is: *what was this motion saying,
+and how do I say it without the travel?*
+
+| Full | Reduced | Why |
+|---|---|---|
+| Section slides up 60px and fades | fades over 200ms | the arrival still reads |
+| Logo draws itself over 1.2s | appears drawn, holds | the brand moment survives |
+| Loader spins | pulses opacity gently | "still working" is the message |
+| Parallax layers | static, correctly composed | parallax says nothing essential |
+| Scroll-scrubbed sequence | each state on entry, no scrub | the content still arrives |
+| Card lifts and scales on hover | border and shadow change | the affordance is what matters |
+| Page transition wipe | instant swap | it was continuity decoration |
+
+**A loader with nothing moving reads as a page that has hung** — which is the
+one thing a loader exists to rule out. Keep a gentle opacity pulse.
+
+## Implementing it
+
+`gsap.matchMedia` handles the preference *changing mid-session*, which a plain
+check does not:
+
+```ts
+const mm = gsap.matchMedia();
+
+mm.add(
+  {
+    motion: "(prefers-reduced-motion: no-preference)",
+    reduced: "(prefers-reduced-motion: reduce)",
+  },
+  (context) => {
+    const { reduced } = context.conditions as Record<string, boolean>;
+
+    if (reduced) {
+      gsap.set("[data-item]", { autoAlpha: 1, y: 0 });
+      return;
+    }
+
+    gsap.from("[data-item]", { y: 60, autoAlpha: 0, stagger: 0.06 });
+  },
+);
+
+```
+
+Built inside a `useGSAP` body this needs no explicit teardown — `matchMedia`
+registers with the active context and is reverted with it.
+
+Everything built in the losing branch is reverted when the preference flips.
+Without `matchMedia`, a visitor who turns reduced motion on mid-session keeps
+the animation they asked to stop.
+
+**The reduced branch must still set the end state.** A `from` tween that never
+runs leaves the element at its authored start — invisible. This is the most
+common reduced-motion bug, and it hides content rather than just skipping
+motion.
+
+## Announcement
+
+- A loader that blocks content: `role="status"` and an accessible name. It
+  announces politely without stealing focus.
+- Decorative artwork: `aria-hidden="true"`, and make sure nothing inside it is
+  focusable.
+- **Never both.** An `sr-only` label inside an `aria-hidden` container is never
+  read — it is dead markup.
+- An overlay covering the page: the content beneath is still in the accessibility
+  tree. For a transient splash that is the right outcome — the visitor reaches
+  the content immediately. For a modal it is not, and you need `inert` or
+  `aria-modal` with focus management.
+
+## Focus
+
+- Never destroy the focus ring. A transform that moves an element out from under
+  its outline, or an `overflow: hidden` ancestor clipping it mid-animation, both
+  count.
+- Hover and focus should produce the same visual state. An effect that only
+  exists on `:hover` is invisible to a keyboard.
+- An animation must not move a focused element out of the viewport.
+- If an animation reveals interactive content, it must not be focusable before
+  it is visible. `autoAlpha` handles this; plain `opacity` does not.
+
+## Timing
+
+- Nothing essential should depend on motion. If the animation is the only thing
+  that says "saved", that is a failure for anyone who cannot see it.
+- Anything auto-playing for longer than 5 seconds and looping needs a way to
+  stop it — WCAG 2.2.2. A marquee of logos qualifies.
+- Do not delay content the visitor came for behind an entrance. An intro that
+  cannot be skipped needs a hard time ceiling, and dismissal should be a race
+  against that ceiling rather than a sequence that can hang.
+
+## Flashing
+
+Nothing should flash more than three times per second — WCAG 2.3.1. Rapid
+opacity or colour cycling, scramble effects at high speed, and strobing hover
+states all get close.
+
+## Touch
+
+- Gate hover effects on `(hover: hover) and (pointer: fine)`. On touch,
+  `:hover` sticks after a tap and the state never clears.
+- A cursor follower on a touch device is dead weight sitting in a corner.
+- Anything that only responds to drag needs a keyboard path to the same outcome.
+
+## A marker that means "current"
+
+A pill, underline or tint whose *position* says which tab, section or page is
+current is a user-interface component, not decoration. WCAG 1.4.11 asks 3:1
+against what it sits on. Motion makes a marker easy to notice while it travels;
+at rest it has to be readable without that.
+
+Brand fills rarely manage it on a light ground. `#FFD400` on white is 1.43:1,
+and the soft brand tints are lower still. That does not rule a tint out — it
+rules out the tint being the **only** thing that says "current". Carry the
+state twice more:
+
+- **In the label.** The current item keeps a colour that meets text contrast
+  even while the marker has moved off to follow the pointer.
+- **In `aria-current`.** `page` for a route, `location` for a section inside
+  the page being read. This is the part that survives with no eyes on it.
+
+## Checklist
+
+- Is there a reduced-motion branch, and does it still communicate?
+- Does the reduced branch set the end state, not just skip the tween?
+- Is `matchMedia` used, so a mid-session change is honoured?
+- Is the artwork either announced or hidden — and not both?
+- Does hover have a focus equivalent?
+- Is the focus ring intact throughout?
+- Can a long loop be stopped?
+- Does anything essential exist only as motion?
+- Does a "current" marker reach 3:1 — or is the state also in the label and `aria-current`?

package/skill/reference/core-gsap.md

@@ -0,0 +1,233 @@
+# Core GSAP
+
+The API you actually reach for. Plugin-specific surfaces live in their own
+files; this is what is true everywhere.
+
+## Imports
+
+Every plugin is in the public package. Import each from its own subpath so the
+bundler can drop the ones a route does not use — never `gsap/all`.
+
+```ts
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { DrawSVGPlugin } from "gsap/DrawSVGPlugin";
+```
+
+Register once, at module scope of the file that owns the animation:
+
+```ts
+gsap.registerPlugin(useGSAP, ScrollTrigger, DrawSVGPlugin);
+```
+
+Registering `useGSAP` alongside them is what makes GSAP warn about a missing
+plugin instead of silently ignoring the property that needed it.
+
+Available here, all free, all typed: `ScrollTrigger`, `ScrollSmoother`,
+`ScrollToPlugin`, `Observer`, `Draggable`, `InertiaPlugin`, `Flip`, `SplitText`,
+`ScrambleTextPlugin`, `TextPlugin`, `DrawSVGPlugin`, `MorphSVGPlugin`,
+`MotionPathPlugin`, `MotionPathHelper`, `CustomEase`, `CustomWiggle`,
+`CustomBounce`, `Physics2DPlugin`, `PhysicsPropsPlugin`, `GSDevTools`,
+`PixiPlugin`, `EaselPlugin`, `CSSRulePlugin`, `EasePack`.
+
+## The four verbs
+
+```ts
+gsap.to(target, vars);              // from current state to vars
+gsap.from(target, vars);            // from vars to current state
+gsap.fromTo(target, fromVars, to);  // explicit both ends
+gsap.set(target, vars);             // instant, no tween
+```
+
+`from` is convenient and it is also the usual cause of a flash: the element
+paints at its natural state before the tween applies. `fromTo` with an explicit
+start, or a `gsap.set` before, is what removes that. In React, `useGSAP` runs in
+a layout effect so the set lands before paint — that is most of why it matters.
+
+## Targets
+
+A selector string, an element, a ref's `.current`, an array, or an object.
+Inside a `useGSAP` or `gsap.context` scope, selector strings resolve against the
+scope rather than the document — which is the whole reason to use one.
+
+```ts
+gsap.to("[data-card]", { ... });     // scoped, when inside useGSAP
+gsap.to(ref.current, { ... });       // explicit
+gsap.to({ v: 0 }, { v: 100, onUpdate });  // tween a plain object
+```
+
+That last form is how you animate anything GSAP cannot touch directly — a
+canvas value, a counter, a Three.js material, a CSS variable on a distant node.
+
+## Properties
+
+Transforms are first-class and composable, and GSAP writes them as one matrix
+rather than fighting over `transform`:
+
+```ts
+{ x: 100, y: -20, xPercent: -50, rotation: 45, scale: 1.2, skewX: 8,
+  transformOrigin: "50% 100%" }
+```
+
+`xPercent`/`yPercent` are percentages of the element's own size, which is what
+centres something without knowing its dimensions.
+
+`autoAlpha` is `opacity` plus `visibility` — it hides the element from pointer
+events at 0, which plain `opacity` does not.
+
+CSS variables work, and are the cheapest way to drive something whose styling
+lives in CSS:
+
+```ts
+gsap.to(root, { "--glow-strength": 1, duration: 0.6 });
+```
+
+## Useful vars
+
+```ts
+{
+  duration, delay, ease,
+  repeat: -1,            // forever
+  yoyo: true,            // reverse on alternate repeats
+  repeatDelay: 0.4,
+  stagger: 0.06,         // or { each, amount, from, ease }
+  overwrite: "auto",     // kill conflicting tweens on the same props
+  paused: true,
+  onComplete, onUpdate, onStart,
+}
+```
+
+`overwrite: "auto"` is the fix for the classic hover bug where leaving and
+re-entering fast leaves an element halfway. Use it on anything an event can
+retrigger.
+
+## `gsap.utils`
+
+Small functions that remove most of the arithmetic from animation code.
+
+```ts
+gsap.utils.clamp(0, 1, v);
+gsap.utils.mapRange(0, 500, 0, 1, scrollY);   // remap one range onto another
+gsap.utils.interpolate("#000", "#fff", 0.5);
+gsap.utils.wrap(0, 10, 13);                   // → 3, for infinite loops
+gsap.utils.snap(0.1, 0.34);                   // → 0.3
+gsap.utils.random(-20, 20, 1);
+gsap.utils.toArray("[data-card]");            // NodeList → real array
+gsap.utils.selector(ref);                     // scoped selector function
+gsap.utils.shuffle(items);
+```
+
+`mapRange` and `wrap` are the two that most often replace ten lines of
+hand-rolled maths in a scroll or marquee.
+
+## `quickTo` and `quickSetter`
+
+For values driven by a high-frequency event — pointer move, scroll, rAF —
+creating a tween per event allocates garbage and fights itself.
+
+```ts
+const moveX = gsap.quickTo(el, "x", { duration: 0.5, ease: "power3" });
+const moveY = gsap.quickTo(el, "y", { duration: 0.5, ease: "power3" });
+
+// In the handler — reuses one tween, no allocation:
+moveX(e.clientX);
+moveY(e.clientY);
+```
+
+`quickSetter` is the same idea with no interpolation, for when you are already
+smoothing the value yourself:
+
+```ts
+const setX = gsap.quickSetter(el, "x", "px");
+```
+
+This is the single most important performance tool for pointer work. See
+[interaction.md](interaction.md).
+
+## `matchMedia`
+
+Different strategies per breakpoint or preference, with automatic teardown when
+the condition stops matching.
+
+```ts
+const mm = gsap.matchMedia();
+
+mm.add(
+  {
+    desktop: "(min-width: 768px)",
+    mobile: "(max-width: 767px)",
+    reduced: "(prefers-reduced-motion: reduce)",
+  },
+  (context) => {
+    const { desktop, reduced } = context.conditions as Record<string, boolean>;
+    if (reduced) { /* the reduced design */ return; }
+    gsap.to(el, { x: desktop ? 200 : 60 });
+  },
+);
+
+// Teardown, when it was not created inside a context:
+mm.revert();
+```
+
+Everything created inside the callback is reverted when the condition stops
+matching. A plain `window.matchMedia` check leaves the first animation running
+forever when a visitor turns reduced motion on mid-session, or rotates a tablet.
+
+**Created inside a `useGSAP` or `gsap.context` body, it reverts itself with
+that context** — `MatchMedia`'s constructor registers with whatever context is
+active (verified against gsap 3.15), and `Context.add` makes itself active while your
+function runs. An explicit `mm.revert()` there is redundant, not wrong. Created
+outside one — module scope, a plain `useEffect` — it is yours to revert. See
+[react-nextjs.md](react-nextjs.md).
+
+## `context`
+
+Scopes selectors and collects everything for teardown. In React you get this
+through `useGSAP` and rarely call it directly.
+
+```ts
+const ctx = gsap.context(() => {
+  gsap.to(".card", { y: 0 });      // resolved inside `root`
+}, root);
+
+ctx.revert();                       // undoes everything, restores inline styles
+```
+
+`revert()` restores original inline styles; `kill()` only stops the tweens. For
+a component unmount you almost always want `revert`.
+
+**A scope does not reach inside plugin config.** `motionPath.path` and
+`morphSVG.shape` are resolved by the plugin against the whole document, so a
+fixed id in a component rendered twice makes both instances drive the first
+one's geometry — with no error. Namespace those ids per instance.
+
+## Control
+
+```ts
+tl.play(); tl.pause(); tl.reverse(); tl.restart();
+tl.progress(0.5);        // jump
+tl.timeScale(2);         // twice as fast, live
+tl.seek("label");
+```
+
+Tweening a timeline's own progress is how you smooth a jumpy external value:
+
+```ts
+gsap.to(tl, { progress: uploaded, duration: 0.4, overwrite: true });
+```
+
+## Easing
+
+Named: `power1`–`power4`, `back`, `elastic`, `bounce`, `circ`, `expo`, `sine`,
+`steps(n)`, `none`, each with `.in`/`.out`/`.inOut`. Which to pick is a craft
+question — see [motion-design.md](motion-design.md).
+
+`CustomEase` takes an SVG path and is free:
+
+```ts
+CustomEase.create("brand", "M0,0 C0.16,1 0.3,1 1,1");
+gsap.to(el, { y: 0, ease: "brand" });
+```
+
+`CustomWiggle` and `CustomBounce` register named eases the same way, for shake
+and impact without hand-built keyframes.