@struq/skill 0.2.2 → 0.4.0

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

package/skills/struq/references/page-architecture.md

@@ -1,134 +0,0 @@
-# Page Architecture: the Narrative Arc, Section Inventory & Footer
-
-Everything else in Struq makes a *section* excellent; this file decides **which sections exist and in what order**. It is the layer templates fake with "Hero / Features / Testimonials / Pricing / CTA", which is a stack, not a story. Read this **before** picking a vibe preset: the arc determines what you build; the preset determines how it looks.
-
-This file does not write the words. It only sets the *structural* budgets copy must fit (headline lengths, one manifesto line, eyebrow grammar).
-
----
-
-## 1. The arc: five beats, in order
-
-Every effective marketing/narrative page is the same dramatic shape:
-
-| Beat | Job | Typical sections | Pacing (spacing role) |
-|---|---|---|---|
-| **Hook** | Stop the scroll; claim a position in one line | Hero | vast: 12 to 20rem, one idea |
-| **Orient** | Who this is, in one breath | Intro / positioning statement | breather: a manifesto line (`font-display text-statement`) in 16 to 24rem of air |
-| **Prove** | Evidence: the work, the product, the numbers | Selected work / product walkthrough / capabilities | dense: 6 to 8rem, editorial rows |
-| **Deepen** | How and why, the thing competitors can't copy | Process / principles / about | medium; this is where the showpiece lives |
-| **Invite** | One ask, made unmissable | CTA block + footer | vast again: the close mirrors the open |
-
-Rules the arc enforces:
-
-- **5 to 8 sections total.** More is a pacing failure, not thoroughness, so cut or merge. (A section is a distinct visual movement, not every `<section>` tag.)
-- **One idea per beat.** If a section is doing two jobs (proving *and* explaining process), split it or cut half.
-- **Pacing alternates.** Dense, then breather, then dense. Two dense sections back-to-back read as a wall; two breathers as emptiness. This is the page-level version of the spacing-asymmetry rule.
-- **A showpiece is its own density class.** It is neither dense nor breather, even when it is airy on screen (`manifesto-fill`, a pinned single statement). So "breather, showpiece, breather" is legal and is the pattern (§3); it never counts as two breathers in a row. The no-two-breathers rule applies to plain sections only.
-- **The page ends where it started, louder.** The Invite beat re-states the Hook's claim as an action ("Studio for durable brands" becomes "Build something durable. Talk to us.").
-
-**Cheap tell:** Hero → 3-card Features → Stats → Testimonials → Pricing → FAQ → CTA. That is the template stack: every section the same weight, no beat structure. **Instead:** Five beats, alternating density, one showpiece, one ask.
-
----
-
-## 2. Per-genre section inventories
-
-| Genre | Inventory (in arc order) | Showpiece slot |
-|---|---|---|
-| **Portfolio** | Hero (name + role claim) → manifesto line → selected work (the meat, 60% of the page) → about/process → contact footer | horizontal work gallery (`pin-horizontal-gallery` in [showcase.md](showcase.md); technique in [pinning-scrub.md](pinning-scrub.md) §2) |
-| **Studio / agency** | Hero → positioning statement → selected work → capabilities (editorial rows) → process or principles → CTA + footer | pinned process sequence ([pinning-scrub.md](pinning-scrub.md) §1) |
-| **Product launch** | Hero (product as the visual) → the one-line why → product walkthrough → proof (numbers/logos/quotes, pick ONE form) → pricing or waitlist → footer | scrubbed product walkthrough |
-| **Campaign / event** | Hero (date/name as display type) → what/why → program or lineup → practical info → register CTA + footer | the hero itself (departure scrub + one act-break curtain) |
-
-Proof sections: choose **one** proof form and do it well: a logo wall *or* two strong pull-quotes *or* three big numbers. Stacking all three is the template reflex; one, art-directed, is the agency move.
-
-Showpiece slots name a technique; the named, copy-ready recipes (with ids) are cataloged in [showcase.md](showcase.md). Pick the recipe there once the slot is decided here.
-
-### 2b. Mapping a niche onto a genre
-
-Struq has no per-niche rulebook in the free skill, so derive the niche decisions in three moves: pick the nearest genre row above, set the proof form and the visitor's fear, then pour a preset from [vibe-presets.md](vibe-presets.md) (its seven axes) over the result. Common mappings:
-
-| Niche (by who signs the check) | Start from genre | The ONE proof form | Visitor fear to design against |
-|---|---|---|---|
-| Product brand (food/bev, skincare, fashion) | Product launch | the products themselves, shot well | "It will not be as good as the photos" |
-| Place people visit (restaurant, hotel, gym, clinic) | Campaign, with the room as the hero | the room and the people in it | "It will feel generic or unwelcoming" |
-| Service or practice (legal, medical, consulting, trades) | Studio / agency | two strong pull-quotes or outcomes | "I will be sold to, not helped" |
-| Show work (portfolio, photography, architecture) | Portfolio | the work, 60% of the page | "The taste will not hold up" |
-| Launch something (SaaS, AI, game, record) | Product launch or Campaign | numbers or the product in motion | "It is vapor, or one more template" |
-| Cause or institution (nonprofit, university) | Campaign | three big numbers | "My money or time will be wasted" |
-
-Classify by buyer and business model, not by surface topic: a legal-tech SaaS is a launch page for a software buyer, not a legal-practice page.
----
-
-## 3. Showpiece placement
-
-The 1 to 2 pinned/scrubbed showpieces ([pinning-scrub.md](pinning-scrub.md), catalog in [showcase.md](showcase.md)) are **act-breaks**, and placement is most of their value:
-
-- **Slot A, post-Prove:** after the work/product has earned attention, the showpiece explains *how* (process sequence). The classic studio-site shape.
-- **Slot B, the hero itself:** for campaign/launch pages where the product IS the show. If the hero becomes a WebGL scene, see [webgl-r3f.md](webgl-r3f.md) and [webgl-scenes.md](webgl-scenes.md).
-- **Never back-to-back.** Two consecutive scroll-jacked sections feel like a hostage situation; separate them with at least one natively-scrolling beat.
-- **Breathers flank the showpiece.** A vast, near-empty section before it (anticipation) and after it (recovery). A pin that starts mid-density feels like a malfunction. The showpiece is its own density class (§1), so its flanking breathers never count as two breathers back to back.
-- **Never in the Invite beat.** By the close, the user has decided; do not make them scrub through theater to reach the CTA.
-
----
-
-## 4. Footer anatomy: "designed as hard as the hero," specified
-
-The footer is the Invite beat's second half and the most-skipped design surface on the internet. The agency footer is a **destination**, not a sitemap dump:
-
-| Zone | Content | Treatment |
-|---|---|---|
-| **The ask** | One oversized CTA line ("Let's talk.", "Start a project") | `font-display text-display`, the footer's hero (the page's one other display line) |
-| **Nav echo** | 4 to 7 links max: the header nav repeated, not every route | `font-ui text-ui`, one column |
-| **Meta row** | location + local time, email, 2 to 4 socials, legal | `text-ink-muted`, baseline-aligned row |
-| **Signature** | wordmark (often oversized/cropped off the bottom edge), © year | the one place giant ghost type is almost always right |
-
-- Surface: step the ladder (footer on `surface-1` under a `surface-0` page, or inverted) so the close registers as a new room.
-- The **footer-reveal** pattern, where the page slides up to uncover a fixed footer ([composition.md](composition.md) §5), is the highest-payoff footer move and costs zero JS.
-- Local time (`Intl.DateTimeFormat` with the studio's zone) is a tiny detail that signals "real people, real place."
-- The oversized ask and wordmark are type decisions: see [typography.md](typography.md) for the fluid display scale.
-
-**Cheap tell:** four columns of gray links on `bg-gray-900`, a newsletter input nobody asked for, social icons in circles. **Instead:** One giant ask, a short nav echo, a meta row, an oversized wordmark, composed like a closing shot.
-
----
-
-## 5. The copy interface: structural budgets
-
-Copywriting is its own craft; the *architecture* constrains it so display type stays display type:
-
-- **Hero h1: ≤ ~8 words**, breaking into 1 to 3 lines of ≤ ~12ch at display size (`max-w-[12ch]` is the layout guard). Longer claims get demoted to the sub-line.
-- **One manifesto line per page**: a single sentence given a whole breather section. More than one and neither is the manifesto.
-- **Eyebrow grammar:** 1 to 3 words, uppercase, tracked. A *category label* ("Capabilities", "Selected work"), never a sentence, never punctuated.
-- **Section headline: ≤ ~10 words.** Body blocks: `max-w-[44-52ch]`, 2 to 4 sentences per block. Long arguments become editorial rows, not paragraphs.
-- **CTA labels: 2 to 4 words, verb-first** ("Start a project", not "Learn more about our services").
-- Real copy from the first draft: the baseline's no-lorem rule is architectural, because fake copy hides that a section has no actual job.
-
----
-
-## 6. Worked example: 7-section studio site, arc annotated
-
-```
-1  HERO         [Hook]    "Studio for durable brands", font-display text-display,
-                          departure scrub; media punches into §2 (seam #1)
-2  POSITIONING  [Orient]  one manifesto line, 20rem air above/below (breather)
-3  SELECTED     [Prove]   editorial rows + full-bleed images, dense 6 to 8rem,
-   WORK                   sibling-dimming hovers; ghost type crop (grid-break #2)
-4  CAPABILITIES [Prove]   hairline-divided list in 16rem breather air after §3's imagery
-5  PROCESS      [Deepen]  SHOWPIECE: pinned 3-phase sequence, ≤2.5 viewports,
-                          flanked by §4 and §6, both breathers
-6  PRINCIPLES   [Deepen]  2 to 3 numbered-ONCE oversized statements, breather spacing (16 to 24rem)
-7  CTA + FOOTER [Invite]  footer-reveal; "Let's build something durable." as
-                          the close: the hero's claim, made an action
-```
-
-Pacing trace: vast → breather → dense → breather → showpiece → breather → vast. Two grid-breaks, one showpiece, one proof form (the work itself), one ask.
-
----
-
-## Architecture checklist (run before building anything)
-
-- [ ] Every section assigned to a beat; any section without a beat is cut
-- [ ] 5 to 8 sections; density alternates; one manifesto breather exists
-- [ ] Exactly one proof form chosen
-- [ ] Showpiece (if any) at an act-break, flanked by calm, never doubled, recipe picked from [showcase.md](showcase.md)
-- [ ] Footer designed to the §4 anatomy before calling the page done
-- [ ] Hero h1 ≤8 words; every CTA verb-first; no section doing two jobs

package/skills/struq/references/page-entrances.md

@@ -1,198 +0,0 @@
-# Per-Zone Page Entrances: the `template.tsx` layer
-
-One arm of the page-flow system: what the *revealed* page does. Siblings: [route-transitions.md](route-transitions.md) (the cover→swap→reveal wipe this entrance overlaps) and [loaders.md](loaders.md) (the first-load overlay).
-
-`template.tsx` re-mounts on every navigation within a route group ([setup.md](setup.md) §6), so it's where the revealed page gets a subtle entrance. It overlaps the reveal so content rises in the cover's wake rather than popping. Differentiate zones: richer for marketing, quick for app.
-
-```tsx
-// app/(marketing)/template.tsx: expressive
-"use client";
-import { useRef } from "react";
-import { useGSAP, gsap, ScrollTrigger } from "@/lib/gsap";
-
-export default function Template({ children }: { children: React.ReactNode }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useGSAP(() => {
-    const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
-    gsap.from(ref.current, reduce
-      ? { opacity: 0, duration: 0.3, clearProps: "all" }
-      : { opacity: 0, y: 24, duration: 0.8, ease: "power3.out", clearProps: "all",
-          onComplete: () => ScrollTrigger.refresh() });
-  }, { scope: ref });
-  return <div ref={ref}>{children}</div>;
-}
-```
-
-```tsx
-// app/(app)/template.tsx: functional, fast
-"use client";
-import { useRef } from "react";
-import { useGSAP, gsap } from "@/lib/gsap";
-
-export default function Template({ children }: { children: React.ReactNode }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useGSAP(() => {
-    gsap.from(ref.current, { opacity: 0, duration: 0.25, ease: "power1.out", clearProps: "all" });
-  }, { scope: ref });
-  return <div ref={ref}>{children}</div>;
-}
-```
-
-**Two non-obvious, load-bearing details:**
-- **`clearProps: "all"`**: a leftover transform on this wrapper (even `translate(0,0)`) makes it a containing block for `position: fixed`, which silently breaks ScrollTrigger pinning for *every* section inside. Clearing props after the entrance removes the wrapper's footprint.
-- **`ScrollTrigger.refresh()` on complete**: trigger positions measured while the page was still offset (mid-entrance) are wrong. Refreshing after it settles re-measures against the final layout so pinned/scrubbed sections don't jump.
-
----
-
-## Hero entrances the presets name
-
-The template entrance above moves the whole page. The hero's own entrance is a separate, per-preset decision ([vibe-presets.md](vibe-presets.md)): Soft Modern's `weight-in` and Warm Editorial's `soft-scrub` live in [typography.md](typography.md) §5; the two below belong to Dark Cinematic and Luxury Minimal. Both follow the same rules as every recipe: a `"use client"` leaf, `useGSAP` with a scope ref, all animation inside the `no-preference` branch of `gsap.matchMedia()`, and the server markup already the final state for reduced motion.
-
-### `match-cut-hero`: image to type (Dark Cinematic)
-
-The hero opens on a full-bleed image, holds it for about a second, then cuts to the h1 sitting exactly where a shape in the image was (a horizon, an edge, a bright band). The cut is hard, or a 0.3s dissolve at most; the type itself does not rise. The shared shape is art direction: place the h1 on the image's horizon line at 1440 and at 390, and choose or crop the image so the shape lands there.
-
-```css
-/* globals.css: the type waits under the image only while motion is allowed */
-@media (prefers-reduced-motion: no-preference) {
-  [data-cut-hero]:not([data-cut]) [data-cut-type] { visibility: hidden; }
-}
-@media (prefers-reduced-motion: reduce) {
-  [data-cut-image] { display: none; } /* reduced motion opens on the type, no cut */
-}
-```
-
-```tsx
-"use client";
-import { useRef } from "react";
-import Image from "next/image";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-type NetInfo = { effectiveType?: string; saveData?: boolean };
-
-export function MatchCutHero({ src, title, cut = "hard" }: {
-  src: string; title: string; cut?: "hard" | "dissolve";
-}) {
-  const root = useRef<HTMLElement>(null);
-
-  useGSAP(() => {
-    const mm = gsap.matchMedia();
-    mm.add("(prefers-reduced-motion: no-preference)", () => {
-      const el = root.current!;
-      const img = el.querySelector<HTMLImageElement>("[data-cut-image] img");
-
-      // Shorter hold on slow or data-saving connections: the post-cut content is the LCP candidate.
-      const net = (navigator as Navigator & { connection?: NetInfo }).connection;
-      const slow = net?.saveData === true || /2g|3g/.test(net?.effectiveType ?? "");
-      const HOLD = slow ? 0.6 : 1;
-
-      const tl = gsap.timeline({ paused: true })
-        .call(() => { el.dataset.cut = "1"; }, [], 0) // the type is there at the cut
-        .to("[data-cut-image]", { autoAlpha: 0, duration: cut === "hard" ? 0 : 0.3, ease: "none" }, 0);
-
-      // The hold starts when the photo has PAINTED, never on mount: a hold over an empty frame
-      // is no match cut at all. Use delayedCall, not tl.delay(): play() ignores a delay set
-      // after the timeline was created.
-      let started = false;
-      let hold: gsap.core.Tween | undefined;
-      const start = (seconds: number) => {
-        if (started) return;
-        started = true;
-        hold = gsap.delayedCall(seconds, () => { tl.play(); });
-      };
-      const onLoad = () => start(HOLD);
-      img?.addEventListener("load", onLoad, { once: true });
-      if (img?.complete && img.naturalWidth > 0) onLoad();      // cached: already painted
-      const fallback = gsap.delayedCall(2.5, () => start(0));  // photo never came: open on the type
-
-      return () => {
-        tl.kill(); hold?.kill(); fallback.kill();
-        img?.removeEventListener("load", onLoad);
-        delete el.dataset.cut;
-      };
-    });
-  }, { scope: root });
-
-  return (
-    <section ref={root} data-cut-hero
-             className="relative grid min-h-svh items-end overflow-clip bg-surface-0 px-6 pb-[12svh]">
-      <h1 data-cut-type className="font-display text-display max-w-[16ch]">{title}</h1>
-      <div data-cut-image aria-hidden className="absolute inset-0">
-        {/* LCP hint: `preload` or `priority`, whichever the installed next/image declares (setup.md §0, Known API shifts) */}
-        <Image src={src} alt="" fill preload sizes="100vw" className="object-cover" />
-      </div>
-    </section>
-  );
-}
-```
-
-- **The hold is gated on the image.** `img.complete` (cached) or its `load` event starts a `gsap.delayedCall` for the hold, with a 2.5s fallback straight to the type. A timeline with `delay: 1` on mount fires the cut over an empty frame whenever the photo is remote or slow, and a delay set later with `tl.delay()` is ignored by `play()`. Verify it with a frame trace: the hold frame must be the photo ([pitfalls.md](pitfalls.md) §3.3).
-- **LCP is not free here.** The h1 is in the HTML from the start, hidden only by CSS while motion is allowed, and whatever is hidden until the cut (the h1, a product shot) becomes the LCP candidate the moment it appears. So lab LCP lands after hold plus cut, and fails the 2.5s floor ([performance.md](performance.md) §1) whenever the post-cut content paints a larger area than the photo did. Keep the post-cut hero smaller than the photo's painted area, and keep the shorter hold on slow connections (`HOLD` above). Measure it with the LCP probe in [performance.md](performance.md) §8; never assume it.
-- Add `<noscript><style>{"[data-cut-image]{display:none!important}[data-cut-type]{visibility:visible!important}"}</style></noscript>` to the root layout's `<head>`, so a JS failure opens on the type.
-- With a loader, start the hold as the loader exits ([loaders.md](loaders.md)), not on mount, or the cut happens behind the curtain.
-- **When not to:** when the image has no shape the type can land on (a cut with no shared shape is just a slideshow), and when the post-cut hero must be larger than the photo's painted area and LCP under 2.5s is a hard requirement: then open on the type and let the image follow.
-
-### `clip-line-hero`: the 1.6s single-line clip (Luxury Minimal)
-
-One line of display type, revealed by one slow `clip-path` wipe from left to right. No split, no stagger, no y-travel: the restraint is the move.
-
-```css
-/* globals.css: pre-paint guard, same shape as line-rise-hero */
-@media (prefers-reduced-motion: no-preference) {
-  [data-clip-line]:not([data-ready]) { clip-path: inset(0% 100% 0% 0%); }
-}
-```
-
-```tsx
-"use client";
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-export function ClipLineHero({ children }: { children: string }) {
-  const root = useRef<HTMLDivElement>(null);
-
-  useGSAP(() => {
-    const mm = gsap.matchMedia();
-    mm.add("(prefers-reduced-motion: no-preference)", () => {
-      const line = root.current!.querySelector<HTMLElement>("[data-clip-line]")!;
-      gsap.fromTo(line,
-        { clipPath: "inset(0% 100% 0% 0%)" },
-        { clipPath: "inset(0% 0% 0% 0%)", duration: 1.6, ease: "power4.inOut", delay: 0.2,
-          clearProps: "clipPath" }); // no clip left on the glyphs once it is open
-      line.dataset.ready = "1"; // the inline start clip now holds the line hidden
-    });
-  }, { scope: root });
-
-  return (
-    <div ref={root}>
-      <h1 data-clip-line className="font-display text-display -my-[0.1em] whitespace-nowrap py-[0.1em]">
-        {children}
-      </h1>
-    </div>
-  );
-}
-```
-
-- `fromTo` renders its start clip immediately, so `data-ready` can lift the CSS guard in the same tick without a flash. The 0.1em padding pulled back with a negative margin keeps descenders inside the clipped box at leading 0.92. An italic last glyph overhangs its box on the right: add `px-[0.08em] -mx-[0.08em]` too when the line ends in italic ([pitfalls.md](pitfalls.md) §1).
-- `power4.inOut` is the baseline's curtain ease: the wipe is a curtain drawn across one line. 1.6s is the top of the hero band, which Luxury Minimal's motion personality owns.
-- Add `<noscript><style>{"[data-clip-line]{clip-path:none!important}"}</style></noscript>` to the root layout's `<head>`.
-- One line only. If the copy needs two lines at 390px, shorten the copy ([page-architecture.md](page-architecture.md) §5); a two-line clip wipe reads as two reveals.
-
----
-
-## Timing reference
-
-| Phase | Duration | Ease | Transform |
-|---|---|---|---|
-| Marketing entrance | 0.8s | `power3.out` | `y 24→0` + fade |
-| App entrance | 0.25s | `power1.out` | fade |
-| Match cut (Dark Cinematic) | 1s hold from image load (0.6s on slow connections, 2.5s fallback), then 0s or 0.3s | `none` | image `autoAlpha` to 0, type static |
-| Single-line clip (Luxury Minimal) | 1.6s | `power4.inOut` | `clip-path` inset wipe |
-| **Reduced motion** | 0.3s | none | opacity only |
-
----
-
-## Anti-pattern (sweep before shipping)
-
-- **Forgetting `clearProps`/`refresh`** → broken pins on revealed pages. If a pinned section jumps only after navigating (not on hard reload), this is the cause ([pitfalls.md](pitfalls.md) §2).
-- **A timed entrance started on mount** while it depends on an image, a font or a loader → it plays behind the curtain or over an empty frame. Start it from the thing it waits for ([pitfalls.md](pitfalls.md) §3.3).