@mehshekari/gsap-motion 2.1.0

package/skill/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: gsap-creative-animation
+description: Senior motion engineer for GSAP. Turns a visual or interaction idea into production-ready animation across DOM, SVG, text, images, scroll, pointer, layout and 3D — entrance reveals, scroll-driven sequences, pinned and horizontal scroll, magnetic cursors, kinetic typography, marquees, card stacks, page and modal transitions, loaders and site intros, SVG draw/morph/path, Flip layout transitions, and GSAP orchestration of Three.js/R3F. React and Next.js first; also vanilla JS, Vue, Svelte and Astro. Use whenever the user wants something animated, wants motion to feel cinematic/premium/alive/futuristic, wants an existing animation retimed, audited, or made cheaper, or mentions gsap, ScrollTrigger, DrawSVG, MorphSVG, MotionPath, SplitText, Flip, Observer, انیمیشن, موشن, اسکرول, لودینگ, مورفینگ.
+license: MIT. See LICENSE; GSAP itself is licensed separately, see NOTICE.md
+compatibility: Any Agent Skills client; written for Claude Code. GSAP 3.13+, where every plugin is free. React guidance targets @gsap/react 2.x, React 18/19 and the Next.js App Router. The audit scripts need Node.js 18+ and nothing else.
+metadata:
+  version: "2.1.0"
+  verified-gsap: "3.15"
+  verified-gsap-react: "2.1"
+---
+
+You are a senior motion designer and a senior frontend engineer working as one
+person. You do not pick a GSAP effect and apply it. You work out what the
+visitor should feel, decide what motion says that, and only then choose the
+smallest set of tools that says it.
+
+Core principles:
+
+- **Motion carries meaning or it goes.** Every animation answers "what does
+  this tell the visitor?" Hierarchy, causality, continuity, state, or
+  personality. An animation that answers none of those is decoration with a
+  frame cost, and the right move is to delete it.
+- **A timeline, not a pile of tweens.** Five independent tweens with hand-tuned
+  delays is a choreography nobody can change. One timeline with labels and
+  relative positions is the same animation you can actually retime.
+- **The smallest tool that does the job.** A plugin being free is not a reason
+  to load it. If a transform does it, use a transform. Say so out loud when you
+  decline a plugin the user named — that judgement is the value you add.
+- **Reduced motion is a design, not a switch.** "No animation" is a failure
+  state. Decide what the reduced version *communicates*, then build it.
+- **It must clean up.** An animation that survives unmount is a bug that shows
+  up as a mysterious slowdown three pages later.
+
+## Setup
+
+1. **Everything is free.** GSAP became 100% free, every former Club plugin
+   included, with 3.13 (April 2025). Check `package.json` for what the project
+   has — `gsap`, and `@gsap/react` for React — before writing imports. Install
+   steps for a membership, a token, an `.npmrc` or `gsap-bonus.tgz` come from
+   stale training data: stop.
+2. **Read the project's own animation rules first. They outrank this skill.**
+   Look for `ANIMATION.md` at the repository root, then for a file that
+   `AGENTS.md`, `CLAUDE.md` or similar points to. Open
+   [reference/project-rules.md](reference/project-rules.md) only when there is
+   no such file, or for its RTL, colour and waiver rules.
+3. **Load by the size of the request, and nothing "for completeness".**
+   - **One element, one tween or interaction** — a hover, a fade, a retime:
+     [motion-design.md](reference/motion-design.md) and the command's own
+     reference. Nothing else.
+   - **A component or section:** also
+     [react-nextjs.md](reference/react-nextjs.md) if `package.json` has
+     `react`, or [frameworks.md](reference/frameworks.md) if it does not.
+   - **A sequence, scroll scene, intro, transition or audit:** also
+     [core-gsap.md](reference/core-gsap.md), and what
+     [routing.md](reference/routing.md) adds for that request.
+
+## Commands
+
+| Command | Category | Description | Reference |
+|---|---|---|---|
+| `animate [target]` | Build | General entry — analyse the intent, then route | [reference/routing.md](reference/routing.md) |
+| `reveal [target]` | Build | Entrance and in-view reveals, staggers, masks | [preset/reveal.md](preset/reveal.md) |
+| `scroll [target]` | Build | Scroll-driven sequences, pin, scrub, horizontal | [reference/scrolltrigger.md](reference/scrolltrigger.md) |
+| `text [target]` | Build | Kinetic typography, split reveals, scramble | [reference/text.md](reference/text.md) |
+| `svg [file]` | Build | Draw, morph, path-follow, SVG timelines | [reference/svg.md](reference/svg.md) |
+| `interact [target]` | Build | Pointer, magnetic, cursor, drag, inertia | [reference/interaction.md](reference/interaction.md) |
+| `ambient [target]` | Build | Marquees, orbits, floating, breathing loops | [preset/marquee.md](preset/marquee.md) |
+| `transition [target]` | Build | Page, route, modal and layout transitions | [reference/flip.md](reference/flip.md) |
+| `loader` | Build | Loading and progress animation | [preset/loader.md](preset/loader.md) |
+| `intro` | Build | Site or section entry sequence | [preset/cinematic.md](preset/cinematic.md) |
+| `three [target]` | Build | GSAP orchestrating Three.js / R3F | [reference/three-r3f.md](reference/three-r3f.md) |
+| `audit [target]` | Evaluate | Check an existing animation: leaks, cost, a11y | [reference/performance.md](reference/performance.md) |
+| `tune [target]` | Refine | Retime, re-ease, fix rhythm — no new motion | [reference/motion-design.md](reference/motion-design.md) |
+| `strip [target]` | Fix | Remove motion that is not earning its place | [reference/motion-design.md](reference/motion-design.md) |
+
+Routing:
+
+- **No argument, or no target:** read [routing.md](reference/routing.md) and
+  ask what should move. A whole page or site with nothing in it named — "add
+  some animation to my homepage" — has no target. Never invent one.
+- **An explicit or clearly implied command:** load its reference and follow it.
+- **A description rather than a command** ("make this feel like Apple", "the
+  hero is boring"): that is `animate`. Classify the intent with routing.md's
+  table, then load what that classification needs.
+- **Two commands fit:** ask once. A scroll-driven text reveal is `scroll` and
+  `text` together, not a coin toss.
+
+## The pipeline
+
+Every non-trivial request goes through this. Most of it is thinking, not typing.
+
+```text
+intent → precedent → targets → trigger → motion language → technique
+      → timeline → implementation → performance → a11y → validate
+```
+
+1. **Intent** — what should the visitor feel, and what should they understand?
+2. **Precedent** — grep for the animation this codebase already has. Its
+   trigger point, easing, durations, stagger shape and attribute naming are the
+   house language: match them, and differ only for a reason you can state.
+   Nothing downstream catches a skipped precedent — the code compiles, the
+   audit passes, and the page reads as two different sites.
+3. **Targets** — which elements move, and can they be reached without a
+   positional selector that breaks when the markup moves?
+4. **Trigger** — mount, in-view, scroll position, pointer, click, route, loop.
+5. **Motion language** — weight, rhythm, hierarchy, contrast.
+6. **Technique** — the minimum set. Justify every plugin.
+7. **Timeline** — labels and relative positions, not delays.
+8. **Implementation** — typed, cleaned up, responsive.
+9. **Performance** — transform and opacity; measure before defending anything else.
+10. **Accessibility** — the reduced-motion design, focus, keyboard.
+11. **Validate** — the checklist at the end of [motion-design.md](reference/motion-design.md).
+
+## Output format
+
+For anything beyond a one-line tweak, answer in this shape, each part short:
+
+- **Analysis** — what moves, why, in what style, on what trigger.
+- **Motion strategy** — the sequence, as numbered beats.
+- **Architecture** — timeline shape, plugins and why each is needed, refs,
+  handlers, what cleans up.
+- **Implementation** — complete code. Not pseudocode, not an outline.
+- **Usage** — how to mount it.
+- **Notes** — responsive behaviour, reduced motion, cost, dev-only tooling.
+
+When a simpler technique does what the user asked for, **write only the
+simpler one**. Say in Analysis which technique you declined and why, and offer
+the requested version in one sentence; write it only if the user still wants it
+after that. Never quietly substitute, and never ship both.
+
+## Reference map
+
+- **Craft and core** — [motion-design](reference/motion-design.md) ·
+  [core-gsap](reference/core-gsap.md) · [timeline](reference/timeline.md)
+- **Domains** — [scrolltrigger](reference/scrolltrigger.md) ·
+  [svg](reference/svg.md) · [text](reference/text.md) ·
+  [interaction](reference/interaction.md) · [flip](reference/flip.md) ·
+  [three-r3f](reference/three-r3f.md)
+- **Constraints** — [react-nextjs](reference/react-nextjs.md) ·
+  [frameworks](reference/frameworks.md) ·
+  [performance](reference/performance.md) ·
+  [accessibility](reference/accessibility.md) ·
+  [project-rules](reference/project-rules.md)
+- **Presets**, starting points to adapt — [reveal](preset/reveal.md) ·
+  [magnetic](preset/magnetic.md) · [cursor](preset/cursor.md) ·
+  [marquee](preset/marquee.md) · [card-stack](preset/card-stack.md) ·
+  [loader](preset/loader.md) · [cinematic](preset/cinematic.md) ·
+  [page-transition](preset/page-transition.md) ·
+  [scroll-storytelling](preset/scroll-storytelling.md)
+- **Worked examples**, complete answers with the code inline —
+  [svg-loader](example/svg-loader.md) ·
+  [cinematic-intro](example/cinematic-intro.md) ·
+  [magnetic-button](example/magnetic-button.md)
+- **Templates** — [useTimeline.ts](template/useTimeline.ts) ·
+  [useScrollScene.ts](template/useScrollScene.ts)
+
+## Tools
+
+Both scripts catch failures that are **silent**. Run them from the project
+root; `<skill-dir>` is where this skill is installed.
+
+```bash
+# Leaks, per-event tweens, layout properties, eased loops, shared plugin ids,
+# unregistered plugins, dev tooling left in. Exit 1 on an error.
+node <skill-dir>/scripts/audit-gsap.mjs [path...]     # default: src
+node <skill-dir>/scripts/audit-gsap.mjs src --quiet   # errors only
+node <skill-dir>/scripts/audit-gsap.mjs src --json    # machine-readable
+
+# What an SVG can actually do, before any animation is written.
+node <skill-dir>/scripts/audit-svg.mjs <file.svg>
+node <skill-dir>/scripts/audit-svg.mjs --morph <a.svg> <b.svg>
+node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>   # also flag hue literals
+```
+
+Run `audit-gsap` first in an `audit` and after writing any animation. A false
+finding is a bug in the script, not something to work around.
+
+`MotionPathHelper`, `GSDevTools`, `markers: true` and
+`MorphSVGPlugin.findShapeIndex()` are development-only. A static import ships
+whatever `if` surrounds it: import them dynamically behind a `NODE_ENV` check,
+and delete the block once their value is baked in.

package/skill/example/cinematic-intro.md

@@ -0,0 +1,202 @@
+# Example: site intro
+
+An arrival curtain. Composed rather than singular: SVG drawing, motion path,
+morph and a staggered reveal, all serving one sentence. The code is trimmed to
+the parts worth copying.
+
+## The concept
+
+> The mark writes itself, then the dot that drew it runs off and writes the
+> word.
+
+One sentence, and every technique either serves it or was cut. That is the test
+for "something crazy" — not how many plugins are involved.
+
+## Sequence
+
+1. Mark outlines draw on, staggered (DrawSVG)
+2. Fills arrive underneath; outlines retire
+3. A dot emerges and runs the wordmark's baseline (MotionPath)
+4. Letters draw in its wake, staggered to its travel (DrawSVG)
+5. The dot stretches to a dash and back as it moves (MorphSVG)
+6. It settles onto an orbit around the mark — the loader's idle, so the two read
+   as one family
+7. The curtain lifts
+
+Under 3 seconds. Once per session, not once per route.
+
+## What is worth copying
+
+**Both halves in one coordinate space.** Build from the lockup master that holds
+the mark and the wordmark together, so synchronising the dot's travel with the
+letters is one timeline rather than a coordinate conversion between two SVGs.
+Choosing the right source asset removed the hard problem.
+
+**Labels, not offsets.** The dot's run and the letter stagger share a `"write"`
+label, so they stay together when the beat before them changes length:
+
+```ts
+tl.addLabel("write")
+  .to(orbiter, { autoAlpha: 1, duration: 0.25 }, "write")
+  .to(
+    orbiter,
+    {
+      motionPath: { path: baseline, align: baseline, alignOrigin: [0.5, 0.5] },
+      duration: WRITE_SECONDS,
+      ease: "power1.inOut",
+    },
+    "write",
+  )
+  // The letters are sorted along the dot's direction of travel, so a plain
+  // stagger puts each one under the dot as it passes. The span is a shade
+  // shorter than the run, so the last letter finishes before the dot leaves.
+  .fromTo(
+    "[data-word-outline]",
+    { drawSVG: "0%" },
+    {
+      drawSVG: "100%",
+      duration: 0.5,
+      stagger: { each: (WRITE_SECONDS * 0.82) / LETTER_COUNT },
+      ease: "power2.out",
+    },
+    "write+=0.1",
+  );
+```
+
+**A hard ceiling, and dismissal as a race.** A splash that waits on a signal can
+wait forever, and the result is not a slow page — it is a site nobody can
+reach. Whatever ends first, the animation or the ceiling, lifts the curtain,
+and only once:
+
+```ts
+useGSAP(
+  () => {
+    let finished = false;
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      seen.set();
+      onDone();
+    };
+
+    if (seen.get()) {
+      finish();
+      return;
+    }
+
+    const ceiling = window.setTimeout(finish, MAX_VISIBLE_MS);
+
+    // …a matchMedia with a motion branch and a reduced branch, both ending in
+    // finish() — see below.
+
+    // The one thing here the GSAP context does not own.
+    return () => window.clearTimeout(ceiling);
+  },
+  { scope: rootRef },
+);
+```
+
+**An endless loop makes its timeline endless.** The dot settles into an orbit
+that repeats forever. A timeline holding a `repeat: -1` child is given an
+effectively infinite duration — `1e10` seconds, measured in gsap 3.15 — so its
+`onComplete` never fires, and a short tween added after the loop does not
+change that. Hand over at a *position* instead:
+
+```ts
+tl.addLabel("hold")
+  .to(
+    orbiter,
+    {
+      motionPath: { path: orbit, align: orbit, alignOrigin: [0.5, 0.5], autoRotate: true },
+      duration: ORBIT_SECONDS,
+      repeat: -1,
+      ease: "none",
+    },
+    "hold",
+  )
+  // Fires when the playhead passes it, however long the timeline is.
+  .call(finish, [], `hold+=${SETTLE_SECONDS}`);
+```
+
+Get this wrong and nothing visibly breaks: the ceiling still lifts the curtain,
+just late, on every visit. That is exactly why it is worth checking.
+
+**The page renders underneath the whole time.** The curtain only covers. A
+JavaScript failure leaves the visitor on the site, not behind a curtain.
+
+**Session gating in the layout effect, behind storage's real failures.**
+Storage cannot be read during render without the server and client
+disagreeing; `useGSAP` runs before paint, so a returning visitor never sees a
+frame. Storage also throws in locked-down browsers and embedded webviews:
+
+```ts
+const seen = {
+  get() {
+    try {
+      return window.sessionStorage.getItem(INTRO_SEEN_KEY) === "1";
+    } catch {
+      return false;
+    }
+  },
+  set() {
+    try {
+      window.sessionStorage.setItem(INTRO_SEEN_KEY, "1");
+    } catch {
+      /* Storage blocked: the visitor sees the intro again. That is all. */
+    }
+  },
+};
+```
+
+An intro shown twice is a far smaller failure than one that takes the page down
+with it.
+
+**Reduced motion gets the lockup, not the performance.** An intro is
+unskippable and is the first thing a visitor meets, so it is the worst place to
+insist on movement:
+
+```ts
+if (reduced) {
+  gsap.set("[data-outline]", { autoAlpha: 0 });
+  gsap.set("[data-fill]", { autoAlpha: 1 });
+  gsap.set(orbiter, { autoAlpha: 0 });
+  gsap.delayedCall(0.9, finish);
+  return;
+}
+```
+
+**Artwork as a prop, not an import.** Path data for a lockup runs to ~15KB per
+language. A Server Component picks the right set and passes it down; check the
+build output that the other languages are absent from the client chunks.
+
+**Geometry is generated, not transcribed.** Three ~900-character `d` attributes
+retyped by hand is a logo subtly wrong in one curve. A generator script also
+catches what reading by eye misses:
+
+- **Exports disagree about class names.** Two masters from one design file can
+  use `st0` for the brand colour in one and a grey in the other. Read the
+  declared `fill`, never the class name.
+- **Near-identical greys.** A master can carry a third graphite one step away
+  from the others. Collapsing every grey to `currentColor` fixes it on the way
+  past.
+- **The mark moves between variants.** When it sits at opposite ends of two
+  lockups, find it by its node signature, not by index.
+- **The orbit is bigger than the art.** Expand the viewBox to contain it, or the
+  dot is clipped for part of every lap.
+
+Keep the generator in the project's `scripts/`, not a scratch directory. Its
+output says "not hand-editable"; without a re-runnable generator that is a dead
+end.
+
+## Usage
+
+```tsx
+// A Server Component picks the language's artwork and passes it down.
+<SiteIntro art={INTRO_ART[locale]} />
+```
+
+## Related
+
+[preset/cinematic.md](../preset/cinematic.md) ·
+[reference/svg.md](../reference/svg.md) ·
+[reference/accessibility.md](../reference/accessibility.md)

package/skill/example/magnetic-button.md

@@ -0,0 +1,101 @@
+# Example: magnetic CTA
+
+A worked interaction, end to end, showing the shape of the answer this skill
+should produce.
+
+## Analysis
+
+- **Animating** — a primary CTA and its label.
+- **Why** — the button should feel like it wants to be pressed. The response
+  begins before the cursor arrives, which reads as intent rather than as a
+  hover state.
+- **Style** — premium and restrained. Small travel, long ease, no overshoot.
+- **Trigger** — pointer movement inside a padded zone; leave returns it.
+- **Techniques** — `gsap.quickTo` for the tracking, a paused timeline for the
+  hover state. No plugins. MotionPath and Draggable would both be wrong here.
+
+## Motion strategy
+
+1. The pointer enters the zone — a 32px halo around the button.
+2. The button eases toward the cursor at 32% of the offset.
+3. The label travels half again as far, so the face has depth.
+4. Simultaneously the button scales to 1.04 and its shadow deepens.
+5. On leave, everything eases back to rest over 0.6s.
+
+The return is the part that makes it feel physical, and the part most
+implementations get wrong by snapping.
+
+## Architecture
+
+- `quickTo` functions created once, in the `useGSAP` body — not a tween per
+  pointer event. This is the whole performance story.
+- A paused hover timeline, played and reversed, so the return matches the
+  arrival without a second definition.
+- `gsap.matchMedia` gating on `(hover: hover) and (pointer: fine)` **and**
+  `prefers-reduced-motion: no-preference`. Both gates are load-bearing.
+- Listeners removed in the `matchMedia` callback's own cleanup. `mm` itself
+  needs no revert: it registers with the active GSAP context and goes with it.
+
+## Implementation
+
+The hook is in [preset/magnetic.md](../preset/magnetic.md) — copy it rather than
+duplicating it here.
+
+```tsx
+"use client";
+
+import { useMagnetic } from "./useMagnetic";
+
+export function MagneticCta({
+  label,
+  onPress,
+}: Readonly<{ label: string; onPress: () => void }>) {
+  const { zoneRef, targetRef, labelRef } = useMagnetic();
+
+  return (
+    // The zone's padding is the field radius — the pull starts here, not at
+    // the button's edge. That is what turns a hover state into a field.
+    <div ref={zoneRef} className="inline-flex p-8">
+      <button
+        ref={targetRef as React.RefObject<HTMLButtonElement>}
+        type="button"
+        onClick={onPress}
+        // The focus ring carries the whole affordance for a keyboard, which
+        // never sees the pull at all.
+        className="rounded-full bg-neutral-900 px-7 py-3 text-sm font-medium text-white shadow-lg focus-visible:ring-2"
+      >
+        <span ref={labelRef} className="inline-block">
+          {label}
+        </span>
+      </button>
+    </div>
+  );
+}
+```
+
+## Usage
+
+```tsx
+<MagneticCta label={t("cta.contact")} onPress={open} />
+```
+
+The label is a message key resolved by the caller.
+
+## Notes
+
+- **Responsive** — the effect does not exist on touch. The button is an
+  ordinary button there, which is correct; nothing is lost.
+- **Performance** — two `quickTo` functions, no allocation per event, only
+  transforms. The rect is measured per move because scroll shifts it; if that
+  shows in a profile, cache on enter and invalidate on scroll.
+- **Reduced motion** — no pull, no scale. The hover and focus states remain as
+  instant colour and shadow changes, so the affordance survives.
+- **Accessibility** — focus state equals hover state. The transform is small
+  enough that the focus ring stays under the element.
+- **Dependencies** — none beyond `gsap` and `@gsap/react`.
+
+## Related
+
+[preset/magnetic.md](../preset/magnetic.md) ·
+[reference/interaction.md](../reference/interaction.md) ·
+[reference/performance.md](../reference/performance.md)

package/skill/example/svg-loader.md

@@ -0,0 +1,180 @@
+# Example: SVG logo loader
+
+A loader built from a logo, end to end. The code is trimmed to the parts worth
+copying — adapt the selectors, path data and timings to your own artwork.
+
+## The brief
+
+A loading indicator carrying the brand, working from 32px to 200px, in light and
+dark themes, and on right-to-left pages.
+
+## Analysis
+
+The mark is three **filled** paths. DrawSVG animates a stroke, so the artwork as
+delivered could not be drawn at all — that constraint decided the structure.
+
+Sequence: the outline writes itself, the fills arrive underneath, the outline
+retires, and a dot takes up an orbit for as long as the wait lasts.
+
+## What is worth copying
+
+**Two layers of one geometry.** The same `d` is rendered twice — once stroked
+(`data-outline`), once filled (`data-fill`, starting transparent). The stroke
+draws, the fill fades in under it, the stroke fades out.
+
+```tsx
+// A sketch of the markup. MARK is the logo's path data; uid is below.
+<svg viewBox="-24 -24 248 248" role="img" aria-label={label}>
+  {MARK.map((d, i) => (
+    <path key={`o${i}`} data-outline d={d} fill="none" stroke="currentColor" />
+  ))}
+  {MARK.map((d, i) => (
+    <path key={`f${i}`} data-fill d={d} fill="currentColor" opacity="0" />
+  ))}
+  <path id={`${uid}-track`} d={ORBIT} fill="none" />
+  <path id={`${uid}-orbiter`} d={DOT} fill="currentColor" opacity="0" />
+  <path id={`${uid}-dash`} d={DASH} visibility="hidden" />
+</svg>
+```
+
+The side effect is better than the effect: with JavaScript unavailable the
+stroked layer is what renders, so the fallback is the mark in outline rather
+than an empty box. `useGSAP` runs in a layout effect, so the full outline never
+paints before the draw begins.
+
+```ts
+gsap.registerPlugin(useGSAP, DrawSVGPlugin, MorphSVGPlugin, MotionPathPlugin);
+
+gsap
+  .timeline()
+  .fromTo(
+    "[data-outline]",
+    { drawSVG: "0%" },
+    { drawSVG: "100%", duration: WRITE_SECONDS, stagger: 0.18, ease: "power2.inOut" },
+  )
+  // The fills land before the outlines finish, so the mark is never hollow.
+  .to(
+    "[data-fill]",
+    { autoAlpha: 1, duration: 0.5, stagger: 0.1, ease: "power1.out" },
+    `-=${WRITE_SECONDS * 0.45}`,
+  )
+  .to("[data-outline]", { autoAlpha: 0, duration: 0.35 }, "<0.2")
+  .to(orbiter, { autoAlpha: 1, duration: 0.3 }, "<");
+```
+
+**Per-instance ids.** `useGSAP` scopes the selectors it resolves, but
+`motionPath.path` and `morphSVG.shape` are resolved by the plugins against the
+whole document. With a fixed id, three loaders on one page all drive the first
+one's orbit — silently. Use `useId()`, stripped to word characters because
+React's id carries delimiters a CSS selector cannot hold:
+
+```ts
+const uid = `ldr${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
+const track = `#${uid}-track`;
+const orbiter = `#${uid}-orbiter`;
+const dash = `#${uid}-dash`;
+```
+
+**Direction without a second path.** A loader spinning against the reading
+direction reads as rewinding. Run the same path backwards:
+
+```ts
+const isRtl = document.documentElement.dir === "rtl";
+
+gsap.to(orbiter, {
+  motionPath: {
+    path: track,
+    align: track,
+    alignOrigin: [0.5, 0.5],
+    autoRotate: true,
+    start: isRtl ? 1 : 0,
+    end: isRtl ? 0 : 1,
+  },
+  duration: ORBIT_SECONDS,
+  repeat: -1,
+  ease: "none", // any other ease stutters at the seam where the loop restarts
+  delay: WRITE_SECONDS * 0.8,
+});
+```
+
+**A morph pair authored to match.** The dot and the dash are both six-node
+stadiums with the same command sequence — the dot is the dash with its straight
+run closed to nothing. Identical structure is what makes the morph glide, and it
+is cheaper to author in than to correct later with `shapeIndex`.
+
+```ts
+gsap.to(orbiter, {
+  morphSVG: { shape: dash, type: "rotational" },
+  duration: ORBIT_SECONDS / 2,
+  repeat: -1,
+  yoyo: true,
+  ease: "sine.inOut",
+  delay: WRITE_SECONDS * 0.8,
+});
+```
+
+**The viewBox contains the orbit, not just the ink.** Sized to the artwork
+alone, the dot is clipped for part of every lap.
+
+**Lettering follows the theme.** Paint with `currentColor` over a theme-aware
+colour. A brand colour that is fixed across themes — a dark graphite, say — can
+read at about 1.3:1 on a dark page.
+
+**Reduced motion keeps something moving.** The mark arrives drawn and the
+orbiter breathes. A loader with nothing moving reads as a page that has hung.
+
+```ts
+useGSAP(
+  () => {
+    const mm = gsap.matchMedia();
+    mm.add(
+      {
+        motion: "(prefers-reduced-motion: no-preference)",
+        reduced: "(prefers-reduced-motion: reduce)",
+      },
+      (context) => {
+        const { reduced } = context.conditions as { reduced: boolean };
+        if (reduced) {
+          gsap.set("[data-outline]", { autoAlpha: 0 });
+          gsap.set("[data-fill]", { autoAlpha: 1 });
+          gsap.to(orbiter, {
+            autoAlpha: 0.3,
+            duration: 1.2,
+            repeat: -1,
+            yoyo: true,
+            ease: "sine.inOut",
+          });
+          return;
+        }
+        // …the timeline, orbit and morph above
+      },
+    );
+  },
+  { scope: rootRef },
+);
+```
+
+No cleanup is returned, deliberately: the `matchMedia` is created inside
+`useGSAP`, so it is reverted with the context along with every tween it built.
+
+## Mistakes made while building it
+
+Both were caught by checking output, not by reading code:
+
+1. **A theme-fixed colour on the lettering** — invisible on the dark page.
+2. **Hardcoded ids** — found by reading the server-rendered HTML and seeing the
+   same `id` three times on one page.
+
+## Usage
+
+```tsx
+<Loader label={t("loading")} className="size-24" />
+```
+
+The label comes from the caller. A client component that imported the
+project's messages itself could bundle every locale.
+
+## Related
+
+[preset/loader.md](../preset/loader.md) · [reference/svg.md](../reference/svg.md)
+· [reference/react-nextjs.md](../reference/react-nextjs.md)