@struq/skill 0.2.2 → 0.4.0

package/skills/struq/references/depth-parallax.md

@@ -1,235 +0,0 @@
-# Layered Depth & Parallax
-
-Parallax has a deserved bad reputation because the cheap version (one background image crawling at 0.5×) was strip-mined by 2014 WordPress themes. The agency version is about **relative rates**: multiple surfaces moving at *different* speeds, which is how human vision infers depth. One moving layer is a gimmick; three rates is a world. For named, ready-made showpiece recipes with ids, see [showcase.md](showcase.md).
-
-Rules of thumb before the techniques:
-- Speed deltas are small: ±10 to 20% of scroll rate. ±50% reads as broken, not deep.
-- Foreground moves *faster* than scroll, background *slower*. Match physical optics or it feels wrong without the viewer knowing why.
-- Everything scrub-tied (`ease: "none"`), transforms only.
-- Disable under `prefers-reduced-motion` (parallax is the #1 vestibular-trigger complaint).
-
----
-
-## 1. Multi-speed layers (`data-speed`)
-
-**Term:** Rate-layered section / multiplane.
-**Mechanic:** Siblings in one section carry a `data-speed` attribute; a single loop gives each a scrubbed y-drift proportional to `(speed - 1)`. Speed 1 = normal flow, 0.85 = lags (far), 1.15 = leads (near).
-
-**When:** Heroes, full-bleed image sections, any composition from [composition.md](composition.md) with overlapping layers: depth makes overlap legible.
-**Overkill when:** dense text/UI sections. Moving reading material is hostile.
-**Cost:** Trivial (transforms). Just don't exceed ~6 layers per viewport.
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-export function ParallaxSection({ children }: { children: React.ReactNode }) {
-  const container = useRef<HTMLElement>(null);
-
-  useGSAP(
-    () => {
-      gsap.utils.toArray<HTMLElement>("[data-speed]").forEach((el) => {
-        const speed = parseFloat(el.dataset.speed ?? "1");
-        gsap.to(el, {
-          y: () => (1 - speed) * 0.4 * window.innerHeight, // drift over one viewport of travel
-          ease: "none",
-          scrollTrigger: {
-            trigger: container.current,
-            start: "top bottom",     // animate across the section's entire visibility
-            end: "bottom top",
-            scrub: true,
-            invalidateOnRefresh: true,
-          },
-        });
-      });
-    },
-    { scope: container }
-  );
-
-  return <section ref={container} className="relative">{children}</section>;
-}
-
-// Usage: three rates = depth:
-// <ParallaxSection>
-//   <span data-speed="0.9"  className="...ghost numeral, far"/>
-//   <img  data-speed="1"    className="...main media, normal"/>
-//   <div  data-speed="1.12" className="...caption card overlapping the image, near"/>
-// </ParallaxSection>
-```
-
-`start: "top bottom", end: "bottom top"` makes the drift symmetric around the section's centered position. Elements are at their natural layout spot when the section is mid-viewport. That's why this doesn't break layout the way naive offset parallax does.
-
-**Cheap tell:** one `background-attachment: fixed` image (also broken on iOS), or a single layer at 0.5×. **Instead:** Three-plus siblings at 0.9 / 1.0 / 1.12, symmetric drift.
-
----
-
-## 2. Image parallax inside a mask
-
-**Term:** Window parallax / internal pan.
-**Mechanic:** Container is the "window" (`overflow-hidden`, fixed aspect); image inside is oversized via `scale(1.15)` and pans vertically as the window crosses the viewport. The frame holds still while the photo moves behind it, the signature texture of editorial agency sites.
-
-**When:** Every significant content image. This is a default treatment, not a feature.
-**Cost:** Cheap. The scale provides the pan headroom. Never load a larger asset for this. ~15% scale on a properly-sized responsive image is invisible quality-wise.
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-export function ParallaxImage({ src, alt, ratio = "4/3" }: { src: string; alt: string; ratio?: string }) {
-  const frame = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      gsap.fromTo(
-        frame.current!.querySelector("img"),
-        { yPercent: -8 },
-        {
-          yPercent: 8,
-          ease: "none",
-          scrollTrigger: { trigger: frame.current, start: "top bottom", end: "bottom top", scrub: true },
-        }
-      );
-    },
-    { scope: frame }
-  );
-
-  return (
-    <div ref={frame} className="overflow-hidden" style={{ aspectRatio: ratio }}>
-      <img src={src} alt={alt} className="h-full w-full scale-[1.18] object-cover" />
-    </div>
-  );
-}
-```
-
-Arithmetic that must hold: pan range (-8% → +8% = 16%) < scale headroom (18%). If edges ever show, scale is too low for the range. Combine freely with the masked-entrance reveal from [scroll-reveals.md](scroll-reveals.md): the entrance plays once and the pan scrubs forever; they don't conflict because the entrance animates the same `yPercent` through GSAP's tween overwrite.
-
-**Cheap tell:** flat `<img>` in a `rounded-xl shadow-lg` card. **Instead:** Still frame, breathing photo.
-
----
-
-## 3. Sticky-stacking cards
-
-**Term:** Stacking deck / sticky pile.
-**Mechanic:** Consecutive full-ish-height cards each get `position: sticky; top: 0`, so each pins while the next slides over it. CSS does 90% of the work; the agency layer is the scrub that *recedes* the covered card: scaling it down and dimming it so it visibly drops into the background instead of just being papered over.
-
-**When:** Sequential content with weight: case studies, principles, chapters. 3 to 5 cards.
-**Overkill when:** >6 cards (the gesture wears out), or content users need to compare side-by-side.
-**Cost:** Sticky is free. The recede uses `scale` + an opacity veil (cheap). Avoid scrubbed `filter: brightness()`/`blur()` on large cards; that's the expensive variant. If you want blur-recede, budget it as your one filter effect per page ([setup.md](setup.md) §5).
-
-```tsx
-"use client";
-
-import { useRef } from "react";
-import { gsap, useGSAP } from "@/lib/gsap";
-
-const SURFACES = ["bg-surface-1", "bg-surface-2", "bg-surface-1", "bg-surface-2"];
-
-export function StackingCards({ items }: { items: { kicker: string; title: string; body: string }[] }) {
-  const container = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const mm = gsap.matchMedia();
-      // The recede is decoration: reduced motion keeps the plain CSS sticky stack.
-      mm.add("(prefers-reduced-motion: no-preference)", () => {
-        gsap.utils.toArray<HTMLElement>("[data-card]").forEach((card, i, all) => {
-          if (i === all.length - 1) return; // last card never gets covered
-          gsap.to(card, {
-            scale: 0.92,
-            yPercent: -4,
-            ease: "none",
-            scrollTrigger: {
-              trigger: all[i + 1],          // driven by the NEXT card's approach
-              start: "top bottom",
-              end: "top top",
-              scrub: true,
-            },
-          });
-          gsap.fromTo(card.querySelector("[data-veil]"), { autoAlpha: 0 }, {
-            autoAlpha: 0.5,
-            ease: "none",
-            scrollTrigger: { trigger: all[i + 1], start: "top bottom", end: "top top", scrub: true },
-          });
-        });
-      });
-    },
-    { scope: container }
-  );
-
-  return (
-    <div ref={container}>
-      {items.map((item, i) => (
-        // One screen tall from md up (svh, so mobile browser chrome never resizes it);
-        // content height below md, per mobile-composition.md §1.
-        <section key={item.title} data-card
-                 className={`sticky top-0 flex flex-col justify-between gap-16 overflow-hidden
-                             px-8 py-12 md:min-h-[100svh] ${SURFACES[i % SURFACES.length]}`}>
-          <span className="eyebrow text-eyebrow text-ink-muted">{item.kicker}</span>
-          <div className="max-w-3xl">
-            <h3 className="font-display text-h2">{item.title}</h3>
-            <p className="text-lead mt-6 max-w-[48ch] text-ink-muted">{item.body}</p>
-          </div>
-          <div data-veil className="pointer-events-none absolute inset-0 bg-surface-0 opacity-0" />
-        </section>
-      ))}
-    </div>
-  );
-}
-```
-
-Load-bearing details:
-- **Trigger is the *next* card**: each recede is driven by its coverer's approach, so timing is exact regardless of card heights.
-- The `data-veil` div dims with surface color (not black) so the receding card recedes *into the page's own depth*, and it's opacity, which is cheap where `brightness()` isn't.
-- Alternating `bg-surface-1/2` makes each new edge visible the moment it enters.
-- `transform-origin` defaults to center, which is correct here: the card shrinks toward the page's vanishing point.
-
-**Cheap tell:** bare `sticky top-0` cards papering over each other with no recede; covered cards look frozen/glitched rather than layered. **Instead:** Covered cards scale to 0.92 and dim under a surface veil, scrubbed to the coverer's approach.
-
----
-
-## 4. Scrub-drift marquee (ghost type)
-
-**Term:** Scroll-rate marquee.
-**Mechanic:** The off-canvas ghost type from [composition.md](composition.md) §4, driven sideways by scroll position (not a CSS loop). Direction can alternate per instance; speed is the parallax delta again, applied on x.
-
-```tsx
-useGSAP(() => {
-  const mm = gsap.matchMedia();
-  mm.add("(prefers-reduced-motion: no-preference)", () => {
-    gsap.to("[data-marquee]", {
-      xPercent: -18,
-      ease: "none",
-      scrollTrigger: { trigger: container.current, start: "top bottom", end: "bottom top", scrub: true },
-    });
-  });
-}, { scope: container });
-
-// <div aria-hidden className="overflow-clip">
-//   <p data-marquee className="font-display text-ghost whitespace-nowrap font-light text-ink/[0.05]">
-//     Studio Nord · Studio Nord · Studio Nord ·
-//   </p>
-// </div>
-```
-
-The type is muted solid: `text-ghost` in the display face at its lightest loaded weight, `text-ink/[0.05]` (0.04 to 0.06), the phrase repeated three times ([typography.md](typography.md) §5, Ghost marquee). Never outlined (`-webkit-text-stroke` with a transparent fill): that is a dated template move.
-
-Scroll-tied drift beats an autonomous CSS `@keyframes` marquee for section texture: it's still when the user is still (calmer, and free under reduced motion if you gate it). Use the looping CSS marquee only for genuinely continuous content like logo walls.
-
----
-
-## Depth recipe (composing the file)
-
-For a hero or any showpiece section, stack the techniques as planes:
-
-| Plane | Element | Treatment |
-|---|---|---|
-| -2 | ghost numeral / marquee type | `data-speed 0.9` or x-drift, `text-ghost text-ink/[0.05]`, muted solid |
-| -1 | full-bleed media | window parallax (§2) |
-| 0 | headline, body | normal flow, text never parallaxes |
-| +1 | caption card, badge overlapping media | `data-speed 1.1`, `z-20` |
-
-Text at plane 0 always. The moment copy drifts at a different rate than the reading eye expects, the whole effect flips from depth to seasickness.

package/skills/struq/references/direction.md

@@ -1,188 +0,0 @@
-# Direction: plan everything before the first component
-
-Award-tier sites are decided before they are built. The logo, the one idea the site is about, the two typefaces, the palette, the icon family, the arc and the showpieces are made once, together, so every later choice can be checked against them. A build that discovers its direction while coding ends up with a Tailwind default and a nice hero.
-
-This file is the orchestrator for **Build**, **Redesign** and the planning half of **Directed**. It runs seven phases, numbered 0 to 6, with one gate between planning and building. It writes one contract file, `STRUQ.md` in the project root, and that file is the only plan artifact: there is no second plan block, no separate brief document, no parallel folder for a normal build.
-
-## The phases
-
-| # | Phase | Output (a section of STRUQ.md) | Procedure | Skip when |
-|---|---|---|---|---|
-| 0 | **Intake** | header (Mode, Stack), MATERIALS | this file §1, with [brief-router.md](brief-router.md) §1 and §1b | never |
-| 1 | **Brand** | BRAND | [brand.md](brand.md) | a brand exists (extract it, §2) |
-| 2 | **Concept** | CONCEPT | this file §3; the tension from [brief-router.md](brief-router.md) §1 | never |
-| 3 | **System** | SYSTEM | this file §4 (sole owner of type, palette, icons, imagery, motion) | never |
-| 4 | **Site plan** | PLAN | [brief-router.md](brief-router.md) §2 | never |
-| Gate | **Veto** | one message: summary, materials request, "Veto anything?" | this file §5 | the user said "just build it", or the run is non-interactive |
-| 5 | **Build** | the site | [../SKILL.md](../SKILL.md) workflow steps 2 to 7 | |
-| 6 | **Verify** | VERIFY | [../SKILL.md](../SKILL.md) workflow step 8 | never |
-
-Phases 0 to 4 together are workflow step 1, **Direction**, in [../SKILL.md](../SKILL.md). Directed mode (`/struq direct`) runs phases 0 to 3 here, then hands over to [../cinematic/README.md](../cinematic/README.md), whose lean outputs are appended to the same STRUQ.md as a DIRECTION section.
-
-**Scale the ceremony to the job.** A one-page site for an existing brand runs phases 0, 2, 3 and 4 in a few minutes. A new company with no name runs all of them. Never ask a question the brief already answers; never skip a phase because it feels obvious. Write the obvious answer down, because the later phases read it.
-
-## 1. Intake
-
-**One stop, not two.** With a usable brief, do not block here. Run the extraction in [brief-router.md](brief-router.md) §1 silently, record what exists under MATERIALS, record what is missing (and how each gap is handled) under MATERIALS and ASSUMPTIONS, and carry on to the gate. The request for materials goes inside the single gate message (§5). Block early only when the wizard trigger conditions in [brief-router.md](brief-router.md) §1b hold: no usable brief, a request to be guided, or no answer to "who buys" and "what are they afraid of".
-
-What MATERIALS tracks:
-
-- Name and logo (files, not descriptions)
-- Brand colors and fonts, if any are fixed
-- Real copy, or at least the facts: what it is, who it is for, what it costs, where it is
-- Photos, product shots, video, 3D models
-- Real numbers (clients, years, results) and real quotes, with permission
-- An existing site (switch to Redesign: [triage.md](triage.md))
-- One or two sites whose feel they envy
-
-**Never invent proof.** Testimonials, client logos, stats and awards that do not exist are left out, not faked.
-
-**Never write in a real person's or brand's voice.** On a site named after a real person or a real business:
-
-- No first person attributed to them ("I make those decisions...") and no quotes in their name. Write in the studio's or the site's third-person voice.
-- No biography, training, process or sourcing stated as fact ("trained as a production thrower", "eats at the restaurant before drawing", "clay dug in Alentejo") unless the brief says it.
-- No catalogue facts: invented works, sizes, glazes, materials, prices, editions, sold-out states, stockists or client names.
-
-When the layout needs that copy to exist, draft it as a labelled placeholder and list every drafted claim under ASSUMPTIONS ("Studio paragraph: drafted, replace with Ana's words"; "Work index: 8 entries drafted as layout copy, no prices, no client names"). A portfolio with no work list gets its entries drafted the same way, titled as layout copy, never as the record. The gate message names the drafts so the client can replace them.
-
-**No real imagery yet.** Plan for it instead of papering over it:
-
-- Prefer type-led showpieces (`manifesto-fill`, `scrub-headline`, `ghost-marquee`) over media-led ones; a horizontal gallery of placeholders is worse than a static grid ([showcase.md](showcase.md) Choosing).
-- Every missing image becomes a shot-list line (subject, grade, ratio) under PLAN `Assets to produce`, so it can be shot, sourced or generated later ([imagery.md](imagery.md) §4).
-- In the build, a missing image renders as a placeholder frame per [imagery.md](imagery.md) §4b: a graded tonal frame at the declared ratio, with the shot-list caption set in the eyebrow style. Never grey boxes, never random stock.
-
-## 2. Brand
-
-If there is no name or no logo, run [brand.md](brand.md). It produces a name shortlist with one recommendation, a wordmark and a mark as SVG, a favicon set, and one voice line; the OG image is built later, once routes exist ([seo.md](seo.md) §3). If a brand exists, extract it instead: logo file, the exact colors, the fonts, how they write. Existing brand assets always beat the preset; the preset still supplies the token structure they pour into.
-
-| What exists | Run |
-|---|---|
-| Nothing | [brand.md](brand.md) in full |
-| A name, no logo, no brand | [brand.md](brand.md) §1 and §3 to §5: skip naming |
-| **A named brand (colours, a font, a voice) but no logo file** | Skip [brand.md](brand.md) §1 and §2: never rename, never reposition. Draw a **provisional** wordmark from the brand's own face ([brand.md](brand.md) §3), write it to the same paths (`brand/logo.svg`, `brand/mark.svg`) so the real logo drops in, and record it under ASSUMPTIONS: "Logo: provisional wordmark from <face>, replace with the brand file" |
-| A full brand with logo files | Extract only; no [brand.md](brand.md) |
-
-**Person-named sites skip naming.** Portfolios, studios named after a person, practices and clinics use the person's name. If the name is unknown, write a placeholder, record it under ASSUMPTIONS, skip [brand.md](brand.md) §2 and go straight to the wordmark (§3 there).
-
-## 3. Concept
-
-The concept is what makes the site feel authored instead of assembled. Write three lines:
-
-- **Idea:** one sentence the whole site is about, specific to this client. Not "modern and clean"; "every page is a quiet room with one object in it" or "the site moves like a slow pan across a construction drawing".
-- **Tension:** what the visitor needs to feel (convince) and what the site must never signal (never). From [brief-router.md](brief-router.md) §1 question 2.
-- **Motif:** the one recurring visual device that carries the idea through the page. A line that draws through every section, a frame that every image sits in, a numeral system, a crop direction, a mark that morphs. One motif, used everywhere, beats five effects used once.
-
-Every later decision gets checked against these three lines. If a showpiece or effect does not serve the idea or the motif, it goes.
-
-## 4. System
-
-This section is the only place SYSTEM is decided. Other files point here.
-
-**Read budget.** During planning, read only the Decide-here section at the top of [typography.md](typography.md) and of [iconography.md](iconography.md), the token contract and the one chosen preset in [vibe-presets.md](vibe-presets.md), and the grade table in [imagery.md](imagery.md) §1. Two more reads are planning reads, not build reads, when they apply: the preset's **hero entrance** recipe ([page-entrances.md](page-entrances.md) for `match-cut-hero` and `clip-line-hero`, on any site), and, when the brief asks for 3D, the **WebGL plan** ([webgl-r3f.md](webgl-r3f.md) §1 and [webgl-scenes.md](webgl-scenes.md) §5: poster, gate, touch fallback, and the "No model file yet" ladder in §4). Read the full files during the build (workflow step 2), not now.
-
-Decide in this order:
-
-0. **Niche.** Buyer, genre and preset from [brief-router.md](brief-router.md) §2 step 1, plus the one borrowed field (TYPE or PALETTE) if any.
-1. **Type.** Exactly two faces: display (run light, 300 to 400, unless the concept is a declared heavy genre) and text. Take a pairing id from the brand's temperament per [typography.md](typography.md) Decide here: Signature (S1 to S7) first, Extended (E1 to E6) only when no Signature temperament fits. "Unsure" is not a temperament and never a reason to take S1. Name the faces, the role weights, the source and the license, the **one signature move** ([typography.md](typography.md) §5) and the **hero entrance** (the preset's named entrance, or a declared different one).
-2. **Palette.** Surface ladder (four steps), ink tiers (ink, muted, faint), one accent and the line color, written as tokens. Existing brand colors pour into this structure. Add the radius. [vibe-presets.md](vibe-presets.md)
-
-   **Brand colours onto the ladder.** A brand's colour names are not token names: brand "ink" usually means the brand's dark, while `--color-ink` is the *text* colour. Map by role, never by name:
-
-   | Brand colour | On a light preset | On a dark preset |
-   |---|---|---|
-   | The brand's dark | `ink` (text), and the inverted surfaces | `surface-0` (the page); `ink` becomes an off-white |
-   | The brand's light | `surface-0` (the page) | `ink` (text) |
-   | The brand's accent | `accent` | `accent` |
-
-   Derive the rest of the ladder from the mapped pair (surfaces step toward the ink, muted and faint tiers mixed from ink). Check the accent against `surface-0`: 4.5:1 or better and it may be text (links); 3:1 or better and it may set large type and UI; below that it is fills and rules only. Write which under SYSTEM.
-3. **Icons.** One icon family for the whole site, chosen by the order in [iconography.md](iconography.md) §2: the brand's own set, else Struq Icons. Name the package, the stroke and how its accent maps to the palette.
-4. **Imagery.** One grade, the declared ratio set (2 to 3), grain yes or no. [imagery.md](imagery.md)
-5. **Scroll and motion.** Lenis lerp (or native, with the reason). Motion is the baseline MOTION line in [../SKILL.md](../SKILL.md) by default: write "baseline". Any other duration band or ease pair, including the alternative pairs in [feel-layer.md](feel-layer.md) §3, is an allowed deviation only when it is written here with its reason.
-
-## 5. The gate
-
-Write `STRUQ.md` (template below), then send one message with: the name, the idea line, the two typefaces and pairing id, the signature move and hero entrance, the palette as hex, the icon family, the arc as one line, the showpiece ids, the open assumptions, and the materials request. End it with exactly this:
-
-> **Veto anything? If you have a logo, photos or real numbers, send them now.**
-
-Apply edits and new materials to the file; do not re-interview. This is the only stop between the brief and the build (the wizard in [brief-router.md](brief-router.md) §1b is the one exception, and it runs before this gate, not instead of it).
-
-If the user said "just build it", or the run is non-interactive, write the file, state the assumptions at the top and continue.
-
-## 6. During the build
-
-`STRUQ.md` is the contract. Before each workflow step, re-read the section it depends on. If a decision has to change during the build (a font does not have the weight, an asset is missing), change it **in the file first**, with one line under LOG saying why, then change the code. A site that drifts from its own plan is how a directed build turns back into a template.
-
-After verify, append the score and the open issues under VERIFY.
-
-## STRUQ.md template
-
-```markdown
-# STRUQ.md: <project name>
-
-Mode: build | redesign | directed
-Stack: <Next.js | Vite> <installed major> · React <major> · Tailwind <major> · GSAP <x.y> · Lenis <major> · three <0.x> (if used), read from package.json (setup.md §0); Vite translations per stack-targets.md
-
-## MATERIALS
-Have: <logo, copy, photos, numbers, quotes>
-Missing: <list, with how each gap is handled>
-References: <sites the client envies, and what to take from each>
-
-## BRAND
-Name: <name> (shortlist and rationale in brand/NAMING.md, if generated)
-Logo: brand/logo.svg (wordmark), brand/mark.svg (mark), app/icon.svg, app/apple-icon.png
-OG: app/opengraph-image.tsx, plus one per shared route (seo.md §3)
-Voice: <one line, e.g. "plain, certain, a little dry; short sentences; no exclamation marks">
-
-## CONCEPT
-Idea: <one sentence>
-Tension: convince <...> / never signal <...>
-Motif: <the one recurring device>
-
-## SYSTEM
-Niche: <buyer + business model> · genre <Portfolio | Studio | Product launch | Campaign>
-  · preset <Soft Modern | Warm Editorial | Dark Cinematic | Luxury Minimal | Brutalist (genre appendix, declared genre only)>
-  [+ borrowed TYPE or PALETTE from <preset>]
-Display: <face> <weight> (<source>, <license>) · pairing <S1 to S7 | E1 to E6>
-Text: <face> <weights> (<source>, <license>)
-Signature move: <weight-in | soft-scrub | type-mask-media | fit-width-wordmark | cropped display>
-Hero entrance: <the preset's named entrance, or a declared different one>
-Palette: <light | dark> · --surface-0 #... --surface-1 #... --surface-2 #... --surface-3 #...
-  --ink #... --ink-muted #... --ink-faint #... (non-text only) --accent #... --line <...>
-Radius: <n>px
-Icons: <family, package, stroke> (default: Struq Icons, @struq/icons, strokeWidth 1.5, accent = --color-accent)
-Imagery: <grade>, ratios <2 to 3>, grain <opacity | none>
-Scroll: Lenis lerp <the preset's stated value | native, because ...> on gsap.ticker
-Motion: baseline | deviations: <each one, with its reason>
-
-## PLAN
-Pages: <list with slugs>
-Arc (home): <numbered rows: section [beat] note, spacing role>; proof form; grid-breaks
-Reveals: headlines <...> · blocks <...> · images <...> · svg <moment | none>
-Showpieces: <showpiece ids, arc row, mobile fallback> (1 to 2, breathers on both sides; a showpiece is its own density class, page-architecture.md §3)
-System recipes: <system ids: line-rise-hero, route-curtain, fullscreen-menu ...>
-Transitions: <route-curtain variant | none>, loader <yes | no>
-WebGL: <none | the moment, its poster, its fallback>
-Copy budget: <per section>
-Assets to produce: <shot list: subject, grade, ratio, source>
-
-## PRESERVED (redesign only)
-- <what will not be touched: brand color, copy, component primitives>
-
-## ASSUMPTIONS
-- <every decision made without the user's input>
-- <every drafted claim: copy in a real person's or brand's name, catalogue entries, a provisional logo, a 3D stand-in>
-
-## LOG
-- <date> <decision changed and why>
-- <date> <API>: installed <pkg major> differs from the skill's code; adapted to <change> (setup.md §0)
-
-## VERIFY
-Server: next start on :<port>, port owner confirmed
-Viewports: 390, 768, 1440, 1920
-Score: <n>/100 · LCP <s> (element) CLS <n> INP <ms | field data pending> · first-load JS <n> kB gzip
-Motion: pins engaged slow and fast <ok>, descender test <ok>, frame trace <ok>
-Open: <issues>
-```
-
-Directed mode appends `## DIRECTION` after PLAN, per [../cinematic/README.md](../cinematic/README.md).

package/skills/struq/references/feel-layer.md

@@ -1,107 +0,0 @@
-# The Feel Layer: Values You'd Actually Ship
-
-Techniques are copyable; feel is in the numbers. Two builds can run the same code and one feels like Locomotive while the other feels like a tutorial. The delta is lerp values, scrub smoothing, ease pairing, and duration scale. This file is the tuning reference for everything else in the skill.
-
----
-
-## 1. Lenis: the scroll's personality
-
-Lenis interpolates real scroll position toward the target each frame. `lerp` is the fraction covered per frame: **lower = floatier, heavier; higher = tighter, more direct.** This single number sets the personality of the entire site, because every scrub-tied effect inherits it.
-
-| lerp | Feel | Ship it for |
-|---|---|---|
-| 0.05-0.07 | syrup-heavy, luxurious, slightly defiant | luxury/fashion one-pagers, short narrative scrolls. Risky: long pages feel slow to operate |
-| **0.09-0.11** | **weighted but obedient (the default)** | **portfolios, studios, most marketing** |
-| 0.12-0.16 | light glide, barely-smoothed | content-heavy marketing, editorial with lots of reading |
-| (no Lenis) | native | dashboards, docs, apps: smoothing a tool insults the user |
-
-Decision rule: the more *reading* per viewport, the higher the lerp; the more *imagery*, the more floor you can afford. Alternative: `duration: 1.2` + `easing` (Lenis's time-based mode) instead of `lerp`. Same idea, easier to reason about as "a scroll impulse takes ~1.2s to settle." Pick one mode, don't set both.
-
-Always:
-- `autoRaf: false` + GSAP ticker + `lagSmoothing(0)` ([setup.md](setup.md)): two clocks = micro-jitter on every scrub.
-- `anchors: true` so in-page links still work.
-- Under `prefers-reduced-motion`, keep Lenis mounted and gate the motion it drives (pins, parallax, scrub showpieces) in `matchMedia` branches, as [setup.md](setup.md) §2 and §4 wire it. Returning early from the provider makes native scroll look like a broken setup.
-
----
-
-## 2. Scrub: direct drive vs. smoothed
-
-`scrub: true` = value locks to scroll position exactly. `scrub: <n>` = value *chases* scroll position over ~n seconds: scroll stops, animation eases into place.
-
-| Value | Feel | Use for |
-|---|---|---|
-| `true` | mechanical 1:1, instant stop | things that must feel *attached*: hero departure, progress bars, curtains the user "drags," marquee drift |
-| `0.5-1` | weighted, settles after the hand stops | **default for transforms**: parallax layers, pinned sequences, horizontal scroll |
-| `1.5-2.5` | cinematic float, noticeable lag | large background media, ambient/atmospheric layers |
-| `>3` | detached, reads as broken | nothing |
-
-Two interacting smoothings: Lenis already smooths the scroll *input*; scrub smooths the *output* on top. Lenis at 0.1 + `scrub: 1` is the classic pairing. If you stack Lenis 0.06 + scrub 2.5, the page feels drunk. Rule: **lower Lenis lerp → lower scrub numbers.**
-
-Mixed rates in one section are the pro move: hero title at `scrub: true` (attached), background media at `scrub: 1.5` (floating behind it). The differential *is* the depth.
-
----
-
-## 3. Ease pairing: the system, not the menu
-
-Full curve table lives in [transitions.md](transitions.md). The shipping system:
-
-**The default system is the baseline MOTION line in [../SKILL.md](../SKILL.md), and these are the same numbers:**
-
-| Role | Ease | GSAP name | CSS |
-|---|---|---|---|
-| Entrances | expo-out | `expo.out` | `cubic-bezier(0.16, 1, 0.3, 1)` |
-| Exits | power2-in (cubic-in) | `power2.in` | `cubic-bezier(0.32, 0, 0.67, 0)` |
-| Position swaps (A to B moves) | quart-in-out | `power3.inOut` | `cubic-bezier(0.76, 0, 0.24, 1)` |
-| Curtains and panels | quint-in-out | `power4.inOut` | `cubic-bezier(0.83, 0, 0.17, 1)` |
-
-GSAP's names are offset by one from the classic curve names: `power1` = quad, `power2` = cubic, `power3` = quart, `power4` = quint.
-
-**Allowed deviations, recorded in STRUQ.md SYSTEM with a reason.** A preset or concept may swap the pair; it is never a silent per-component choice:
-- *Kinetic*: `power4.out` (quint-out) entrances + `back.out(1.4)` accents (crisp, springy)
-- *Editorial-calm*: `power3.out` (quart-out) entrances + `power2.inOut` moves (nothing shouts)
-
-Then three rules:
-1. Entrances out-ease, exits in-ease (`power2.in`), A→B moves in-out. Never the reverse.
-2. Scrubbed tweens: `ease: "none"` for tracking values; segment eases (power2) only *inside* scrubbed timelines for phase swaps.
-3. `back`/`elastic` are accent spices: ≤1 element type per page (toast, badge, magnetic return). Two springy things = toy.
-
----
-
-## 4. Duration & stagger scale
-
-Durations scale with **visual mass** (size × contrast of the change), not importance. A 90vw image takes 1.2s; a 14px tag takes 0.25s; same duration on both makes one feel sluggish and the other twitchy.
-
-| Tier | Duration | Examples |
-|---|---|---|
-| Micro | 0.2 to 0.3s | press, toggles, underline, tag slide |
-| Standard UI | 0.3 to 0.6s | dropdowns, card hovers, accordion, text swap |
-| Reveal | 0.6 to 1.0s | section entrances, split lines, masked images |
-| Hero and cinematic | 1.0 to 1.6s | hero entrance, page curtain + content rise, full-bleed media |
-| Over 1.6s | n/a | only multi-part timelines; a single tween this long = user waiting |
-
-These bands are the baseline's, number for number. A different band is a deviation and goes into STRUQ.md SYSTEM with its reason.
-
-Exits run about 60% of their entrance's duration (leaving is decisive; see [transitions.md](transitions.md) §4).
-
-Stagger:
-
-| each | Feel | Use |
-|---|---|---|
-| 0.02-0.04 | texture: perceived as one rich motion | chars, long lists (12+) |
-| **0.06-0.1** | **readable rhythm (the default)** | cards, lines, nav items |
-| 0.12-0.18 | deliberate, editorial | 2-4 big blocks |
-| >0.2 | queueing: last item enters embarrassingly late | avoid; for n items keep `each × n ≤ ~0.8s` |
-
-`stagger: { each: 0.08, from: "center" | "edges" | "random" }`: vary the origin by composition (centered logo walls from `"center"`, grids from `"start"`, particle-ish textures `"random"`).
-
----
-
-## 5. The 60-second feel audit
-
-Scroll the build top to bottom once, then:
-
-1. **Stop scrolling abruptly mid-section.** Do scrubbed layers settle softly (good) or freeze instantly (raise scrub) or keep drifting awkwardly (lower it)?
-2. **Watch one entrance.** Can you see it *end*? If you can't perceive the deceleration tail, the ease or duration is too timid. This is the #1 "feels like a template" cause even when the technique is right.
-3. **Count layers in a hover.** One moving layer = cheap, two or three = choreography.
-4. **Flick-scroll the whole page.** Does the site stay composed (Lenis + scrub doing their job) or strobe with triggered animations firing everywhere? If strobing: too many `once` reveals triggered too late (move starts earlier, e.g. `top 85%`).
-5. **Is anything moving that the user didn't cause?** Autonomous looping motion (except one deliberate marquee/ambient element) drains the premium feel. Agency motion is overwhelmingly *response*, not *activity*.