@mehshekari/gsap-motion 2.1.0

package/skill/reference/routing.md

@@ -0,0 +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.

package/skill/reference/scrolltrigger.md

@@ -0,0 +1,191 @@
+# ScrollTrigger
+
+Scroll position as a trigger or as a playhead. The difference between those two
+is the first decision.
+
+```ts
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+gsap.registerPlugin(ScrollTrigger);
+```
+
+## Trigger or playhead
+
+| Want | Use | Ease |
+|---|---|---|
+| Play once when it comes into view | no `scrub` | normal easing |
+| Motion tied to scroll position | `scrub: true` | **`ease: "none"`** |
+| Motion tied to scroll, slightly lagged | `scrub: 1` | `none` |
+
+`scrub` makes the scrollbar the playhead. Easing inside a scrubbed timeline
+fights the visitor's own scrolling and reads as lag — use `none` on every child
+and let `scrub: 1` provide the smoothing.
+
+## The config that matters
+
+```ts
+ScrollTrigger.create({
+  trigger: section,
+  start: "top 80%",     // trigger's top hits 80% down the viewport
+  end: "bottom 20%",
+  scrub: 1,             // true = locked, number = seconds of catch-up
+  pin: true,
+  anticipatePin: 1,     // reduces the flicker when pinning at speed
+  snap: { snapTo: 1 / 4, duration: 0.4, ease: "power2.inOut" },
+  markers: process.env.NODE_ENV === "development",
+  invalidateOnRefresh: true,
+  toggleActions: "play none none reverse",
+});
+```
+
+`start` / `end` read as `"<trigger edge> <viewport position>"`. Both accept
+`"top"`, `"center"`, `"bottom"`, a percentage, or a px offset — and `end` also
+accepts `"+=800"`, meaning "800px of scrolling after the start", which is what
+you want for a pinned sequence.
+
+`toggleActions` is four states in order: **onEnter, onLeave, onEnterBack,
+onLeaveBack**. `"play none none reverse"` is the usual reveal. `"play none none
+none"` plays once and never again.
+
+## One trigger, many elements
+
+The most common mistake is one ScrollTrigger per card. If a group belongs to one
+visual moment, it is one trigger with a staggered timeline:
+
+```ts
+// Wrong — 40 triggers, 40 sets of scroll maths
+cards.forEach((card) =>
+  gsap.from(card, { y: 40, scrollTrigger: { trigger: card } }),
+);
+
+// Right — one trigger, one timeline
+gsap.from("[data-card]", {
+  y: 40,
+  autoAlpha: 0,
+  stagger: 0.06,
+  scrollTrigger: { trigger: grid, start: "top 75%" },
+});
+```
+
+Per-item triggers are correct when items are genuinely far apart and reveal
+independently. For a grid on one screen they are not.
+
+## Pinning
+
+`pin` holds the element while the page scrolls past its `end`. The scroll
+distance is what you are really authoring:
+
+```ts
+gsap.timeline({
+  scrollTrigger: {
+    trigger: section,
+    start: "top top",
+    end: "+=2000",        // 2000px of scroll drives the sequence
+    pin: true,
+    scrub: 1,
+  },
+})
+  .to(a, { autoAlpha: 1 })
+  .to(b, { autoAlpha: 1 });
+```
+
+Things that bite:
+
+- **A pinned element cannot be inside a container with `overflow: hidden`** on
+  the scroll axis. This is the usual cause of "pin does nothing".
+- Pin adds a wrapper and a spacer to the DOM. Sibling selectors and
+  `:first-child` break.
+- `position: sticky` is cheaper and needs no plugin. Use it when you only need
+  the element to stay put, not to drive a timeline.
+
+## Horizontal scroll
+
+A vertical scroll driving a horizontal translation. `xPercent` avoids measuring:
+
+```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: 1 / (panels.length - 1),
+    invalidateOnRefresh: true,
+  },
+});
+```
+
+`end` as a function is re-evaluated on refresh, which is what keeps it right
+after a resize. In RTL the direction inverts — see
+[project-rules.md](project-rules.md).
+
+Horizontal scroll costs the visitor their scroll intuition. Use it when the
+content is genuinely a sequence, not to be interesting.
+
+## Refresh
+
+ScrollTrigger measures once and caches. Anything that changes layout after that
+invalidates the measurement.
+
+```ts
+ScrollTrigger.refresh();   // after fonts, images, accordions, route changes
+```
+
+- `invalidateOnRefresh: true` recomputes tween start values too, which is what
+  you want when a `from` depends on measured size.
+- Images without dimensions are the usual cause of triggers drifting: the page
+  grows after measurement. Give them width/height or an aspect ratio.
+- Web fonts shift text height on load. Refresh after `document.fonts.ready`.
+
+## Velocity
+
+Scroll speed as an input — a cheap way to make a section feel responsive:
+
+```ts
+const skew = gsap.quickTo("[data-card]", "skewY", { duration: 0.6, ease: "power3" });
+
+ScrollTrigger.create({
+  onUpdate: (self) => skew(gsap.utils.clamp(-12, 12, self.getVelocity() / -250)),
+});
+```
+
+`getVelocity()` is px/sec and signed. Clamp it — unclamped it produces absurd
+values on a flick.
+
+## ScrollSmoother
+
+Free, and a large commitment: it takes over the scroll container, which
+interferes with `position: fixed`, anchor links, and native scroll on some
+touch devices. Do not add it to make a reveal smoother — fix the reveal. Add it
+only when the whole page is designed around smoothed scrolling.
+
+## React
+
+The lifecycle is the hard part. `useGSAP` reverts its context on unmount, which
+kills ScrollTriggers created inside it. Anything created outside must be killed
+by hand:
+
+```ts
+useGSAP(() => {
+  gsap.to(el, { scrollTrigger: { ... } });   // reverted automatically
+}, { scope: root });
+```
+
+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).
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Nothing happens | `trigger` element not in the DOM when created |
+| Pin does nothing | an ancestor has `overflow: hidden` |
+| Triggers fire at wrong positions | layout changed after measurement — refresh |
+| Scrubbed motion feels laggy | easing inside a scrubbed timeline |
+| Janky while scrolling | layout-triggering properties — see [performance](performance.md) |
+| Works, then breaks after navigation | ScrollTriggers not killed on unmount |
+| Wrong on mobile after address-bar hide | viewport resize — `invalidateOnRefresh` |

package/skill/reference/svg.md

@@ -0,0 +1,201 @@
+# SVG
+
+SVG is one domain among several — reach for it when the shape itself is the
+idea, not because the asset happens to be an SVG. A logo fading in is a
+transform job.
+
+**Run the audit first.** Every failure below is silent at runtime: DrawSVG on a
+fill-only path animates nothing and throws nothing.
+
+```bash
+node .claude/skills/gsap-creative-animation/scripts/audit-svg.mjs <file.svg>
+node .claude/skills/gsap-creative-animation/scripts/audit-svg.mjs --morph <a.svg> <b.svg>
+```
+
+## Preparation
+
+### It must be inline in the DOM
+
+GSAP animates DOM nodes. `<img src="x.svg">`, `next/image`, and a CSS
+`background` all put the shapes somewhere GSAP cannot reach. Inline the markup
+as JSX.
+
+### Ids on everything the timeline targets
+
+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
+`data-*` attribute beats a run of ids:
+
+```tsx
+<path data-petal d="…" />
+```
+
+### `viewBox` in, `width`/`height` out
+
+MotionPath aligns in user units and converts coordinate systems through the
+`viewBox`. Without one there is nothing to convert from. Size with CSS — that is
+also what lets one loader work at 32px and 200px.
+
+**The box must contain everything the animation draws, not just the ink.** An
+orbit that circles a wide lockup is taller than the artwork, and sized to the
+artwork alone the element is clipped for part of every lap.
+
+### Colours
+
+A theme cannot reach a hard-coded hue, and many projects lint for them — SVG
+attributes are string literals like any other. Prefer `currentColor`, then one
+of the project's CSS variables. `audit-svg.mjs --hues` lists every hue literal
+in a file before it is pasted. See [project-rules.md](project-rules.md).
+
+Export tools put paint in a `<style>` block keyed by generated class names
+(`.st0`, `.cls-1`). Two traps: an attribute-only scan of the JSX will not see
+those hues, and **the class names are not stable between files** — the same
+`st0` can be the brand yellow in one export and a grey in another. Read the
+declared fill, never the class name.
+
+### Strip the export noise
+
+`<title>`/`<desc>` (decide accessibility deliberately instead), whole-drawing
+`clip-path` wrappers, `pathLength` (it rescales the dash maths DrawSVG relies
+on), `style` blocks, `xlink:href`. In JSX: `class`→`className`,
+`stroke-width`→`strokeWidth`, `stop-color`→`stopColor`, `fill-rule`→`fillRule`.
+
+## DrawSVGPlugin
+
+Animates a **stroke** by driving `stroke-dasharray` and `stroke-dashoffset`.
+
+```ts
+gsap.fromTo("#outline", { drawSVG: "0%" }, { drawSVG: "100%", duration: 1.4 });
+```
+
+| Value | Means |
+|---|---|
+| `"0%"` | zero-length at the start — invisible |
+| `"100%"` | the whole stroke |
+| `"50% 100%"` | only the second half visible |
+| `"20% 20%"` | zero-length at 20% along |
+
+A travelling dash — the comet loader — is a tween between two same-width
+windows:
+
+```ts
+gsap.fromTo("#ring", { drawSVG: "0% 25%" },
+  { drawSVG: "75% 100%", repeat: -1, ease: "none", duration: 1.2 });
+```
+
+**It does nothing on a shape with no stroke, and throws nothing.** A filled
+logo that must draw itself needs two layers of the same geometry: a stroked copy
+that draws, then the filled version fading in under it, then the outline fading
+out. A useful side effect — with JavaScript unavailable the outline is what
+renders, so the fallback is the mark in outline rather than an empty box.
+
+Set `strokeLinecap="round"` unless the design says otherwise; a half-drawn butt
+cap ends in a visible flat edge.
+
+## MorphSVGPlugin
+
+Tweens one path's `d` into another's.
+
+```ts
+gsap.to("#shape", {
+  morphSVG: { shape: "#target", shapeIndex: 3, type: "rotational" },
+});
+```
+
+- `shapeIndex` decides which node of the target lines up with node 0 of the
+  source. It is the difference between a glide and a spin, and the default is a
+  guess. Find it once with `MorphSVGPlugin.findShapeIndex("#a", "#b")` in the
+  browser console, then hardcode the number.
+- `type: "rotational"` keeps segment angles instead of straight-lining points.
+  Much better for organic shapes.
+- `map` decides how the two shapes' **subpaths** are paired when each has
+  several — a letter with a counter, a logo of separate marks. `"size"` is the
+  default and pairs by area; `"position"` pairs by where they sit; and
+  `"complexity"` pairs by node count, which is the one to reach for when the
+  subpaths are similar in size but not in detail.
+
+Both sides must be `<path>`:
+
+```ts
+MorphSVGPlugin.convertToPath("circle, rect, ellipse, line, polygon, polyline");
+```
+
+Convert in the source file where you can — a runtime conversion mutates the DOM
+React thinks it owns. It is safe for static markup React never re-renders.
+
+**Keep node counts within about 3×.** Beyond that MorphSVG subdivides the
+simpler path, which is mathematically right and reads as a smear; the fix is to
+redraw a shape, not to tune the tween. Best of all, author both shapes with the
+**same command sequence** — a dot as a stadium with its straight run closed to
+nothing morphs into a dash perfectly.
+
+Target shapes should be unpainted (`fill="none" stroke="none"`) but **still
+rendered** — `display: none` leaves no geometry to read.
+
+## MotionPathPlugin
+
+Moves an element along a path.
+
+```ts
+gsap.to("#dot", {
+  motionPath: {
+    path: "#track",
+    align: "#track",
+    alignOrigin: [0.5, 0.5],
+    autoRotate: true,
+    start: 0,
+    end: 1,
+  },
+  duration: 3,
+  repeat: -1,
+  ease: "none",
+});
+```
+
+- **`align` is the one people forget.** Without it the path's coordinates are
+  offsets from the element's current position — the cause of "it moves, but
+  nowhere near the path".
+- `alignOrigin: [0.5, 0.5]` centres the element; the default is its top-left.
+- `autoRotate: true` points it along travel. A number adds degrees, for art
+  whose "forward" is not to the right.
+- **`start: 1, end: 0` runs the path backwards** — which is how you mirror for
+  RTL without authoring a second path.
+
+A route is geometry, not decoration: `fill="none" stroke="none"`, still
+rendered. `ease: "none"` on anything looping.
+
+To author a path by eye, use `MotionPathHelper` in development only and bake the
+`d` it gives you. It is an editor — never ship it.
+
+## Masks and clip paths
+
+Often better than either plugin, and cheaper. A mask reveal is a transform on a
+rect inside a `<mask>`:
+
+```tsx
+<mask id={`${uid}-wipe`}>
+  <rect data-wipe x="0" y="0" width="100%" height="100%" fill="#fff" />
+</mask>
+<g mask={`url(#${uid}-wipe)`}>…</g>
+```
+
+```ts
+gsap.from("[data-wipe]", { scaleX: 0, transformOrigin: "0% 50%", duration: 0.8 });
+```
+
+Greyscale in a mask is an alpha stop, not a colour — the one literal this
+repo's colour rule allows.
+
+## Choosing
+
+```text
+stroke, and the drawing is the idea        → DrawSVG
+two shapes, and the change is the idea     → MorphSVG
+something travelling a route               → MotionPath
+a reveal                                   → mask or clip-path
+moving, scaling, rotating whole groups     → plain transforms
+```
+
+Never force MorphSVG or DrawSVG onto a structure that does not support it. Say
+why, and offer the alternative.

package/skill/reference/text.md

@@ -0,0 +1,150 @@
+# Text animation
+
+Text is the content the visitor came for. Animating it delays reading, so the
+bar is higher than for decoration: it must be fast, it must not break selection
+or screen readers, and it must not reflow.
+
+## SplitText
+
+Free and installed. Splits into chars, words, or lines and gives you the arrays.
+
+```ts
+import { SplitText } from "gsap/SplitText";
+gsap.registerPlugin(SplitText);
+
+const split = new SplitText(heading, {
+  type: "lines,words",
+  linesClass: "rs-line",
+  mask: "lines",          // wraps each line in an overflow-hidden parent
+  autoSplit: true,        // re-splits on resize and font load
+});
+
+gsap.from(split.lines, {
+  yPercent: 110,
+  duration: 0.8,
+  stagger: 0.08,
+  ease: "power3.out",
+});
+
+// Cleanup — puts the original markup back:
+split.revert();
+```
+
+`mask: "lines"` is what makes a line rise out of nothing instead of sliding in
+from below. It is the single option that separates a polished reveal from a
+generic one.
+
+`autoSplit: true` handles the two things that silently break a split: a web font
+loading after the split and changing line breaks, and a resize reflowing them.
+Without it, lines end up wrapped mid-phrase.
+
+### Which unit
+
+- **Lines** — the default for headings and paragraphs. Reads as writing.
+- **Words** — for short, deliberate phrases. Six words maximum.
+- **Chars** — for a logo, a number, a single word. Never a sentence: a paragraph
+  revealing per character is unreadable and produces hundreds of nodes.
+
+### Accessibility
+
+Splitting replaces the text with a pile of `<div>`s. SplitText sets
+`aria-label` on the container from the original text and hides the fragments —
+verify it, because a heading read as forty letters is a serious regression.
+
+Always `revert()` on unmount. Leaving a split in place breaks copy-paste and
+leaves the DOM heavier than it needs to be.
+
+### Cost
+
+Splitting a paragraph into characters can produce a thousand elements. Split
+lines, animate lines. If you must animate characters, cap it at a headline.
+
+## ScrambleTextPlugin
+
+Cycles characters before settling on the target — the "decoding" effect.
+
+```ts
+import { ScrambleTextPlugin } from "gsap/ScrambleTextPlugin";
+
+gsap.to(el, {
+  duration: 1.2,
+  scrambleText: {
+    text: "LAUNCHING",
+    chars: "upperCase",     // or "lowerCase", "upperAndLowerCase", or your own
+    speed: 0.4,
+    revealDelay: 0.3,
+    tweenLength: false,
+  },
+});
+```
+
+`tweenLength: false` keeps the element's width fixed, which stops the layout
+jumping as the string grows. Almost always what you want.
+
+Reads as technical and futuristic. It also makes text unreadable while it runs,
+so keep it under ~1.2s and never use it on something the visitor must read
+immediately. Persian and Arabic script scramble badly — the glyph shapes are
+contextual — so use a Latin-only charset or skip the effect for those locales.
+
+## TextPlugin
+
+Types or replaces text content. Simpler than scramble, and better for a
+typewriter:
+
+```ts
+gsap.to(el, { duration: 2, text: "Built in Iran.", ease: "none" });
+```
+
+## Counters
+
+Numbers are text that should animate. Tween an object, format on update:
+
+```ts
+const n = { value: 0 };
+gsap.to(n, {
+  value: 1240,
+  duration: 1.4,
+  ease: "power2.out",
+  onUpdate: () => { el.textContent = Math.round(n.value).toLocaleString(locale); },
+});
+```
+
+Use tabular figures (`font-variant-numeric: tabular-nums`) or the width jitters
+on every frame.
+
+## Without SplitText
+
+A line mask needs no plugin when you control the markup — cheaper and no
+revert to forget:
+
+```tsx
+<span className="block overflow-hidden">
+  <span data-line className="block">…</span>
+</span>
+```
+
+```ts
+gsap.from("[data-line]", { yPercent: 110, stagger: 0.08, ease: "power3.out" });
+```
+
+For a heading whose lines you know, this is the better answer.
+
+## Rhythm
+
+- Lines: `stagger: 0.06–0.1`, duration `0.6–0.9`, `power3.out`.
+- Words: `stagger: 0.03–0.05` — words are small, so the wave should be tight.
+- Chars: `stagger: { amount: 0.4 }` — a *total*, so a long word does not crawl.
+
+Text reveals should be over inside a second. Anything slower and the visitor is
+waiting on the page rather than reading it.
+
+## Copy, locales and direction
+
+Keep the words out of the animation. The animated component should receive the
+**string as a prop**: a client component that imports the project's messages or
+content module itself can bundle every locale into the browser payload. The
+project's rules say where copy comes from — see
+[project-rules.md](project-rules.md).
+
+In a right-to-left language, a stagger in "reading order" is `from: "end"`, and
+a line rising from the start edge uses logical properties, not `left`.