@struq/skill 0.0.0-stage → 0.2.1

package/skills/struq/references/scaling.md

@@ -0,0 +1,151 @@
+# The Scaling System: fluid root-rem, one knob
+
+The single most expensive recurring mistake is building a layout that looks right at
+one width and then fixing every element by hand at every other width. That tax comes
+from authoring in pixels and treating breakpoints as *resize* tools. This file kills it:
+**one root-level knob scales everything proportionally**, and breakpoints are reserved
+for genuine *layout changes* (column count, stack to row), never for resizing.
+
+The mental model: design once at a reference width; the whole interface (type, padding,
+gaps, component sizes) breathes in and out together as the viewport changes. No
+per-element viewport patching.
+
+---
+
+## 1. The knob: scale the root font-size with the viewport
+
+Everything authored in `rem` is measured against `html`'s font-size. Scale that one
+value with the viewport and *every rem in the build scales with it at once.*
+
+```css
+/* app/globals.css (Next) or src/index.css (Vite): the ONE knob */
+html {
+  font-size: clamp(1rem, 0.92rem + 0.2vw, 1.125rem);
+  /* 16px up to about 640w (so 16px at 390), about 17.6px at 1440, frozen at 18px from about 1640 */
+}
+```
+
+### Why this exact form (the a11y-safe part, do not skip)
+
+A pure-`vw` root (`font-size: 2.6vw`) scales beautifully **but breaks browser zoom and
+the user's font-size preference**: `vw` ignores both, so zoom does nothing to text and
+accessibility is gone. The fix is to **always keep a `rem` term in the expression**:
+
+```
+clamp( MIN_rem ,  REM_BASE_rem  +  SLOPE_vw ,  MAX_rem )
+                  └── zoomable anchor ──┘  └ fluid part ┘
+```
+
+The `REM_BASE` term responds to zoom and OS font settings; the `vw` term adds the fluid
+scaling on top. Result: proportional scaling **and** working zoom. This is the only
+acceptable form. A clamp whose middle term is `vw`-only is the same bug as pure-`vw`.
+
+> Deriving the middle term: pick two anchors, (minViewport, minRoot) and
+> (maxViewport, maxRoot), both in px. `slope_vw = 100 * (maxRoot - minRoot) / (maxVp - minVp)`,
+> `base_rem = (minRoot - slope_vw/100 * minVp) / 16`. Or just use a fluid-clamp
+> calculator and paste. The two clamp ends are your readable floor and ceiling.
+
+---
+
+## 2. Keep the root band narrow, layer the drama on top
+
+The root knob also scales **body text**, so a wide band makes body huge on 4K or tiny on
+mobile. Keep the band **modest and readable** (16px to 18px, frozen from about 1640). The body
+should feel basically the same size everywhere; what you want scaling dramatically is the
+*display* type and *section rhythm*, not paragraphs.
+
+So the system is two layers:
+
+1. **Root knob (narrow band)** carries proportional scaling of all spacing, gaps,
+   component sizes, and body text. Set once, never touched again.
+2. **Per-element `clamp()` on the extremes**: the hero/display type keeps its own
+   aggressive fluid clamp *on top* of the root:
+   ```css
+   /* the text-display role token (typography.md §2.4): 46px at 390, about 120px at 1440 */
+   @theme { --text-display: clamp(2.875rem, 1.2rem + 6.86vw, 8rem); }  /* drama lives here, not in the root */
+   ```
+   These two compose cleanly: the root scales the rem baseline gently; the hero's own
+   clamp adds the big swing. The middle term keeps its `rem` part, so zoom still scales
+   the hero; a `vw`-only middle (`clamp(3rem, 8vw, 9rem)`) is the same bug as a pure-`vw`
+   root. Components use the token (`font-display text-display`), never a hand-written clamp.
+
+Rule of thumb: **if it's body, labels, padding, gaps, radii, use plain rem and let the root
+carry it. If it's a display headline or a showpiece measurement, give it its own
+`clamp()`.** The full display-type scale (sizes, tracking, leading per tier) lives in
+[typography.md](typography.md).
+
+---
+
+## 3. Author in rem: no px for anything that should scale
+
+This is the discipline that makes the knob work:
+
+- **Type:** rem (Tailwind `text-*` is already rem). Display type: its own `clamp()`.
+- **Spacing / padding / gap / margin:** rem (Tailwind `p-*`, `gap-*`, `space-*`, `m-*`
+  are already rem). Section padding stays role-varied per the
+  [baseline](baseline-prompt.md), just expressed in rem so it scales.
+- **Component sizing, max-widths, radii:** rem / `ch` / `%`. `max-w-[44ch]` scales with
+  type; `rounded-[0.5rem]` scales with the knob.
+- **Hairlines & true 1px details:** `px` is correct. Borders, focus rings, and
+  decorative hairlines should stay crisp at 1px and must NOT scale. This is the one place
+  px is right.
+- **Media:** width in `%`/`rem`/`vw`, height via aspect-ratio (also prevents CLS).
+
+Tailwind (v4 or later) cooperates for free: its spacing scale and font sizes are rem-based, so once
+the root is wired, every utility inherits the scaling. You mostly just *stop reaching for
+arbitrary px values*.
+
+---
+
+## 4. Breakpoints change layout, never size
+
+With the knob doing the resizing, breakpoints (`md:`, `lg:`) are freed for their real
+job: **structural** changes that fluid scaling can't express.
+
+- column count: `grid-cols-1 md:grid-cols-12`
+- direction: `flex-col lg:flex-row`
+- show/hide: a nav collapsing to a menu
+- composition swaps: a 50/50 split becoming full-bleed
+
+You should rarely write `text-2xl md:text-4xl lg:text-6xl` ladders again. That's the
+manual-resize anti-pattern the root knob replaces. One fluid value, no ladder.
+
+---
+
+## 5. Bounds and the test matrix
+
+- **Ceiling:** the upper `clamp()` arm freezes growth so 2560px+ monitors don't keep
+  inflating. Past ~1600 to 1920 the design should *stop scaling and start adding margin*,
+  not get bigger. (Cap the content container with a rem/`ch` max-width.)
+- **Floor:** the lower arm holds the readable minimum; never let the knob drive body
+  below 16px effective or labels below the 12px floor ([anti-patterns.md](anti-patterns.md) §12).
+- **Test at 360 / 768 / 1280 / 1920 / 2560.** If every element looks proportional at all
+  five *without per-width overrides*, the system is working. If you're adding `lg:`
+  size overrides to fix spacing, something was authored in px: find it and convert.
+- **Zoom test:** Ctrl/Cmd-+ to 150% must enlarge text. If it doesn't, a `vw`-only value
+  leaked into the root or into a font-size. Fix it (see §1).
+
+---
+
+## 6. Wiring per stack
+
+The knob is just CSS, so it's framework-agnostic. Only the file differs:
+
+```css
+/* Next App Router → app/globals.css   |   Vite → src/index.css (imported in main.tsx) */
+@import "tailwindcss";
+
+html { font-size: clamp(1rem, 0.92rem + 0.2vw, 1.125rem); }
+```
+
+Full stack-detection and the rest of the primitive translations are in
+[stack-targets.md](stack-targets.md). Nothing else about scaling changes between Vite and
+Next: it's one CSS rule in the global stylesheet either way.
+
+---
+
+**Cheap tell:** px-everything layout with `sm: md: lg: xl:` size ladders on type and
+padding, hand-tuned per breakpoint, that still drifts at 1440 and 2560 and needs a fresh
+override every time a new screen is tested.
+**Instead:** One a11y-safe root clamp, everything in rem, breakpoints only for structural change,
+display type on its own `clamp()`: proportional at every width with zero per-element fixes.

package/skills/struq/references/scroll-reveals.md

@@ -0,0 +1,280 @@
+# Scroll-Driven Reveals
+
+The single highest-payoff motion category. Three techniques, in ascending order of drama: staggered group reveals, masked reveals, and split-text line reveals. All assume the providers from [setup.md](setup.md). Shipping values (durations, eases, staggers) justified in [feel-layer.md](feel-layer.md).
+
+**A reveal misbehaving?** Content stuck invisible, an offset that vanished, clipped descenders: [pitfalls.md](pitfalls.md) first, symptom by symptom.
+
+---
+
+## 1. Staggered group reveal
+
+**Term:** Orchestrated entrance / stagger choreography.
+**Mechanic:** Sibling elements enter with a shared transform + opacity, offset in time by 0.06 to 0.1s each, triggered when the group scrolls into view. The offsets create a reading order. The eye is led, not flooded.
+
+**When:** Default for any group: nav items, card rows, list items, footer columns. Basically never overkill; this is the floor, not the ceiling.
+**Cost:** Negligible (transform/opacity only).
+
+```tsx
+"use client";
+
+import { useRef } from "react";
+import { gsap, useGSAP } from "@/lib/gsap";
+
+export function FeatureRow({ children }: { children: React.ReactNode }) {
+  const container = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const mm = gsap.matchMedia();
+      // Reduced motion: nothing registers, the server markup is already the final state.
+      mm.add("(prefers-reduced-motion: no-preference)", () => {
+        gsap.from("[data-reveal]", {
+          y: 48,
+          autoAlpha: 0,
+          duration: 0.9,
+          ease: "expo.out",
+          stagger: { each: 0.08, from: "start" }, // try "center" or "edges" for non-linear rows
+          scrollTrigger: {
+            trigger: container.current,
+            start: "top 78%",   // fire while approaching, not at the edge; feels anticipatory
+            once: true,          // entrances happen once; re-triggering reads as a glitch
+          },
+        });
+      });
+    },
+    { scope: container }
+  );
+
+  return (
+    <div ref={container} className="grid grid-cols-12 gap-6">
+      {children /* each child carries data-reveal */}
+    </div>
+  );
+}
+```
+
+**Hard rule: one owner per property per element.** A `[data-reveal]` element never carries a CSS `transition-*` on a property this tween writes (`transition-opacity`, `transition-transform`, `transition-all`), and never a Tailwind `translate-*`, `scale-*` or `rotate-*` utility. The transition fights the inline values GSAP writes and can leave the element at `opacity: 0; visibility: hidden` with the tween at progress 1; GSAP sets the individual `translate`, `scale` and `rotate` properties to `none`, which erases the utility. Reveal the wrapper, put hover transitions and offsets on a child. Symptoms and checks: [pitfalls.md](pitfalls.md) §3.
+
+Notes that separate this from the reflex version:
+- `start: "top 78%"`: content is already moving as it enters the eye line. `"top bottom"` fires too early (animates off-screen), `"top top"` too late.
+- `once: true` for entrances. Scrub-tied effects may repeat; entrances may not.
+- Vary the stagger origin: a centered logo wall feels better with `from: "center"`.
+- Motion swap: for a one-off, `<motion.div initial={{ opacity: 0, y: 48 }} whileInView={{ opacity: 1, y: 0 }} viewport={{ once: true, margin: "-22%" }} transition={{ duration: 0.9, ease: [0.16, 1, 0.3, 1] }}>` is fine. Use GSAP once multiple groups need coordination.
+
+**Cheap tell:** every element fades in with `opacity: 0 → 1`, no transform, all at once, `duration-300 ease-in-out` (the "AOS fade" look). **Instead:** Transform + stagger + expo-out, triggered at 78%.
+
+---
+
+## 2. Masked / clip-path reveal
+
+**Term:** Mask reveal (wipe).
+**Mechanic:** The element doesn't fade *into* view. It's *uncovered*, as if sliding out from behind an invisible edge. Two implementations: **overflow mask** (parent `overflow-hidden`, child translates up from 110%) and **clip-path wipe** (`inset()` animates open). The motion has a surface to interact with, which is what reads as physical.
+
+**When:** Images, hero media, big standalone statements. The signature "agency" reveal.
+**Overkill when:** applied to every paragraph. Masks are for moments; body content uses technique 1.
+**Cost:** `clip-path` and transforms are paint/composite-only. Cheap.
+
+```tsx
+"use client";
+
+import { useRef } from "react";
+import { gsap, useGSAP } from "@/lib/gsap";
+
+// A) Overflow mask: image slides up from behind its own bottom edge,
+//    while scaling down from 1.25 → 1 ("settle") for a parallax-like richness.
+export function MaskedImage({ src, alt }: { src: string; alt: string }) {
+  const container = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const tl = gsap.timeline({
+        scrollTrigger: { trigger: container.current, start: "top 75%", once: true },
+        defaults: { duration: 1.2, ease: "expo.out" },
+      });
+      tl.from(container.current, { yPercent: 18, autoAlpha: 0 }, 0)
+        .from("img", { yPercent: 24, scale: 1.25 }, 0); // counter-move: frame up, image down
+    },
+    { scope: container }
+  );
+
+  return (
+    <div ref={container} className="overflow-hidden rounded-sm">
+      <img src={src} alt={alt} className="block h-full w-full object-cover" />
+    </div>
+  );
+}
+
+// B) Clip-path wipe, for blocks where overflow-hidden would clip siblings.
+export function WipeReveal({ children }: { children: React.ReactNode }) {
+  const el = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      gsap.fromTo(
+        el.current,
+        { clipPath: "inset(100% 0% 0% 0%)" },                  // covered from top
+        {
+          clipPath: "inset(0% 0% 0% 0%)",
+          duration: 1.1,
+          ease: "power4.inOut",                                 // wipes read best with in-out
+          scrollTrigger: { trigger: el.current, start: "top 80%", once: true },
+        }
+      );
+    },
+    { scope: el }
+  );
+
+  return <div ref={el}>{children}</div>;
+}
+```
+
+The **counter-move** in (A) is the load-bearing detail: container and image translate in opposite directions, so the image appears to be revealed *through* a window rather than sliding as a sticker. Same trick powers parallax-in-mask ([depth-parallax.md](depth-parallax.md)).
+
+**Cheap tell:** image scales from 0.8 with a fade ("zoom-in card"), or slides as one rigid block. **Instead:** Frame and content counter-translate inside an overflow mask.
+
+---
+
+## 2C. Curtain section reveal (named preset)
+
+**Term:** Curtain section reveal (a.k.a. "the curtain reveal").
+**Mechanic:** The clip-path wipe (2B) *paired with a counter-scale on the inner image*, fired per media frame as a row/section enters view. The frame is **uncovered bottom-up** (`inset(100% 0 0 0)` → `inset(0)`) while the image behind **settles back from a slight zoom** (`scale 1.2 → 1`), both from the same trigger. The picture is drawn up like a rising curtain while the image "breathes" into place behind it. The two tweens are the whole effect: clip alone is flat; clip + counter-scale is what reads as premium and physical.
+
+**When:** Editorial media rows, alternating image/text sections, case-study frames, discipline mosaics. The default "professional section entrance" for imagery on a narrative page. Ready-made named showpiece recipes built on presets like this one are catalogued in [showcase.md](showcase.md).
+**Overkill when:** tiny thumbnails, logo walls, or anything below ~240px tall. The wipe needs vertical distance to read.
+**Cost:** `clip-path` + `transform` only (paint/composite). Cheap. Composes cleanly with a parallax `yPercent` drift on the *same* inner element (translate + scale coexist).
+
+```tsx
+// Clip on the OUTER frame, counter-scale on the INNER image, one timeline, once per frame.
+gsap.utils.toArray<HTMLElement>("[data-curtain]").forEach((frame) => {
+  const inner = frame.querySelector("[data-curtain-inner]");
+  const tl = gsap.timeline({
+    scrollTrigger: { trigger: frame, start: "top 88%", once: true },
+    defaults: { ease: "power4.out" },
+  });
+  tl.fromTo(
+    frame,
+    { clipPath: "inset(100% 0% 0% 0%)" },       // covered from the bottom up
+    { clipPath: "inset(0% 0% 0% 0%)", duration: 1.1 },
+  );
+  if (inner) tl.fromTo(inner, { scale: 1.2 }, { scale: 1, duration: 1.4 }, "<"); // settle, same start
+});
+```
+
+Details that matter:
+- **Clip on the frame, scale on the inner child**: never both on one node, or the scale visibly drags the clip edge. Structure: `<div data-curtain><div data-curtain-inner><img/></div></div>`.
+- `"<"` starts the scale at the **same instant** as the clip; the slightly longer scale duration (1.4 vs 1.1) means the image keeps easing after the curtain is fully open. That trailing settle is the premium tell.
+- `start: "top 88%"` fires just before the frame is comfortably in view; `once: true` (entrances never re-fire).
+- **Do not also wrap the frame in a fade-in** (e.g. a `FadeIn`/`whileInView` opacity). The curtain *is* the entrance; a fade on top muddies it. Give the media its curtain and nothing else.
+- **Reduced-motion:** register the tween only under `(prefers-reduced-motion: no-preference)` and set no initial clip in CSS, so motion-off renders the image fully visible with zero JS. No FOUC.
+- Pairs with: a parallax drift on `[data-curtain-inner]` ([depth-parallax.md](depth-parallax.md)) and an entrance-drawn connector line between frames (DrawSVG, recipes in [svg-motion.md](svg-motion.md); API surface in [gsap-api.md](gsap-api.md)).
+
+**Cheap tell:** the frame just fades/zooms in as one block, or the clip runs with no scale. **Instead:** Bottom-up clip on the frame + counter-scale settle on the image, same trigger, image easing a beat longer.
+
+---
+
+## 3. Line-by-line text split (SplitText)
+
+**Term:** Masked line reveal / line stagger.
+**Mechanic:** SplitText slices a heading into line elements, each wrapped in an `overflow: clip` mask; lines translate up from 110% below their own mask, staggered. The text appears to rise out of the page in slats, the canonical award-site headline entrance.
+
+**When:** Hero h1, section headlines, pull quotes. 3 to 6 uses per page.
+**Overkill when:** body paragraphs (use a plain fade-up), or per-**char** splits on long text (chars are for short display words only; char-staggering a sentence looks like a typewriter toy).
+**Cost:** Splitting mutates DOM and measures layout. Fine for headlines, do not split hundreds of nodes. `aria` handling is automatic (SplitText sets `aria-label` on the parent).
+
+```tsx
+"use client";
+
+import { useRef } from "react";
+import { gsap, useGSAP, SplitText } from "@/lib/gsap";
+
+export function SplitHeadline({
+  children,
+  as: Tag = "h2",
+  className = "",
+}: {
+  children: string;
+  as?: "h1" | "h2" | "h3" | "p";
+  className?: string;
+}) {
+  const container = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const mm = gsap.matchMedia();
+      mm.add("(prefers-reduced-motion: no-preference)", () => {
+        SplitText.create(container.current!.querySelector("[data-split]"), {
+          type: "lines",
+          mask: "lines",        // wraps each line in an overflow-clipped .split-line-mask
+          autoSplit: true,      // re-splits on font load / resize; animation must live in onSplit
+          linesClass: "split-line",
+          onSplit: (self) =>
+            gsap.from(self.lines, {
+              yPercent: 110,
+              duration: 1.1,
+              ease: "expo.out",
+              stagger: 0.09,
+              scrollTrigger: { trigger: container.current, start: "top 80%", once: true },
+            }),
+        });
+      });
+    },
+    { scope: container }
+  );
+
+  return (
+    <div ref={container}>
+      <Tag data-split className={className}>
+        {children}
+      </Tag>
+    </div>
+  );
+}
+
+// Usage:
+// <SplitHeadline className="font-display text-h2 max-w-[20ch]">
+//   Design that survives contact with reality
+// </SplitHeadline>
+```
+
+```css
+/* globals.css: descender room inside each line mask (class = linesClass + "-mask"), no layout jump */
+.split-line-mask { padding-block: 0.1em; margin-block: -0.1em; }
+```
+
+Details that matter:
+- `mask: "lines"` + `yPercent: 110` is the whole effect. Without the mask it's just a stagger fade; with it, each line is born at its own baseline.
+- `autoSplit: true` + returning the tween from `onSplit` makes the split responsive and font-safe: GSAP reverts and re-runs on reflow. This API needs GSAP 3.13 or later; do not use the old `new SplitText()` + manual resize listeners.
+- Set the headline with its role token (`text-display`, `text-h2`) *before* splitting: the token carries the pairing's tight leading, and masks clip to line boxes, so loose leading shows gaps.
+- Descenders: the `.split-line-mask` rule above pads each mask and pulls the margin back, so g/y/p are never clipped and the layout does not move. It is not the only place a descender dies: parent overflow, reveal wrappers sized to the line height, clip-path insets and italic overhang all clip too. The full list and the 10-second "Gyp, jq." test: [pitfalls.md](pitfalls.md) §1.
+- Section headlines use this scroll version; the hero has its own load-time variant (`line-rise-hero`, [typography.md](typography.md) §5), and the masked rise is one technique among the presets' named entrances. It is a tell only as the hero's sole gesture, with no signature move and no preset entrance behind it.
+- Reduced motion: the split and the tween exist only in the `no-preference` branch, so the server markup stays the final state.
+- Scrub variant for manifesto paragraphs: split into `words`, set initial `opacity: 0.15`, and `gsap.to(words, { opacity: 1, stagger: 0.05, scrollTrigger: { scrub: true, start: "top 70%", end: "top 20%" } })`, the "reading highlights itself" effect.
+- Motion swap: only if you refuse GSAP. Manually wrap lines and animate `y` with `whileInView`. SplitText's measurement/re-split handling is why GSAP wins here.
+- SplitText typography choreography in depth: [typography.md](typography.md).
+
+**Cheap tell:** whole headline fades in as one block; or chars typewriter in one-by-one with uniform linear timing. **Instead:** Lines rise from individual masks, 0.09s apart, expo-out.
+
+---
+
+## Orchestrating a full section
+
+Reveals compose into one timeline per section so the elements *relate* (label → headline → body → media), instead of each element wearing its own trigger:
+
+```tsx
+useGSAP(
+  () => {
+    const tl = gsap.timeline({
+      scrollTrigger: { trigger: container.current, start: "top 70%", once: true },
+      defaults: { ease: "expo.out", duration: 1 },
+    });
+
+    tl.from("[data-eyebrow]", { y: 24, autoAlpha: 0, duration: 0.6 })
+      .add(splitHeadlineIn(), "-=0.4")                       // overlap, don't queue
+      .from("[data-body]", { y: 32, autoAlpha: 0 }, "-=0.6")
+      .from("[data-media]", { yPercent: 12, autoAlpha: 0, duration: 1.2 }, "-=0.8");
+  },
+  { scope: container }
+);
+```
+
+The `-=0.x` overlaps are the craft: sequential-but-overlapping reads as one composed gesture; strictly sequential reads as a PowerPoint build.

package/skills/struq/references/seo.md

@@ -0,0 +1,219 @@
+# SEO, social images and site structure
+
+A cinematic site that nobody finds, or that shows a blank grey card when it is shared, has failed at the first impression. These are the basics every Struq build ships, wired the Next.js App Router way (Vite notes at the end). They are cheap, and most of them have to be decided in the plan, not patched after launch.
+
+## 1. Site structure (decided in the PLAN phase)
+
+- **Flat and named.** Every page is at most two levels deep: `/work`, `/work/<slug>`, `/studio`, `/contact`. Slugs are lowercase words in the site's language, never ids.
+- **One page, one job, one h1.** By default the hero display line **is** the h1: write it so it says what the page is about in words someone would search. Only when the display line is deliberately not descriptive (a poetic claim, a single word) does the h1 become a smaller line above it, with the display line as a `p` in display styling.
+- **Headings in order.** h1, then h2 per section, h3 inside. A section eyebrow is a `p`, not a heading. Visual size and heading level are separate decisions.
+- **Every important page linked from the nav or the footer** with a real `<a href>` (the `TransitionLink` from [route-transitions.md](route-transitions.md) renders one). A route reachable only through a JavaScript click handler does not exist to a crawler.
+- **A real 404** (`app/not-found.tsx`) designed as hard as the hero, with a way back.
+
+Record the page list and slugs under PLAN in STRUQ.md ([direction.md](direction.md)).
+
+## 2. Metadata
+
+Set the base once in the root layout, then per page:
+
+```tsx
+// app/layout.tsx
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  metadataBase: new URL("https://example.com"),
+  title: { default: "Name: what it is in five words", template: "%s | Name" },
+  description: "One or two plain sentences, 140 to 160 characters, written for a person, not a keyword list.",
+  // No alternates.canonical here: metadata merges down, so a root canonical of "/"
+  // would mark every page as a duplicate of the home page. Set it per page.
+  openGraph: { type: "website", siteName: "Name", locale: "en_US" },
+  twitter: { card: "summary_large_image" },
+};
+```
+
+```tsx
+// app/page.tsx: the home page sets its own canonical too
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  alternates: { canonical: "/" },
+};
+```
+
+```tsx
+// app/work/[slug]/page.tsx
+import type { Metadata } from "next";
+
+export async function generateMetadata(
+  { params }: { params: Promise<{ slug: string }> }
+): Promise<Metadata> {
+  const { slug } = await params;
+  const project = await getProject(slug);
+  return {
+    title: project.title,
+    description: project.summary,
+    alternates: { canonical: `/work/${slug}` },
+  };
+}
+```
+
+- `metadataBase` makes every relative OG and canonical URL absolute. Without it, shared links break.
+- Titles: the page's own name first, the brand after (`%s | Name`). Under about 60 characters.
+- One canonical per page, set in that page's own `metadata` or `generateMetadata`, never in the root layout. Multi-language sites add `alternates.languages`.
+- Add the theme color to `viewport` so mobile browser chrome matches the surface: `export const viewport = { themeColor: "#0A0A0B" }`.
+
+## 3. Open Graph images: one per route, designed as posters
+
+The OG image is the site's first impression in every chat app and social feed. Design it like a poster from the same system as the site: the surface color, the display face at a light weight, the wordmark, one line, generous margins. Never a screenshot of the hero, never a default grey card.
+
+Every route that gets shared gets its own image via the file convention: an `opengraph-image.tsx` next to the route's `page.tsx`.
+
+```tsx
+// app/opengraph-image.tsx (and app/work/[slug]/opengraph-image.tsx for per-project cards)
+import { ImageResponse } from "next/og";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export const alt = "Name: what it is";
+export const size = { width: 1200, height: 630 };
+export const contentType = "image/png";
+
+export default async function Image() {
+  // next/og needs the font as data: a TTF, OTF or WOFF of the display face in the repo (Fontsource WOFF works, brand.md §3).
+  const display = await readFile(join(process.cwd(), "assets/fonts/Display-Light.ttf"));
+
+  return new ImageResponse(
+    (
+      <div
+        style={{
+          width: "100%",
+          height: "100%",
+          display: "flex",
+          flexDirection: "column",
+          justifyContent: "space-between",
+          padding: 72,
+          background: "#0A0A0B",
+          color: "#EDEAE4",
+          fontFamily: "Display",
+        }}
+      >
+        <div style={{ fontSize: 28, letterSpacing: "0.12em", textTransform: "uppercase", opacity: 0.6 }}>
+          Name
+        </div>
+        <div style={{ fontSize: 96, lineHeight: 1, letterSpacing: "-0.03em", fontWeight: 300, maxWidth: 900 }}>
+          The one line the page is about.
+        </div>
+      </div>
+    ),
+    { ...size, fonts: [{ name: "Display", data: display, weight: 300, style: "normal" }] }
+  );
+}
+```
+
+- `ImageResponse` renders a flexbox subset of CSS: every element with more than one child needs `display: "flex"`. No grid, no `clamp()`.
+- It needs TTF, OTF or WOFF font data, not WOFF2. Keep a TTF of the display face in the repo for this.
+- Per-project images pull the project's title and, if it reads at card size, its cover image as an `<img>` with an absolute URL. In a dynamic segment the image receives the params as a promise, like the page does:
+
+```tsx
+// app/work/[slug]/opengraph-image.tsx
+export default async function Image({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const project = await getProject(slug);
+  // ...same ImageResponse as above, with project.title as the line
+}
+```
+- Twitter and X use the same image when `twitter.card` is `summary_large_image`; add `twitter-image.tsx` only when it should differ.
+- Check every card at real size before shipping: text over 60 characters wraps badly at 96px.
+
+## 4. Sitemap and robots
+
+```ts
+// app/sitemap.ts
+import type { MetadataRoute } from "next";
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const base = "https://example.com";
+  // A constant, not new Date(): with cacheComponents on, a request-time date breaks the prerender
+  // (setup.md §0, Known API shifts). Bump it when the content changes.
+  const LAST_UPDATED = "2026-01-15";
+  const projects = await getProjects();
+  return [
+    { url: base, lastModified: LAST_UPDATED, changeFrequency: "monthly", priority: 1 },
+    { url: `${base}/work`, lastModified: LAST_UPDATED, changeFrequency: "weekly", priority: 0.8 },
+    ...projects.map((p) => ({
+      url: `${base}/work/${p.slug}`,
+      lastModified: p.updatedAt,
+      changeFrequency: "yearly" as const,
+      priority: 0.6,
+    })),
+    { url: `${base}/contact`, lastModified: LAST_UPDATED, changeFrequency: "yearly", priority: 0.5 },
+  ];
+}
+```
+
+```ts
+// app/robots.ts
+import type { MetadataRoute } from "next";
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: { userAgent: "*", allow: "/" },
+    sitemap: "https://example.com/sitemap.xml",
+  };
+}
+```
+
+Every page in the PLAN's page list appears in the sitemap; nothing that 404s does. A staging deploy must disallow everything (`disallow: "/"`) so it never gets indexed.
+
+## 5. Structured data
+
+One JSON-LD block per page type, server-rendered:
+
+```tsx
+// in a server component
+const jsonLd = {
+  "@context": "https://schema.org",
+  "@type": "Organization", // LocalBusiness for a place, Person for a portfolio, Product for a product page
+  name: "Name",
+  url: "https://example.com",
+  logo: "https://example.com/brand/mark.png",
+  sameAs: ["https://www.instagram.com/name"],
+};
+
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, "\\u003c") }}
+/>
+```
+
+Add `BreadcrumbList` on nested pages and `FAQPage` only when the page really has a visible FAQ. Never mark up content that is not on the page.
+
+## 6. Where cinematic sites lose SEO, and the fix
+
+| Risk | Fix |
+|---|---|
+| A loader that covers the page delays the Largest Contentful Paint | The hero renders and paints underneath; the loader is an overlay, session-gated, and never blocks HTML ([loaders.md](loaders.md)). Never render the hero only after the loader finishes. |
+| SplitText turns the h1 into dozens of spans for screen readers | Use SplitText's `aria` option (the default `"auto"` keeps an accessible label on the parent); never split before fonts are ready ([typography.md](typography.md)) |
+| Content that only exists after a scroll animation, or starts at `opacity: 0` in server HTML with no fallback | Animate `from` so final state is the default; content stays readable with JavaScript off and under reduced motion ([setup.md](setup.md) §4) |
+| Text inside a WebGL canvas | Real copy lives in the DOM; 3D text is decoration with the same words in the DOM next to it ([webgl-scenes.md](webgl-scenes.md)) |
+| Heavy 3D or video on first load | Lazy islands with posters ([webgl-r3f.md](webgl-r3f.md)); the poster image is the LCP candidate, sized and preloaded |
+| Route transitions built on client-only navigation | `TransitionLink` keeps a real `href`; every route is server-rendered and works on direct load |
+| Images without dimensions | `next/image` with width and height or `fill` in a sized frame; descriptive `alt` for content images, empty `alt` for decoration |
+| Fonts swapping and shifting the layout | `next/font` with `adjustFontFallback` ([typography.md](typography.md)) |
+
+**Performance floor to check in verify:** LCP under 2.5s, CLS under 0.1, INP under 200ms on a mid-range phone profile. Run Lighthouse or PageSpeed once on the production build for LCP and CLS; lab Lighthouse reports TBT, not INP, so INP comes from field data or a manual interaction trace ([performance.md](performance.md) §8). Record the numbers under VERIFY in STRUQ.md.
+
+## 7. Vite
+
+No metadata API: set title, description, canonical and OG tags per route in the HTML or with a head manager, ship static OG PNGs per shared page, and generate `sitemap.xml` at build time (a small script over the route list, or a sitemap plugin). A client-only SPA is weak for SEO; if search matters, prerender the routes or use Next.js.
+
+## Checklist
+
+- [ ] `metadataBase`, title template and description in the root layout; a canonical on every page (home included), none in the layout
+- [ ] An `opengraph-image` per shared route, designed from the system, checked at real size
+- [ ] `sitemap.ts` covers every page; `robots.ts` points at it; staging disallows all
+- [ ] One h1 per page (the hero display line, unless it is not descriptive), headings in order, eyebrows are not headings
+- [ ] JSON-LD for the page type
+- [ ] Every route reachable by a real link and server-rendered on direct load
+- [ ] Loader and animations never hide content from the server HTML
+- [ ] LCP, CLS and INP recorded under VERIFY