@struq/skill 0.0.0-stage → 0.2.1

package/skills/struq/references/loaders.md

@@ -0,0 +1,287 @@
+# First-Load Loaders: session-gated, SSR-safe
+
+One arm of the page-flow system, the site's *arrival*. A loader is the route transition's cover phase with no swap ([route-transitions.md](route-transitions.md)): it starts closed and clears once assets are ready. Sibling: [page-entrances.md](page-entrances.md) for what the revealed page does next.
+
+**It is optional.** It is warranted on narrative/portfolio/launch sites and skipped on app/dashboard zones. Keep it short, tie it to real load progress, and play it **once per session**. Never a spinner: the overlay sits on top of finished content and reveals it.
+
+---
+
+## 0. The lifecycle invariant: why flash-free loaders work
+
+A first-load loader has **two different state machines**. Never collapse them into one boolean:
+
+| State | Owner | What it may do |
+|---|---|---|
+| First paint: play or skip | synchronous script in `<head>` + CSS | Hide SSR loader markup on a revisit before the browser paints |
+| Live phase: loading → revealing → done | the mounted loader component | Keep the first-visit curtain mounted until its transform/opacity exit completes |
+
+The classic regression is using one `data-loader-seen` attribute for both jobs, then running `markLoaderSeen()` when the intro starts or when the exit starts. If CSS contains `html[data-loader-seen] [data-first-loader] { display:none }`, that write removes the live curtain immediately. The reveal timeline technically starts against `display:none`, so the user sees a flash/cut instead of a curtain.
+
+**Non-negotiable order:**
+
+1. SSR emits an already-opaque curtain. Any animated word/chars are also emitted in their hidden start state; do not wait for hydration to apply a GSAP `.from()` state.
+2. A synchronous `<head>` script stamps the skip attribute only for a session revisit or excluded app route. CSS suppresses that SSR overlay before first paint.
+3. On a genuine first visit, await real readiness plus a minimum floor, capped by a safety ceiling. The curtain remains static and opaque while waiting.
+4. Start one compositor-only exit (`transform` and/or `opacity`). Do not read layout or change overflow at release time.
+5. In the exit's `onComplete`, and only there: persist the session marker, stamp the skip attribute, release scroll, and unmount.
+
+This is why the system stays clean at both ends: the SSR gate prevents revisit flashes, while delayed persistence lets the live curtain finish.
+
+---
+
+## 1. The session gate (shared by every loader)
+
+```ts
+// components/ui/loaders/useFirstVisit.ts
+const PREFIX = "loader:";
+export const LOADER_SEEN_ATTR = "data-loader-seen";
+
+// Inline this synchronously in <head>, before loader markup. It is the only code
+// allowed to activate the CSS skip gate before the first paint.
+export const PRE_PAINT_LOADER_SCRIPT = `try{if(sessionStorage.getItem('${PREFIX}intro')==='1')document.documentElement.setAttribute('${LOADER_SEEN_ATTR}','1')}catch(e){}`;
+
+export function loaderSeen(id?: string): boolean {
+  if (typeof window === "undefined" || !id) return false;
+  if (document.documentElement.hasAttribute(LOADER_SEEN_ATTR)) return true;
+  try { return sessionStorage.getItem(PREFIX + id) === "1"; } catch { return false; }
+}
+export function markLoaderSeen(id?: string): void {
+  if (typeof window === "undefined" || !id) return;
+  // CALL ONLY FROM THE CURTAIN EXIT'S onComplete.
+  document.documentElement.setAttribute(LOADER_SEEN_ATTR, "1");
+  try { sessionStorage.setItem(PREFIX + id, "1"); } catch { /* private mode → plays every time */ }
+}
+```
+
+```css
+/* SSR revisit gate. This selector is permanent suppression, not animation state. */
+html[data-loader-seen] [data-first-loader] {
+  display: none !important;
+}
+```
+
+Mount the loader in a persistent root/marketing layout, never inside a page template that remounts on every client navigation. A small same-document module guard may protect Strict Mode/HMR remounts while the first run is active; session persistence still happens only after the exit completes.
+
+---
+
+## 2. Asset-aware counter (the default loader)
+
+Tie release to **real** readiness (`document.fonts.ready` + critical image decode/load) and a minimum on-screen floor, raced against a hard ceiling. The floor makes a warm-cache run legible; the ceiling means one stalled request can never pin the site.
+
+The key lifecycle, not the visual styling, is:
+
+```tsx
+"use client";
+import { useRef, useState } from "react";
+import { gsap, useGSAP } from "@/lib/gsap";
+import { loaderSeen, markLoaderSeen } from "./useFirstVisit";
+
+const MIN_HOLD_MS = 1450;
+const SAFETY_CEILING_MS = 4000;
+const wait = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+function decodeCriticalHeroImage(src = "/hero-poster.webp"): Promise<void> {
+  return new Promise((resolve) => {
+    const image = new Image();
+    image.src = src;
+    image.decode().then(resolve).catch(resolve);
+  });
+}
+
+export function LoaderCounter({ id = "intro" }: { id?: string }) {
+  const root = useRef<HTMLDivElement>(null);
+  const [done, setDone] = useState(false);
+
+  useGSAP(() => {
+    if (loaderSeen(id)) { setDone(true); return; }
+    const layer = root.current;
+    if (!layer) return;
+
+    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    let cancelled = false;
+    document.documentElement.classList.add("loader-scroll-lock");
+
+    const assetChecks = Promise.all([
+      (document as Document & { fonts?: FontFaceSet }).fonts?.ready ?? Promise.resolve(),
+      decodeCriticalHeroImage(), // resolve on decode OR error
+      wait(MIN_HOLD_MS),
+    ]);
+
+    Promise.race([assetChecks, wait(SAFETY_CEILING_MS)]).then(() => {
+      if (cancelled) return;
+      layer.dataset.loaderPhase = "revealing";
+      gsap.to(layer, {
+        yPercent: reduce ? 0 : -100,
+        autoAlpha: reduce ? 0 : 1,
+        duration: reduce ? 0.25 : 0.9,
+        ease: reduce ? "power2.out" : "power4.inOut",
+        onComplete: () => {
+          // Persist LAST. Earlier writes activate the CSS display:none gate and
+          // cut this live reveal off.
+          markLoaderSeen(id);
+          document.documentElement.classList.remove("loader-scroll-lock");
+          setDone(true);
+        },
+      });
+    });
+
+    return () => {
+      cancelled = true;
+      document.documentElement.classList.remove("loader-scroll-lock");
+    };
+  }, { scope: root });
+
+  if (done) return null;
+  return (
+    <div ref={root} data-first-loader data-loader-phase="loading"
+         className="fixed inset-0 z-[10001] bg-surface-0">
+      {/* Encode hidden start states in SSR markup/CSS. If SplitText must create
+          them after hydration, keep the whole word visibility:hidden until its
+          chars have been positioned, then reveal the wrapper. */}
+      <span className="loader-word" style={{ visibility: "hidden" }}>Brand</span>
+    </div>
+  );
+}
+```
+
+The readiness callback must only flip state/start a transform. Never run `getBoundingClientRect()`, `ScrollTrigger.refresh()`, image decoding, or synchronous asset work in the release frame.
+
+### Flash-free animated start states
+
+The curtain background itself must be present in SSR HTML. Any content that winds up (masked chars, mark, line, dot) must also start hidden before React runs:
+
+```css
+.loader-char { transform: translateY(118%); }
+.loader-dot { opacity: 0; transform: scale(0); }
+```
+
+For SplitText, SSR cannot emit the generated char wrappers. Set `visibility:hidden` on the unsplit word in JSX, create the split, position every char, then set the wrapper visible. A GSAP `.from()` without that SSR guard is too late: the browser can paint the completed word for one frame before hydration, producing the initial flash.
+
+### Scroll lock without scrollbar shift
+
+`scrollbar-gutter: stable` alone is not enough if the lock changes `<html>` to `overflow:hidden`; Chromium may collapse the gutter because the root is no longer scrollable. Keep the root scrollable and lock the body/content instead:
+
+```css
+html { scrollbar-gutter: stable; }
+html.loader-scroll-lock {
+  overflow-y: scroll;
+  touch-action: none;
+  overscroll-behavior: none;
+}
+html.loader-scroll-lock body {
+  height: 100dvh;
+  overflow: hidden;
+}
+```
+
+Apply the class while the opaque curtain is present and remove it only after the exit completes. Measure `document.documentElement.clientWidth` before/during/after the lock in browser coverage; all three values must match.
+
+---
+
+## 3. Loader preset menu (pick one per project)
+
+All are SSR-safe overlays at `z-[10001]`, reveal on exit, respect reduced-motion, and use `mixBlendMode: "difference"` so the mark reads on any backdrop. Add the `loaderSeen`/`markLoaderSeen` gate (inside `useGSAP`) for any loader you want to play once per session.
+
+| Preset | Feel | Mechanic | Exit |
+|---|---|---|---|
+| **Counter** | data / precise | % count tied to real asset load | slide up `yPercent:-100` 0.9s `power4.inOut` |
+| **Mark** | minimal / brand | wordmark fades in, holds, layer fades | `opacity→0` 0.6s `power2.inOut` |
+| **Shutter** | architectural | grid of tiles holds brand, staggered grid-wipe | tiles `scaleY→0` 0.6s `power4.inOut` (the baseline curtain ease) |
+| **Odometer** | mechanical | rolling 0→100 reel | slide up 0.9s `power4.inOut` |
+| **WordCycle** | editorial | masked word reel settles on brand | slide up 0.9s `power4.inOut` |
+| **ProgressBar** | restrained | hairline fills 0→100% under a wordmark | slide up 0.8s `power4.inOut` |
+| **DrawMark** | crafted | SVG mark draws in (DrawSVG, recipe in [svg-motion.md](svg-motion.md)) + wordmark | layer fades 0.6s |
+
+> **Warning: avoid a scramble / "decode" / terminal-typewriter loader by default.** That monospaced, glitchy-text aesthetic reads as techy filler and collides with the monospace ban ([anti-patterns.md](anti-patterns.md)). Use it only when the brand is genuinely a terminal/dev product.
+
+Example of the gate wired into a preset (Shutter):
+
+```tsx
+// components/ui/loaders/LoaderShutter.tsx (abridged)
+"use client";
+import { useRef, useState } from "react";
+import { gsap, useGSAP } from "@/lib/gsap";
+import { loaderSeen, markLoaderSeen } from "./useFirstVisit";
+
+export function LoaderShutter({ id, brand = "Brand", rows = 3, cols = 4 }: {
+  id?: string; brand?: string; rows?: number; cols?: number;
+}) {
+  const root = useRef<HTMLDivElement>(null);
+  const [done, setDone] = useState(false);
+
+  useGSAP(() => {
+    if (loaderSeen(id)) { setDone(true); return; } // revisit → hide before paint
+    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    const tiles = gsap.utils.toArray<HTMLElement>(".sh-tile");
+    const tl = gsap.timeline();
+    tl.from(".sh-word", { autoAlpha: 0, y: 14, duration: reduce ? 0.2 : 0.5, ease: "power2.out" });
+    tl.to(".sh-word", { autoAlpha: 0, duration: reduce ? 0.2 : 0.4, ease: "power2.in" }, "+=" + (reduce ? 0.1 : 0.35));
+    tl.to(tiles, {
+      scaleY: 0, transformOrigin: "top", duration: reduce ? 0.3 : 0.6, ease: "power4.inOut", // curtains: quint-in-out
+      stagger: { each: reduce ? 0 : 0.04, grid: [rows, cols], from: "start" },
+      onComplete: () => {
+        markLoaderSeen(id); // persist only after the last tile has cleared
+        setDone(true);
+      },
+    }, "-=0.1");
+  }, { scope: root });
+
+  if (done) return null;
+  return (
+    <div ref={root} className="fixed inset-0 z-[10001]">
+      <div className="absolute inset-0 grid"
+           style={{ gridTemplateColumns: `repeat(${cols},1fr)`, gridTemplateRows: `repeat(${rows},1fr)` }}>
+        {Array.from({ length: rows * cols }).map((_, i) => (
+          <div key={i} className="sh-tile bg-surface-0 will-change-transform" />
+        ))}
+      </div>
+      <div className="sh-word pointer-events-none absolute inset-0 grid place-items-center font-display text-h2 text-ink"
+           style={{ mixBlendMode: "difference" }}>{brand}</div>
+    </div>
+  );
+}
+```
+
+**Why SSR-safe matters:** the overlay sits *on top of* the rendered HTML and reveals it. The page is fully in the SSR markup underneath, so there's no flash of unstyled content, no hydration mismatch, no SEO cost, and if JS fails the content is still there.
+
+Loaders mount inside `<body>`, above `children`. The root-layout wiring is in [route-transitions.md](route-transitions.md) §2.
+
+---
+
+## Timing reference
+
+| Phase | Duration | Ease | Transform |
+|---|---|---|---|
+| Loader exit (slide) | 0.8-0.9s | `power4.inOut` | `yPercent 0→-100` |
+| Loader exit (fade) | 0.6s | `power2.inOut` | opacity |
+| **Reduced motion** | 0.2-0.3s | none | opacity only |
+
+---
+
+## Anti-patterns (sweep before shipping)
+
+- **Spinner / loading gif** while content pops in → an asset-aware overlay that reveals finished content.
+- **Loader on every navigation** (stacked on the route wipe) → session-gate with `id`; loader is first-visit-only.
+- **FOUC / content reflowing in** as fonts/images land → SSR-safe overlay + explicit media aspect ratios; entrances double as load choreography.
+- **Completed wordmark flashes, then restarts** → its start state only exists in a hydration-time `.from()` tween; encode it in SSR CSS/inline visibility first.
+- **Curtain disappears instead of lifting** → the session `seen` attribute activated `display:none` before exit completion; persist only in `onComplete`.
+- **Page jumps horizontally at lock/unlock** → `overflow:hidden` collapsed the root scrollbar gutter; keep `<html>` at `overflow-y:scroll` and lock body/content.
+- **Warm loads blink / slow loads hang** → readiness has neither a minimum floor nor a hard safety ceiling; use both in one shared promise.
+- **Scramble/terminal-decode loader** as a default aesthetic → use a typographic preset instead (monospace ban).
+
+## When to use a loader
+
+- **Use** on narrative, portfolio, campaign, and launch sites, and only **once per session** (`id`). Keep it under ~1.5s of real work.
+- **Skip** on app/dashboard zones and utility pages. There, the route wipe alone (or even just the fast app entrance, [page-entrances.md](page-entrances.md)) is enough; a theatrical intro on a tool feels wrong.
+- Reduced motion: every preset branches to a 0.2-0.3s fade, no travel.
+
+## Regression coverage: required for loader work
+
+At minimum, automate these four checks in a real browser:
+
+1. First visit: loader is attached and visible; the persistent `seen` attribute is absent while it plays.
+2. Reveal: loader enters an explicit `revealing` phase, remains `display != none`, and its transform moves off-screen before unmount.
+3. Same-session revisit: the pre-paint attribute exists and no frame ever shows the SSR loader layer.
+4. Scroll lock: root `clientWidth` is identical before, during, and after lock; the lock class is removed when the loader finishes.
+
+Also inspect raw SSR HTML: the `<head>` pre-paint script must occur before loader markup, and animated content must carry its hidden first-paint state.

package/skills/struq/references/micro-interactions.md

@@ -0,0 +1,270 @@
+# Micro-Interactions
+
+Garnish, not the meal: micro-interactions are the last 5% that make the first 95% feel intentional. They only land if the macro layer (type, spacing, reveals) is already right. A magnetic button on a templated layout is lipstick.
+
+Budget rule: pick **2 to 3** from this file per site, executed perfectly, rather than all of them. Density of gimmicks reads as junior.
+
+All hover-dependent effects must be gated: wrap in `@media (hover: hover)` / check `window.matchMedia("(hover: hover)").matches`. Magnetic buttons and cursor followers on touch devices are dead weight that still costs listeners.
+
+**Library split (SOTA, not taste):** the high-frequency imperative effects here (magnetic buttons, custom cursor) stay on **GSAP `quickTo`**, because they update every frame and must share the one Lenis+GSAP ticker. A competing Motion spring loop is what makes otherwise-good motion feel subtly off. **Motion** owns the state/lifecycle layer: press/toggle feedback (`whileTap`), `AnimatePresence`, `layout`/`layoutId`, and `whileHover`/`whileInView` one-offs. Same rule as the SKILL.md decision table: *every frame or scroll-tied means GSAP; React state/lifecycle means Motion.* The weighted, smooth feel comes from one clock and tuned easing, not from the library choice.
+
+---
+
+## 1. Magnetic button
+
+**Term:** Magnetic / gravitational hover.
+**Mechanic:** Within a proximity zone, the button drifts toward the cursor (and its label drifts slightly further, creating internal depth). On leave, it snaps home with an elastic ease. Implemented with `gsap.quickTo`, which gives pre-compiled tweens for high-frequency updates. Never `setState` per mousemove (re-render per frame) and never raw `gsap.to` per event (allocates a tween per pixel moved).
+
+**When:** Primary CTAs, nav logo, social icons. 1 to 3 magnetic elements per viewport max.
+**Cost:** Trivial with quickTo. The gate is taste, not perf.
+
+```tsx
+"use client";
+
+import { useRef } from "react";
+import { gsap, useGSAP } from "@/lib/gsap";
+
+export function MagneticButton({ children, strength = 0.35 }: { children: React.ReactNode; strength?: number }) {
+  const wrap = useRef<HTMLDivElement>(null);
+  const label = useRef<HTMLSpanElement>(null);
+
+  useGSAP(
+    (_, contextSafe) => {
+      if (!window.matchMedia("(hover: hover)").matches) return;
+
+      const el = wrap.current!;
+      const xTo = gsap.quickTo(el, "x", { duration: 0.4, ease: "power3.out" });
+      const yTo = gsap.quickTo(el, "y", { duration: 0.4, ease: "power3.out" });
+      const lx = gsap.quickTo(label.current, "x", { duration: 0.45, ease: "power3.out" });
+      const ly = gsap.quickTo(label.current, "y", { duration: 0.45, ease: "power3.out" });
+
+      const onMove = contextSafe!((e: MouseEvent) => {
+        const r = el.getBoundingClientRect();
+        const dx = e.clientX - (r.left + r.width / 2);
+        const dy = e.clientY - (r.top + r.height / 2);
+        xTo(dx * strength); yTo(dy * strength);
+        lx(dx * strength * 0.5); ly(dy * strength * 0.5); // label trails → internal parallax
+      });
+
+      const onLeave = contextSafe!(() => {
+        gsap.to([el, label.current], { x: 0, y: 0, duration: 0.7, ease: "elastic.out(1, 0.4)" });
+      });
+
+      el.addEventListener("mousemove", onMove);
+      el.addEventListener("mouseleave", onLeave);
+      return () => { el.removeEventListener("mousemove", onMove); el.removeEventListener("mouseleave", onLeave); };
+    },
+    { scope: wrap }
+  );
+
+  return (
+    <div ref={wrap} className="inline-block">
+      <button className="group relative overflow-hidden rounded-full border border-line bg-surface-2
+                          px-8 py-4 font-ui text-ui text-ink">
+        <span ref={label} className="relative z-10 inline-block">{children}</span>
+        {/* fill swell on hover: scales from bottom, CSS-only */}
+        <span aria-hidden className="absolute inset-0 origin-bottom scale-y-0 bg-accent
+                                     transition-transform duration-500 ease-out-expo group-hover:scale-y-100" />
+      </button>
+    </div>
+  );
+}
+```
+
+The two depth cues, the label trailing at 0.5× and the `elastic.out` return, are the difference between "follows the mouse" and "magnetic." Strength stays at or below 0.4. Buttons chasing cursors across the screen is the parody version.
+
+**Cheap tell:** `hover:scale-105 transition` on the button. **Instead:** Proximity drift + trailing label + elastic return + fill swell.
+
+---
+
+## 2. Custom cursor / follower
+
+**Term:** Cursor follower / contextual cursor.
+**Mechanic:** A fixed element lerps toward the real cursor (trailing it by its smoothing factor) and **changes state per hover context**: growing into a "View" pill over project cards, a circle over links, hiding over native inputs. The context-reactivity is the entire justification. A dot that only follows is decoration.
+
+**When:** Image-heavy portfolios and campaign pages where "View / Drag / Play" affordances add real information.
+**Skip when:** content/SaaS/utility products. Fighting the system cursor in a tool context is hostile. This is the #1 over-reached-for effect, so when in doubt, skip.
+**Cost:** One quickTo pair on a `fixed` element, which is cheap. Never hide the native cursor without a perfect replacement, and never `cursor: none` globally (it breaks inputs, iframes, selection).
+
+```tsx
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { gsap } from "@/lib/gsap";
+
+export function Cursor() {
+  const dot = useRef<HTMLDivElement>(null);
+  const [variant, setVariant] = useState<"default" | "view">("default");
+
+  useEffect(() => {
+    if (!window.matchMedia("(hover: hover)").matches) return;
+
+    // duration here IS the trail amount: 0.5-0.7 visible trail, 0.2 tight
+    const xTo = gsap.quickTo(dot.current, "x", { duration: 0.55, ease: "power3.out" });
+    const yTo = gsap.quickTo(dot.current, "y", { duration: 0.55, ease: "power3.out" });
+
+    const onMove = (e: MouseEvent) => { xTo(e.clientX); yTo(e.clientY); };
+
+    // Event delegation: one listener, data-cursor attributes opt elements in
+    const onOver = (e: MouseEvent) => {
+      const t = (e.target as HTMLElement).closest<HTMLElement>("[data-cursor]");
+      setVariant((t?.dataset.cursor as "view") ?? "default");
+    };
+
+    window.addEventListener("mousemove", onMove);
+    document.addEventListener("mouseover", onOver);
+    return () => { window.removeEventListener("mousemove", onMove); document.removeEventListener("mouseover", onOver); };
+  }, []);
+
+  return (
+    <div ref={dot} className="pointer-events-none fixed left-0 top-0 z-[100] -translate-x-1/2 -translate-y-1/2">
+      <div className={`flex items-center justify-center rounded-full bg-ink text-surface-0
+                       transition-all duration-300 ease-out-expo
+                       ${variant === "view" ? "eyebrow text-eyebrow h-20 w-20" : "h-2.5 w-2.5"}`}>
+        {variant === "view" && "View"}
+      </div>
+    </div>
+  );
+}
+
+// Usage: <article data-cursor="view">…</article>. The native cursor stays visible alongside.
+```
+
+**Cheap tell:** a ring + dot following the cursor everywhere, no state changes, native cursor hidden. **Instead:** Small dot that *becomes an affordance* over opted-in elements, delegation-driven, hover-gated.
+
+---
+
+## 3. Hover state choreography
+
+**Term:** Compound hover / hover scene.
+**Mechanic:** A hover state where 2 to 4 properties move on *different* timings: image scales while a caption rises while siblings dim. The compound timing is what reads as choreography. Mostly CSS via `group`; Motion/GSAP only when state must persist or sequence.
+
+### Hover vocabulary (summary)
+
+| Effect | What it is | Tool | Where |
+|---|---|---|---|
+| Link underline | Line exits one side, redraws from the other (origin flip) | CSS | §3a |
+| Card hover scene | Image scale + caption rise + sibling dim on three clocks | CSS (`group`, `group/list`) | §3b |
+| Text swap | Label rolls out of its mask while its twin rolls in | CSS (JS + SplitText for per-char) | §3c |
+| Magnetic | Element and label drift toward the cursor, elastic return | GSAP `quickTo` | §1 |
+| Cursor follower | Lerped dot that becomes "View / Drag / Play" over opted-in elements | GSAP `quickTo` + delegation | §2 |
+| Image distortion on hover | Displacement/ripple of a texture under the pointer, WebGL only | R3F shader | [webgl-scenes.md](webgl-scenes.md) |
+
+Pick from this table by genre (see the selection heuristic at the end). Hover distortion on images is the heaviest item here, so it needs a real poster fallback and the one-canvas budget from [webgl-r3f.md](webgl-r3f.md).
+
+### a) Link underline: draws out one side, redraws from the other
+
+```tsx
+<a className="group relative inline-block text-ink" href="/work">
+  Selected work
+  <span aria-hidden className="absolute -bottom-0.5 left-0 h-px w-full origin-right scale-x-0
+                               bg-current transition-transform duration-400 ease-out-quart
+                               group-hover:origin-left group-hover:scale-x-100" />
+</a>
+```
+
+The origin flip (`origin-right` at rest, `origin-left` on hover) makes the line *exit the way it came in*: exit stage right, re-enter stage left. It is the detail people feel and can't name.
+
+### b) Card hover scene: image, caption, arrow, siblings
+
+```tsx
+export function WorkCard({ p }: { p: { img: string; title: string; tag: string } }) {
+  return (
+    // parent <ul> gets: className="group/list", enables sibling dimming.
+    // The <li> is the scroll-reveal target ([data-reveal], GSAP autoAlpha + y), so it carries
+    // NO transition and no opacity class: the dim lives on the inner <a>. A CSS opacity
+    // transition on a GSAP target leaves it stuck at opacity 0 (pitfalls.md §3.1).
+    <li data-reveal className="group">
+      <a href="#" className="block transition-opacity duration-500
+                             group-hover/list:opacity-40 group-hover/list:hover:opacity-100">
+        <div className="overflow-hidden">
+          <img src={p.img} alt="" className="aspect-[4/3] w-full object-cover
+                                             transition-transform duration-700 ease-out-expo
+                                             group-hover:scale-[1.06]" />
+        </div>
+        <div className="mt-4 flex items-baseline justify-between">
+          <h3 className="type-h3 text-h3">{p.title}</h3>
+          <span className="text-small translate-x-2 text-ink-muted opacity-0
+                           transition-all duration-400 delay-75 ease-out-quart
+                           group-hover:translate-x-0 group-hover:opacity-100">
+            {p.tag} →
+          </span>
+        </div>
+      </a>
+    </li>
+  );
+}
+```
+
+Three timings: image `700ms` (heavy thing, moves slow), tag `400ms` + `delay-75` (responds after), siblings `500ms` dim. **Sibling dimming** (`group/list` named group: list dims everyone, hovered card restores itself) is the single highest-value hover trick. It turns a grid into a spotlight.
+
+**Reveal the wrapper, transition the child.** The rule behind the markup above: an element GSAP animates (here the `li`, revealed by [scroll-reveals.md](scroll-reveals.md) §1) never also carries a CSS `transition-*` on a property GSAP writes (`opacity`, `transform`, `translate`, `scale`). Hover transitions go one level in. The same applies to Tailwind `translate-*`, `scale-*` and `rotate-*` offsets: GSAP sets those properties to `none` on its targets, so they belong on a child or a wrapper ([pitfalls.md](pitfalls.md) §3).
+
+### c) Text swap (slot-machine label)
+
+```tsx
+<button className="group relative overflow-hidden px-6 py-3">
+  <span className="block transition-transform duration-400 ease-out-expo
+                   group-hover:-translate-y-full">Get in touch</span>
+  <span aria-hidden className="absolute inset-x-6 top-full block transition-transform duration-400
+                               ease-out-expo group-hover:-translate-y-full">Get in touch</span>
+</button>
+```
+
+Label rolls up and out of its mask while its twin rolls in: the masked-reveal principle ([scroll-reveals.md](scroll-reveals.md)) at button scale. With per-char stagger it becomes the full slot-machine; that needs JS (SplitText chars + `stagger: 0.02`) and is worth it on exactly one element (the main CTA or logo).
+
+**Cheap tell:** `hover:shadow-xl hover:-translate-y-1` on cards: everything moves at once, on one duration, with a shadow change for "lift." **Instead:** Image, caption, and siblings on three different clocks; elevation never via shadow swell.
+
+---
+
+## 4. Micro-feedback (press, focus, toggle)
+
+The smallest layer: `whileTap` and friends. Motion is the right tool (state-driven):
+
+```tsx
+import { motion } from "motion/react";
+
+<motion.button
+  whileTap={{ scale: 0.97 }}
+  transition={{ duration: 0.15, ease: [0.25, 1, 0.5, 1] }}
+  className="... focus-visible:outline-2 focus-visible:outline-offset-4 focus-visible:outline-accent"
+>
+  Submit
+</motion.button>
+```
+
+- Press = scale **0.97**, 150ms. (Not 0.9, that's a toy.)
+- Focus rings: visible, offset, in the accent. Designed, not suppressed. Keyboard users get states as considered as hover users'.
+- Toggles/accordions animate `grid-template-rows: 0fr → 1fr` (or Motion `height: "auto"`), 300ms quart-out, with a chevron rotating on the same clock.
+
+---
+
+## 5. Animated icons (Lordicon / Lottie)
+
+An animated icon is a micro-interaction and obeys this file's rules: budget 2 to 3 per view, hover-gated, reduced-motion renders static (the still frame). It's state/lifecycle-driven (a Lottie player toggled on hover/click), so triggering lives in **Motion** territory, not GSAP.
+
+The discipline that separates "delightful" from "distracting" is **timing**, and it's locked:
+
+| Trigger | Duration | Notes |
+|---|---|---|
+| Click / tap | **≤ 500ms** | must keep up with repeat clicks; longer lags the cursor and annoys by the 3rd press |
+| Hover (decorative) | **1500-3000ms** | the delight sweet spot; more complex symbol → longer end |
+| GIF fallback loop | **2000-5000ms delay between loops** | only if tech forces a looping GIF |
+
+- **Never loop in a dashboard / standard UI**; trigger on hover instead. (Looping is for a page *loader*, not ambient decoration. Same as "nothing moves the user didn't cause," [feel-layer.md](feel-layer.md) §5.)
+- **No flashing/flickering** (seizure hazard); **natural physics only**. Unnatural bounce or motion that contradicts the icon's meaning leaves users unsettled.
+
+Full icon doctrine (source via Iconify, system vs decorative registers, color/state, labels, accessibility, touch targets) is in [iconography.md](iconography.md).
+
+**Cheap tell:** a row of icons all looping forever, or a 700ms "success" spin that lags every click. **Instead:** One hover-triggered animated anchor that plays once, ≤500ms on click, static under reduced motion.
+
+---
+
+## Selection heuristic
+
+| Site genre | Ship | Skip |
+|---|---|---|
+| Portfolio / studio | cursor "View" states, sibling dimming, magnetic CTA | none |
+| Campaign / launch | magnetic CTA, text-swap buttons, underline choreography | cursor follower (usually) |
+| Editorial / content | underline choreography, image scale-in-mask | magnetic, cursor |
+| SaaS / product | press feedback, focus design, hover scenes on cards | cursor follower, magnetic (almost always) |

package/skills/struq/references/mobile-composition.md

@@ -0,0 +1,70 @@
+# Mobile Composition: translating the art direction to 360-430px
+
+The scaling knob ([scaling.md](scaling.md)) already solves *sizing* on mobile, so do **not** re-introduce breakpoint size ladders here. What the knob can't solve is *composition*: overlaps, asymmetric grids, and lockups are authored in twelve columns, and a naive `grid-cols-1` collapse turns art direction back into the centered-stack template. This file is the translation table.
+
+The principle: **mobile keeps the attitude, not the geometry.** Asymmetry, trespass, and scale contrast must survive; the specific desktop arrangement doesn't. A mobile page that is a centered column of full-width blocks has lost the design even if every rem is correct.
+
+---
+
+## 1. Translation table: every desktop technique, its mobile form
+
+| Desktop technique | Mobile translation | What survives |
+|---|---|---|
+| **Layered lockup** ([composition.md](composition.md) §3): type and image sharing grid cells | Stack, but keep a *deliberate small overlap*: headline pulls `-mb-[0.5em]` over the image top (or image pulls under the headline's last line). Drop `mix-blend-difference` if the overlap zone gets busy at small width; a `pointer-events-none` scrim or plain ink type is more legible | the trespass |
+| **Asymmetric 12-col rows** (features as editorial rows, [anti-patterns.md](anti-patterns.md) §2) | Single column with **alternating indents** (`even:pl-[10vw]`) or a hanging eyebrow column (`grid-cols-[5rem_1fr]`). Never centered | the off-axis rhythm |
+| **Section bleed / seam** ([composition.md](composition.md) §1) | Keep it: negative margins are width-independent. Reduce overlap depth ~50% (`-mb-16` not `-mb-32`) so the seam doesn't eat a whole viewport | the trespass |
+| **Full-bleed breakout** ([composition.md](composition.md) §2) | The `content-grid` collapses gracefully (side lanes hit their 1.5rem floor), but full-bleed only *contrasts* if contained content is visibly inset. Keep body at the `content` lane; never let everything go edge-to-edge | contained vs escaping |
+| **Off-canvas ghost type** ([composition.md](composition.md) §4) | Shrink to ~24-30vw and keep the crop, or drop it. At 18vw-of-360px it's a smudge: if it can't be huge, it shouldn't exist | scale contrast (or nothing) |
+| **Hero composition** | Poster logic still applies: left-aligned h1 (centered mobile heroes = template), meta pushed to the hero's edges, media bleeding off one side rather than politely contained | the poster edges |
+| **Sticky-stack cards** ([depth-parallax.md](depth-parallax.md) §3) | **Keep**: sticky stacking is touch-native. Cards go `min-h-[100svh]` → content-height + `top` offset; keep the recede scrub | everything |
+| **Pinned / horizontal showpieces** | Never pin on touch. The §4 matchMedia + scroll-snap fallback in [pinning-scrub.md](pinning-scrub.md) is the law, not a suggestion | the content, natively |
+| **Multi-speed parallax** ([depth-parallax.md](depth-parallax.md) §1) | Halve the deltas (0.95/1/1.06) or drop to window-parallax only, since small screens amplify relative motion | one breathing layer |
+| **Footer-reveal** ([composition.md](composition.md) §5) | Keep if the footer fits `~60svh` at mobile width; otherwise release to normal flow (`fixed` + tall footers = covered content) | the close |
+
+---
+
+## 2. Mobile rhythm: the numbers
+
+Section padding compresses to roughly **60% of the desktop role values**, keeping the *ratio* between roles (the asymmetry is the design; the absolute air is negotiable):
+
+| Role | Desktop | Mobile |
+|---|---|---|
+| Hero | 12-20rem | 8-12rem |
+| Dense content | 6-8rem | 4-5rem |
+| Breather | 16-24rem | 10-14rem |
+
+- Express the compression **structurally** (`py-16 md:py-28`, a layout decision and therefore allowed) or via a `--section-pad` token per role. This is not a size ladder, it's one deliberate rhythm change.
+- **Display type floor:** hero h1 bottoms out at 2.875rem (46px at 390), or the pairing's own floor ([typography.md](typography.md) §3.1). The `text-display` token already handles it; check the *line count* instead: a mobile hero h1 over 4 lines needs shorter copy ([page-architecture.md](page-architecture.md) §5), not smaller type.
+- Body measure self-solves via the root knob; check `min-h-[100vh]` sections use `svh` so mobile browser chrome doesn't cause jumps.
+- Horizontal padding: 1.25 to 1.5rem lanes; keep at least one element per screen *ignoring* them (a bleed, a crop) so mobile keeps its grid-breaks too.
+
+---
+
+## 3. What to cut vs keep
+
+**Cut on touch (already hover-gated; verify, don't assume):** magnetic buttons, cursor followers, hover scenes ([micro-interactions.md](micro-interactions.md) gates them via `(hover: hover)`). Sibling-dimming and tag-slides need a non-hover story: default-visible tags, or active-state on tap.
+
+**Keep, tuned:**
+- Reveals and staggers: shorten travel (`y: 24` not 80) and durations ~15%; small screens exaggerate motion.
+- Split-line headlines: `autoSplit` re-splits at mobile line breaks for free ([scroll-reveals.md](scroll-reveals.md) §3).
+- The departure scrub ([pinning-scrub.md](pinning-scrub.md) §3): no pin, so it's touch-safe as-is.
+- Lenis: keep mounted (the provider doctrine, [setup.md](setup.md) §2). It applies lightly or not at all to native touch scrolling, and the ScrollTrigger wiring stays consistent.
+
+**Branch declaratively**, one `gsap.matchMedia()` block per component, the same pattern as reduced-motion ([setup.md](setup.md) §4). Never `if (window.innerWidth < 768)` at setup time: it doesn't revert on rotate/resize.
+
+---
+
+## 4. The two-viewport check, plus 768 where columns change
+
+Design every section at **1440 and 390 simultaneously**, not desktop-then-shrink. Then check **768** on every section whose column count changes at a breakpoint: `md` is 768px wide, and a 12-column split there gives a 5-column text lane about 280px wide, where an `h2` breaks into one word per line and an email input shrinks to nothing. Rule of thumb: **text-plus-media splits start at `lg`**, not `md`; between 768 and 1023 they stay stacked or go to an asymmetric single column. Offsets on revealed elements use padding or margin (`even:pl-[10vw]`), never a `translate-*` utility, which GSAP erases ([pitfalls.md](pitfalls.md) §3.2).
+
+Before moving on, ask of the 390 view:
+
+1. Is anything overlapping, bleeding, or cropped, or did it collapse to a centered stack?
+2. Do two consecutive sections still have different skeletons?
+3. Is the display type still *display* (≥3× body scale contrast)?
+4. Can a thumb reach/operate everything (48px targets, no pin traps)?
+5. Does the showpiece content still exist (as snap-scroll or stacked list), even though the showpiece mechanics don't?
+
+**Cheap tell:** a mobile view where every section is a centered full-width column: same skeleton repeating, overlaps gone, ghost type gone, hero centered. The art direction evaporated below 768px.
+**Instead:** The 390px page still has trespassing elements, alternating indents, one crop, poster-edge heroes, and compressed-but-asymmetric rhythm. It is recognizably the same design, recomposed.