@struq/skill 0.3.0 → 0.4.1

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

@@ -1,270 +0,0 @@
-# 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" ? "text-small 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

@@ -1,70 +0,0 @@
-# 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 meta column (`grid-cols-[5rem_1fr]`, a year or a place in `text-small`). 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.

package/skills/struq/references/nav-header.md

@@ -1,296 +0,0 @@
-# Navigation & Header: the most persistent component
-
-The header is on screen for 100% of the session; the menu is the one interaction every visitor performs. Templates treat both as chrome (white sticky bar, shadow on scroll, hamburger dropdown); agencies treat the menu as **a scene**, often the most art-directed moment on the site. Assumes the providers from [setup.md](setup.md) and the z-ladder from [composition.md](composition.md) §5 (nav = `z-50`, overlay menu joins it).
-
----
-
-## 1. Header anatomy
-
-- **Contents:** wordmark left, 3 to 5 links + one CTA right (or wordmark + menu button only, the "editorial minimal" header). Anything more belongs in the footer's nav echo ([page-architecture.md](page-architecture.md) §4).
-- **Height:** 4 to 5rem, authored in rem so it rides the scaling knob ([scaling.md](scaling.md)).
-- **Surface:** transparent over the hero, then, once real content scrolls under it, either a **hard surface swap** (`bg-surface-0` + `border-b border-line`, on-genre for editorial/brutalist) or `bg-surface-0/80` + `backdrop-blur-md` (the one sanctioned blur in the system, cinematic and luxury registers only; every other `backdrop-blur`, glass cards above all, stays on the blocklist in [../SKILL.md](../SKILL.md) AI-default blocklist). Never a drop shadow: the border *is* the elevation ([anti-patterns.md](anti-patterns.md) §1).
-- **Links:** body-size or smaller, tracked; hover = the origin-flipping underline ([micro-interactions.md](micro-interactions.md) §3 (a)), not a color swap.
-- Wordmark and CTA are prime candidates for the page's 1 to 3 magnetic elements ([micro-interactions.md](micro-interactions.md) §1).
-
-**Cheap tell:** `sticky top-0 bg-white shadow-md` with 7 gray links and a blue button. **Instead:** Transparent → surfaced on scroll, hairline-separated, 3 to 5 links, one designed CTA.
-
----
-
-## 2. Scroll behavior: hide-on-down / show-on-up
-
-The default for narrative pages: the header gets out of the way while reading (scrolling down) and returns the instant intent reverses (scrolling up). **Pick hide-on-scroll or shrink-on-scroll, never both.** Stacked behaviors read as nervous.
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP, ScrollTrigger } from "@/lib/gsap";
-
-export function Header({ children }: { children: React.ReactNode }) {
-  const el = useRef<HTMLElement>(null);
-
-  useGSAP(() => {
-    const show = gsap.quickTo(el.current, "yPercent", { duration: 0.4, ease: "power4.out" });
-
-    ScrollTrigger.create({
-      start: "top top",
-      end: "max",
-      onUpdate: (self) => {
-        if (self.scroll() < 80) { show(0); el.current!.dataset.surfaced = "false"; return; }
-        el.current!.dataset.surfaced = "true";
-        show(self.direction === 1 ? -100 : 0); // down → hide, up → return
-      },
-    });
-  }, { scope: el });
-
-  return (
-    <header ref={el} data-surfaced="false"
-            className="fixed inset-x-0 top-0 z-50 flex h-16 items-center justify-between px-6
-                       transition-colors duration-300
-                       data-[surfaced=true]:border-b data-[surfaced=true]:border-line
-                       data-[surfaced=true]:bg-surface-0/80 data-[surfaced=true]:backdrop-blur-md">
-      {children}
-    </header>
-  );
-}
-```
-
-Craft notes:
-- `quickTo` (not a tween per event): this fires every scroll frame; same one-clock rule as magnetic buttons.
-- The **80px grace zone** keeps the header stable over the hero; the surface swap and the hide behavior arrive together.
-- Direction flips mid-gesture must respond instantly. That's why show/hide is a `quickTo` chase, not a toggled class with a CSS transition fighting itself.
-- The **shrink variant** (height 5rem → 3.5rem + wordmark scale 0.85, same trigger, `power3.out` 0.35s) suits content-heavy sites where the header should stay visible but quiet.
-- Skip hiding entirely on short pages (< ~3 viewports): the behavior never gets room to read as intentional.
-
----
-
-## 3. The full-screen overlay menu (the agency staple)
-
-Menu opens = a full-viewport inverted panel wipes in; nav links render as **display type** with masked line staggers; a meta column carries contact/socials. The menu is a *destination*, not a dropdown.
-
-**Colour: invert the page.** The recipes ship `bg-ink text-surface-0`, which reads on every light preset (Soft Modern, Warm Editorial, Luxury Minimal). On a dark preset (Dark Cinematic), where `ink` is the light colour, use `bg-surface-3 text-ink` instead. Never `bg-surface-3 text-surface-0` on a light preset: that is cream on cream. On the inverted panel, `surface-0` is the text and `surface-2` the muted tier; `ink-muted` on `ink` fails contrast ([vibe-presets.md](vibe-presets.md), token contract).
-
-**Build it on an accessible primitive.** An overlay that covers the page is a modal dialog, and a modal needs a focus trap, Escape to close, `aria-modal` semantics, inert background content, and focus return to the trigger. Hand-rolling all of that is where menus break. Use **Radix Dialog** (`Dialog` from the unified `radix-ui` package that [setup.md](setup.md) installs) or an equivalent primitive (React Aria, Ark UI) and let it own accessibility while GSAP owns the motion. §3a shows the motion; §3b shows it wrapped in Radix, which is the version to ship.
-
-### 3a. The motion (reference sketch)
-
-```tsx
-"use client";
-
-import { useRef, useState } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-import { useLenis } from "lenis/react";
-
-const LINKS = [
-  { href: "/work", label: "Work" },
-  { href: "/studio", label: "Studio" },
-  { href: "/journal", label: "Journal" },
-  { href: "/contact", label: "Contact" },
-];
-
-export function OverlayMenu() {
-  const scope = useRef<HTMLDivElement>(null);
-  const panel = useRef<HTMLDivElement>(null);
-  const [open, setOpen] = useState(false);
-  const lenis = useLenis();
-
-  const { contextSafe } = useGSAP({ scope });
-
-  const toggle = contextSafe(() => {
-    const next = !open;
-    setOpen(next);
-    const links = gsap.utils.toArray<HTMLElement>("[data-menu-link]");
-
-    if (next) {
-      lenis?.stop(); // scroll lock: the Lenis-native way, no overflow:hidden fights
-      gsap.timeline()
-        .set(panel.current, { display: "block" })
-        .fromTo(panel.current, { yPercent: -100 }, { yPercent: 0, duration: 0.6, ease: "power4.inOut" })
-        .fromTo(links,
-          { yPercent: 110 },
-          { yPercent: 0, duration: 0.8, ease: "expo.out", stagger: 0.06 }, "-=0.15")
-        .fromTo("[data-menu-meta]", { autoAlpha: 0, y: 16 }, { autoAlpha: 1, y: 0, duration: 0.5 }, "<0.1");
-    } else {
-      gsap.timeline({ onComplete: () => { gsap.set(panel.current, { display: "none" }); lenis?.start(); } })
-        .to(links, { yPercent: -110, duration: 0.35, ease: "power2.in", stagger: { each: 0.03, from: "end" } })
-        .to(panel.current, { yPercent: -100, duration: 0.5, ease: "power4.inOut" }, "-=0.1");
-    }
-  });
-
-  return (
-    <div ref={scope}>
-      <button onClick={toggle} aria-expanded={open} aria-controls="site-menu"
-              className="font-ui text-ui relative z-[60]">
-        {open ? "Close" : "Menu"}
-      </button>
-
-      <div ref={panel} id="site-menu" role="dialog" aria-modal="true"
-           className="fixed inset-0 z-50 hidden bg-ink text-surface-0">
-        <nav className="flex h-full flex-col justify-between px-6 pb-10 pt-32">
-          <ul>
-            {LINKS.map((l) => (
-              <li key={l.href} className="-my-[0.1em] overflow-hidden py-[0.1em]">{/* the mask, with descender room */}
-                <a data-menu-link href={l.href}
-                   className="font-display text-display block">
-                  {l.label}
-                </a>
-              </li>
-            ))}
-          </ul>
-          <div data-menu-meta className="text-small flex justify-between">
-            <span>hello@studio.com</span><span>Oslo, 14:32</span>
-          </div>
-        </nav>
-      </div>
-    </div>
-  );
-}
-```
-
-Load-bearing details:
-- **`lenis.stop()` / `lenis.start()`** is the scroll lock. Never `overflow: hidden` on body, which fights the smooth-scroll provider and jumps the page.
-- Links live in `overflow-hidden` `<li>` masks: the masked line reveal ([scroll-reveals.md](scroll-reveals.md) §3) at menu scale, with the same 0.1em descender padding as `.split-line-mask`. The exit reverses with `power2.in` at ~60% duration and `from: "end"`, the designed exit rule ([transitions.md](transitions.md) §4).
-- The menu button sits **above** the panel (`z-[60]`) and swaps its label. The close affordance is designed, not a reflexive close-icon glyph.
-- Menu links can navigate through the page-flow wipe ([route-transitions.md](route-transitions.md)): close the menu, then `push(href)`, never both animations at once.
-- **A11y is non-optional:** `role="dialog"` + `aria-modal`, `aria-expanded`/`aria-controls` on the trigger, `Esc` closes, focus moves into the panel on open and returns to the trigger on close, and focus is trapped while open. The sketch above declares the semantics but does not implement the trap or Escape; §3b gets all of it from the primitive. Reduced motion: panel and links fade 0.2s, no travel.
-- In-page anchor variant (one-pagers): links call `lenis.scrollTo(target)` after close. `anchors: true` covers plain hash links already.
-
-### 3b. The same menu on Radix Dialog (ship this)
-
-Radix supplies the focus trap, Escape handling, `aria-modal`, inert background, and focus return to the trigger. GSAP keeps the choreography. The only wiring decisions are who controls `open`, and when the exit finishes.
-
-```tsx
-"use client";
-
-import { useCallback, useRef, useState, type MouseEvent } from "react";
-import { useRouter } from "next/navigation";
-import { Dialog } from "radix-ui";
-import { gsap } from "@/lib/gsap";
-import { useLenis } from "lenis/react";
-
-// LINKS as in §3a
-
-export function OverlayMenu() {
-  const [open, setOpen] = useState(false);
-  const panel = useRef<HTMLDivElement | null>(null);
-  const enterTl = useRef<gsap.core.Timeline | null>(null);
-  const closing = useRef(false);
-  const pendingHref = useRef<string | null>(null);
-  const router = useRouter();
-  const lenis = useLenis();
-
-  // Enter: Radix mounts the content, the ref callback plays the timeline.
-  const setPanel = useCallback((node: HTMLDivElement | null) => {
-    panel.current = node;
-    if (!node) return;
-    const links = node.querySelectorAll("[data-menu-link]");
-    enterTl.current = gsap.timeline()
-      .fromTo(node, { yPercent: -100 }, { yPercent: 0, duration: 0.6, ease: "power4.inOut" })
-      .fromTo(links, { yPercent: 110 },
-        { yPercent: 0, duration: 0.8, ease: "expo.out", stagger: 0.06 }, "-=0.15")
-      .fromTo(node.querySelector("[data-menu-meta]"), { autoAlpha: 0, y: 16 },
-        { autoAlpha: 1, y: 0, duration: 0.5 }, "<0.1");
-  }, []);
-
-  // Radix calls this for Escape, the Close button, and outside interaction.
-  // Opening is immediate; closing plays the exit first, then unmounts.
-  const onOpenChange = (next: boolean) => {
-    if (next) { lenis?.stop(); setOpen(true); return; }
-    if (closing.current || !panel.current) return;
-    closing.current = true;
-    enterTl.current?.kill(); // a fast close must not fight a half-played entrance
-    const node = panel.current;
-    gsap.timeline({
-      onComplete: () => {
-        closing.current = false;
-        setOpen(false);
-        lenis?.start();
-        const href = pendingHref.current;
-        pendingHref.current = null;
-        if (href) router.push(href); // navigate only after the exit has finished
-      },
-    })
-      .to(node.querySelectorAll("[data-menu-link]"),
-        { yPercent: -110, duration: 0.35, ease: "power2.in", stagger: { each: 0.03, from: "end" } })
-      .to(node, { yPercent: -100, duration: 0.5, ease: "power4.inOut" }, "-=0.1");
-  };
-
-  // Keep the real href (crawlers, middle-click, new tab) but take over a plain click.
-  const onLinkClick = (e: MouseEvent<HTMLAnchorElement>, href: string) => {
-    if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
-    e.preventDefault();
-    pendingHref.current = href;
-    onOpenChange(false);
-  };
-
-  return (
-    <Dialog.Root open={open} onOpenChange={onOpenChange}>
-      {/* Mobile-only menu: desktop shows inline links in the header (§4), so the trigger
-          hides from md up. Drop md:hidden for an "editorial minimal" header on every width. */}
-      <Dialog.Trigger className="font-ui text-ui h-12 md:hidden">Menu</Dialog.Trigger>
-
-      <Dialog.Portal>
-        <Dialog.Content ref={setPanel} aria-describedby={undefined}
-                        className="fixed inset-0 z-50 bg-ink text-surface-0">
-          <Dialog.Title className="sr-only">Site menu</Dialog.Title>
-
-          {/* The trigger is inert while the modal is open, so Close lives inside the panel.
-              It must sit EXACTLY over the header's Menu button: same right inset as the header's
-              px-6, same height (h-12) and the same vertical centre as the h-16 header bar, so the
-              label swaps in place instead of jumping. Change one, change both. */}
-          <Dialog.Close className="font-ui text-ui absolute right-6 top-2 h-12">
-            Close
-          </Dialog.Close>
-
-          <nav className="flex h-full flex-col justify-between px-6 pb-10 pt-32">
-            <ul>
-              {LINKS.map((l) => (
-                <li key={l.href} className="-my-[0.1em] overflow-hidden py-[0.1em]">
-                  <a data-menu-link href={l.href} onClick={(e) => onLinkClick(e, l.href)}
-                     className="font-display text-display block">
-                    {l.label}
-                  </a>
-                </li>
-              ))}
-            </ul>
-            <div data-menu-meta className="text-small flex justify-between">
-              <span>hello@studio.com</span><span>Oslo, 14:32</span>
-            </div>
-          </nav>
-        </Dialog.Content>
-      </Dialog.Portal>
-    </Dialog.Root>
-  );
-}
-```
-
-Notes on the Radix version:
-- **Controlled `open`** is what lets the exit animation finish before Radix unmounts the content. `onOpenChange(false)` starts the exit; `setOpen(false)` runs only in the timeline's `onComplete`.
-- **Scroll lock still coordinates with Lenis.** Radix applies its own modal scroll lock; keep `lenis.stop()` on open and `lenis.start()` after the exit so Lenis' wheel and touch handling halts too. Put `data-lenis-prevent` on any scrollable region inside the menu so it can scroll natively while Lenis is running elsewhere.
-- **`Dialog.Title` is required** for screen readers (hide it visually with `sr-only`). `aria-describedby={undefined}` is the documented way to opt out of a description when there isn't one.
-- **Focus** moves into the panel on open and returns to the trigger on close without extra code. Do not fight it with manual `focus()` calls.
-- **Links navigate client-side after the exit.** A plain `<a href>` navigates immediately and cuts the exit short, and a full reload drops the Lenis and transition providers. `onLinkClick` stores the target in `pendingHref`, prevents the default, starts the exit, and `router.push` runs in the exit timeline's `onComplete`, so the motion stays strictly sequential. The `href` stays real for crawlers and modified clicks. On a site with route curtains, swap `useRouter` for `useTransitionRouter()` from the provider in [route-transitions.md](route-transitions.md) (its `push` is the same `navigate` that `TransitionLink` calls) so the menu exit hands straight into the curtain.
-- **The enter timeline is kept in a ref and killed before the exit runs.** Escape pressed mid-entrance otherwise leaves two timelines writing the same `yPercent`.
-- **Reduced motion:** branch with `gsap.matchMedia()` ([setup.md](setup.md) §4) and replace the travel with a 0.2s `autoAlpha` fade in both timelines.
-
-**Cheap tell:** hamburger → white dropdown of body-size links sliding 200ms `ease-in-out`, with no focus trap and Escape ignored. **Instead:** A surface wipe, display-type links rising from masks, meta column, choreographed exit, scroll properly locked, and a real dialog primitive underneath.
-
----
-
-## 4. Mobile
-
-- **The overlay IS the mobile nav.** One menu system for all widths: desktop may *also* show inline links, mobile shows only wordmark + menu button. Never a separate "mobile hamburger dropdown." The usual split: the inline links carry `max-md:hidden`, the trigger carries `md:hidden` (§3b), and both live in the same header so the Close button can sit over Menu.
-- Touch targets ≥ 48×48px for the menu button and each link row ([iconography.md](iconography.md) §7); the display-type links clear this by default.
-- Hide-on-scroll stays on. It's *more* valuable on small screens where 4rem of chrome is 5% of the viewport. The `backdrop-blur` surface is fine on modern mobile; if the page is effect-heavy, prefer the hard surface swap (blur stacks with everything else on the compositor).
-- The wordmark stays ≤ ~40% of viewport width; long names abbreviate to a mark.
-
----
-
-## Header checklist
-
-- [ ] Transparent over hero → surfaced after ~80px (border or sanctioned blur, never shadow)
-- [ ] One scroll behavior (hide *or* shrink), quickTo-driven
-- [ ] 3 to 5 links + one CTA max; overlay menu for everything else
-- [ ] Menu: built on Radix Dialog (or equivalent), Lenis stop/start, masked link stagger in, reversed exit, ≤ 1s total
-- [ ] Dialog semantics from the primitive: title, Esc, focus trap + return; trigger has `aria-expanded`; reduced-motion fade
-- [ ] Mobile: same overlay, 48px targets, no dropdown variant