@struq/skill 0.2.2 → 0.4.0

package/skills/struq/scripts/tokens.mjs

@@ -0,0 +1,222 @@
+// The token block and the font requests, derived exactly as Struq's block lab derives them (lib/lab/tokens.ts,
+// lib/canon/surface-ladder.ts, lib/canon/palette-roles.ts, lib/canon/font-sources.ts), so a block in a client
+// project wears the same colours and faces it was judged in. Pure functions, no I/O: canon.mjs writes, tests compare.
+
+/* ------------------------------------------------------------------ colour */
+const linearise = (byte) => {
+  const v = byte / 255;
+  return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+};
+const encode = (linear) => {
+  const v = linear <= 0.0031308 ? linear * 12.92 : 1.055 * Math.pow(linear, 1 / 2.4) - 0.055;
+  return Math.round(Math.min(255, Math.max(0, v * 255)));
+};
+
+function oklabToLinear({ L, a, b }) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return {
+    r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  };
+}
+function linearToOklab({ r, g, b }) {
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+/** A canon colour (hex or oklch) as linear RGB, or null (background-exposure.ts parseColor). */
+export function parseLinear(value) {
+  const v = String(value).trim();
+  if (v.startsWith("#")) {
+    const body = v.slice(1);
+    const parts =
+      body.length === 3
+        ? body.split("").map((c) => parseInt(c + c, 16))
+        : body.length === 6
+          ? [0, 2, 4].map((i) => parseInt(body.slice(i, i + 2), 16))
+          : null;
+    if (!parts || parts.some(Number.isNaN)) return null;
+    return { r: linearise(parts[0]), g: linearise(parts[1]), b: linearise(parts[2]) };
+  }
+  if (!v.toLowerCase().startsWith("oklch")) return null;
+  const m = /oklch\(\s*([\d.]+)%?\s+([\d.]+)\s+([\d.]+)/i.exec(v);
+  if (!m) return null;
+  let L = parseFloat(m[1]);
+  if (v.includes("%")) L /= 100;
+  const C = parseFloat(m[2]);
+  const h = (parseFloat(m[3]) * Math.PI) / 180;
+  return oklabToLinear({ L, a: C * Math.cos(h), b: C * Math.sin(h) });
+}
+
+export function toHex(c) {
+  const clamp = (n) => Math.min(1, Math.max(0, n));
+  return `#${[c.r, c.g, c.b].map((x) => encode(clamp(x)).toString(16).padStart(2, "0")).join("")}`;
+}
+
+/** sRGB bytes, oklch clamped into gamut first (facets.ts parseColor). */
+function parseBytes(input) {
+  const value = String(input).trim().toLowerCase();
+  const hex = value.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/);
+  if (hex) {
+    const d = hex[1].length === 3 ? hex[1].split("").map((x) => x + x).join("") : hex[1];
+    return { r: parseInt(d.slice(0, 2), 16), g: parseInt(d.slice(2, 4), 16), b: parseInt(d.slice(4, 6), 16) };
+  }
+  const ok = value.match(/^oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)/);
+  if (!ok) return null;
+  const L = ok[1].endsWith("%") ? Number(ok[1].slice(0, -1)) / 100 : Number(ok[1]);
+  const h = (Number(ok[3]) * Math.PI) / 180;
+  const lin = oklabToLinear({ L, a: Number(ok[2]) * Math.cos(h), b: Number(ok[2]) * Math.sin(h) });
+  const enc = (c) => {
+    const x = Math.min(1, Math.max(0, c));
+    const g = x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055;
+    return Math.round(Math.min(1, Math.max(0, g)) * 255);
+  };
+  return { r: enc(lin.r), g: enc(lin.g), b: enc(lin.b) };
+}
+const luminance = ({ r, g, b }) => 0.2126 * linearise(r) + 0.7152 * linearise(g) + 0.0722 * linearise(b);
+
+/** WCAG contrast ratio between two canon colours. */
+export function contrast(a, b) {
+  const ca = parseBytes(a);
+  const cb = parseBytes(b);
+  if (!ca || !cb) return 0;
+  const [hi, lo] = [luminance(ca), luminance(cb)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Lightness for light or dark: OKLCH L, else the HSL lightness of a hex (lib/lab/tokens.ts). */
+export function lightness(v) {
+  const m = String(v).match(/oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)/i);
+  if (m) return m[1].endsWith("%") ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
+  const h = String(v).match(/^#([0-9a-f]{6})$/i);
+  if (!h) return 0.5;
+  const [r, g, b] = [0, 2, 4].map((i) => parseInt(h[1].slice(i, i + 2), 16) / 255);
+  return (Math.max(r, g, b) + Math.min(r, g, b)) / 2;
+}
+
+/* ------------------------------------------------------------------- roles */
+const NEAR_WHITE = "oklch(0.98 0.005 85)";
+const NEAR_BLACK = "oklch(0.16 0.01 60)";
+
+function inkFor(ground, own) {
+  const ranked = [...own, NEAR_WHITE, NEAR_BLACK]
+    .map((ink, order) => ({ ink, order, ratio: contrast(ground, ink) }))
+    .sort((a, b) => b.ratio - a.ratio || a.order - b.order);
+  const ownPassing = ranked.find((e) => e.order < own.length && e.ratio >= 4.5);
+  return (ownPassing ?? ranked[0]).ink;
+}
+
+function deepenedField(accent, light) {
+  const base = parseLinear(accent);
+  if (!base) return { field: accent, ink: inkFor(accent, light) };
+  for (let step = 0; step <= 12; step += 1) {
+    const f = Math.pow(0.9, step);
+    const field = step === 0 ? accent : toHex({ r: base.r * f, g: base.g * f, b: base.b * f });
+    const ink = inkFor(field, light);
+    if (contrast(field, ink) >= 4.5) return { field, ink };
+  }
+  return { field: accent, ink: inkFor(accent, light) };
+}
+
+/** The field and inverse roles: authored on the palette, else derived from its own colours (palette-roles.ts). */
+export function paletteRoles(palette) {
+  if (palette.roles) return palette.roles;
+  const { background, text, accent } = palette.colors;
+  const ink = inkFor(accent, [background, text]);
+  const { field, ink: fieldInk } =
+    contrast(accent, ink) >= 4.5 ? { field: accent, ink } : deepenedField(accent, [background, text]);
+  return { field, fieldInk, inverse: text, inverseInk: background };
+}
+
+/** A deeper surface step held on the ground's own hue (surface-ladder.ts). */
+export function surfaceStep(surface, ink, pct) {
+  const s = parseLinear(surface);
+  const k = parseLinear(ink);
+  if (!s || !k) return `color-mix(in oklab, ${surface}, ${ink} ${pct}%)`;
+  const a = linearToOklab(s);
+  const b = linearToOklab(k);
+  const t = pct / 100;
+  const mixed = { L: a.L + (b.L - a.L) * t, a: a.a + (b.a - a.a) * t, b: a.b + (b.b - a.b) * t };
+  let C = Math.hypot(mixed.a, mixed.b);
+  const H = Math.hypot(a.a, a.b) < 0.002 ? Math.atan2(mixed.b, mixed.a) : Math.atan2(a.b, a.a);
+  const inGamut = (c) => [c.r, c.g, c.b].every((v) => v >= -1e-4 && v <= 1 + 1e-4);
+  while (C > 0 && !inGamut(oklabToLinear({ L: mixed.L, a: C * Math.cos(H), b: C * Math.sin(H) }))) C -= 0.001;
+  const deg = ((H * 180) / Math.PI + 360) % 360;
+  return `oklch(${mixed.L.toFixed(4)} ${Math.max(0, C).toFixed(4)} ${deg.toFixed(2)})`;
+}
+
+/* ------------------------------------------------------------------- faces */
+export const headFamily = (stack) => (String(stack ?? "").split(",")[0] ?? "").trim().replace(/^['"]|['"]$/g, "");
+
+/** The token block, as [name, value] pairs in the lab's order (lib/lab/tokens.ts paletteTokens). */
+export function paletteTokens(palette, pairing) {
+  const c = palette.colors;
+  const roles = paletteRoles(palette);
+  const dark = lightness(c.background) < 0.5;
+  const accentInk = contrast(c.accent, c.background) >= contrast(c.accent, c.text) ? c.background : c.text;
+  const tokens = [
+    ["--surface-0", c.background],
+    ["--surface-1", c.surface],
+    ["--surface-2", surfaceStep(c.surface, c.text, dark ? 9 : 7)],
+    ["--surface-3", surfaceStep(c.surface, c.text, dark ? 18 : 16)],
+    ["--ink", c.text],
+    ["--ink-muted", `color-mix(in oklab, var(--ink) ${dark ? 70 : 66}%, var(--surface-0))`],
+    ["--accent", c.accent],
+    ["--accent-ink", accentInk],
+    ["--accent-2", c.accentAlt ?? c.surface],
+    ["--line", "color-mix(in oklab, var(--ink) 13%, transparent)"],
+    ["--on-photo", dark ? c.text : c.background],
+    ["--photo-ground", dark ? c.background : roles.inverse],
+    ["--inverse", roles.inverse],
+    ["--on-inverse", roles.inverseInk],
+    ["--field", roles.field],
+    ["--on-field", roles.fieldInk],
+    ["color-scheme", dark ? "dark" : "light"],
+    ["--display-weight", String(pairing.displayScale?.weight ?? 300)],
+    ["--face-display", `"${headFamily(pairing.display)}"`],
+    ["--face-body", `"${headFamily(pairing.body)}"`],
+  ];
+  if (pairing.accentItalic) tokens.push(["--face-accent", `"${headFamily(pairing.accentItalic)}"`]);
+  return tokens;
+}
+
+/**
+ * Stylesheet URLs for a pairing's faces (lib/lab/tokens.ts fontHrefs): per Google family the face's real weight range
+ * and the bare family as a fallback, because css2 refuses a request that names a weight the family lacks.
+ */
+export function fontHrefs(pairing, { fontWeights = {}, fontProviders = {} } = {}) {
+  const hrefs = [];
+  const faces = [
+    { stack: pairing.display, italic: false },
+    { stack: pairing.body, italic: false },
+    ...(pairing.accentItalic ? [{ stack: pairing.accentItalic, italic: true }] : []),
+  ];
+  for (const { stack, italic } of faces) {
+    const family = headFamily(stack);
+    const provider = fontProviders[family];
+    if (!provider || provider === "system") continue;
+    if (provider === "fontshare") {
+      hrefs.push(`https://api.fontshare.com/v2/css?f[]=${family.toLowerCase().replace(/\s+/g, "-")}@300,400,500,600,700&display=swap`);
+      continue;
+    }
+    const name = family.replace(/\s+/g, "+");
+    const range = fontWeights[family];
+    const axis = range && range[0] < range[1] ? `${range[0]}..${range[1]}` : null;
+    hrefs.push(
+      italic
+        ? `https://fonts.googleapis.com/css2?family=${name}:${axis ? `ital,wght@1,${axis}` : "ital@1"}&display=swap`
+        : `https://fonts.googleapis.com/css2?family=${name}${axis ? `:wght@${axis}` : ""}&display=swap`,
+    );
+    hrefs.push(`https://fonts.googleapis.com/css2?family=${name}${italic ? ":ital@1" : ""}&display=swap`);
+  }
+  return [...new Set(hrefs)];
+}

package/skills/struq/references/anti-patterns.md

@@ -1,265 +0,0 @@
-# Anti-Pattern Gallery: the Cheap Reflex vs. the Agency Version
-
-Each pair below names the **tell**, the specific detail that exposes the default. Use this file as a pre-ship checklist: scan for tells, replace with the paired fix. Cross-references point to the full technique.
-
----
-
-## 1. Elevation
-
-**Reflex:**
-```tsx
-<div className="rounded-xl bg-white p-6 shadow-lg border border-gray-200">
-```
-**The tell:** `shadow-md`/`shadow-lg` doing elevation on a light card, gray-200 border, on a `bg-gray-50` page. Component-library depth model.
-
-**Agency:**
-```tsx
-// Dark: elevation = lighter surface. Light: elevation = hairline + tone.
-<div className="rounded-sm bg-surface-2 p-8 border border-line">
-```
-Surface ladder steps (`surface-0 → 1 → 2`) signal depth tonally. Real shadows are reserved for true floaters, and then: `shadow-[0_24px_80px_-12px_rgb(0_0_0/0.4)]`. ([baseline-prompt.md](baseline-prompt.md))
-
----
-
-## 2. The feature section
-
-**Reflex:**
-```tsx
-<section className="py-16">
-  <h2 className="text-center text-3xl font-bold">Why Choose Us</h2>
-  <p className="mt-2 text-center text-gray-500">Everything you need to succeed</p>
-  <div className="mt-12 grid grid-cols-3 gap-8">
-    {features.map(f => (
-      <div className="rounded-xl border p-6 shadow-sm text-center">
-        <Icon className="mx-auto h-8 w-8 text-blue-600" />
-        <h3 className="mt-4 font-semibold">{f.title}</h3>
-        <p className="mt-2 text-sm text-gray-500">{f.body}</p>
-      </div>
-    ))}
-  </div>
-</section>
-```
-**The tell:** centered h2 + subhead + 3 identical icon-cards. The single most recognizable AI/template section on the internet.
-
-**Agency:** kill the cards; let type and rhythm carry it:
-```tsx
-<section className="content-grid py-40 gap-y-0">
-  <p className="eyebrow text-eyebrow text-ink-muted">Capabilities</p>
-  <div className="mt-16 divide-y divide-line">
-    {features.map((f) => (
-      <div key={f.title} className="group grid grid-cols-12 items-baseline gap-4 py-10">
-        <h3 className="type-h3 text-h3 col-span-6">{f.title}</h3>
-        <p className="text-body col-span-5 col-start-8 max-w-[44ch] text-ink-muted">{f.body}</p>
-      </div>
-    ))}
-  </div>
-</section>
-```
-Editorial rows, left-aligned, divided by hairlines, asymmetric columns. Hierarchy comes from type scale and the eyebrow, not from a number on every row (see §16). ([composition.md](composition.md))
-
----
-
-## 3. Scroll reveal
-
-**Reflex:**
-```tsx
-<motion.div initial={{ opacity: 0 }} whileInView={{ opacity: 1 }} transition={{ duration: 0.3 }}>
-```
-**The tell:** opacity-only, no transform, no stagger, 300ms default ease. Content blinks into existence, all siblings simultaneously.
-
-**Agency:**
-```tsx
-gsap.from("[data-reveal]", {
-  y: 48, autoAlpha: 0, duration: 0.9, ease: "expo.out",
-  stagger: 0.08,
-  scrollTrigger: { trigger: container.current, start: "top 78%", once: true },
-});
-```
-Transform + opacity, expo-out tail, 80ms rhythm between siblings, inside the reduced-motion branch. ([scroll-reveals.md](scroll-reveals.md))
-
-**The silent failure:** a `[data-reveal]` element that also carries `transition-opacity` (a sibling-dim hover) or a `translate-y-*` offset. The first leaves it stuck at `opacity: 0` with the tween at progress 1; the second is erased because GSAP sets `translate: none`. Reveal the wrapper, transition and offset the child ([pitfalls.md](pitfalls.md) §3).
-
----
-
-## 4. Headline entrance
-
-**Reflex:** the whole `<h1>` fades up as one block, or worse, a per-character typewriter with uniform linear timing.
-**The tell:** text treated as a rectangle (or a teletype), not as lines.
-
-**Agency:**
-```tsx
-SplitText.create(el, {
-  type: "lines", mask: "lines", autoSplit: true,
-  onSplit: (self) => gsap.from(self.lines, {
-    yPercent: 110, duration: 1.1, ease: "expo.out", stagger: 0.09,
-    scrollTrigger: { trigger: el, start: "top 80%", once: true },
-  }),
-});
-```
-Lines rising from individual overflow masks. ([scroll-reveals.md](scroll-reveals.md) §3; the typographic side of SplitText lives in [typography.md](typography.md))
-
----
-
-## 5. Hero
-
-**Reflex:** centered h1, gray subhead, two buttons (one blue, one outline), then a product screenshot in a browser-chrome mockup, possibly tilted with a purple glow.
-**The tell:** the symmetric "SaaS hero stack," gradient text on the keyword, floating screenshot.
-
-**Agency (structure, not just styling):** left-aligned or compositionally split; h1 as `font-display text-display` (the pairing's display clamp, [typography.md](typography.md) §2.4) doing the visual work; media bleeding off-grid or punching into the next section; meta-information (location, availability, scroll cue) placed at the hero's edges like a poster; scrub-tied departure ([pinning-scrub.md](pinning-scrub.md) §3). A hero is a *composition*, not a stack. For ready-made hero showpieces, see [showcase.md](showcase.md).
-
----
-
-## 6. Parallax
-
-**Reflex:** `background-attachment: fixed` banner, or one layer drifting at 0.5× scroll.
-**The tell:** single-layer movement (and iOS breakage). Depth needs *relative* rates.
-
-**Agency:** three siblings at `data-speed` 0.9 / 1.0 / 1.12 within one section, scrubbed, symmetric around natural position, plus photos panning inside `overflow-hidden` frames (`scale(1.18)`, `yPercent` from -8 to 8). ([depth-parallax.md](depth-parallax.md))
-
----
-
-## 7. Sticky stacking
-
-**Reflex:** bare `sticky top-0` cards papering over each other.
-**The tell:** the covered card sits frozen at full scale/brightness. It looks glitched, not layered.
-
-**Agency:** each covered card recedes (`scale: 0.92`, surface-colored veil to 50%), scrubbed to the *next* card's approach. ([depth-parallax.md](depth-parallax.md) §3)
-
----
-
-## 7b. Pinned / horizontal-scroll handoff
-
-**Reflex:** reach for `anticipatePin: 1` (and/or `scrub: true`) to "smooth" the moment a pinned or horizontal section engages.
-**The tell:** a jerk/jump right at the vertical-to-horizontal (or pin-on) handoff, worst on a fast scroll-in. It snaps then corrects instead of easing in. With smooth scroll (Lenis), `anticipatePin` predicts from a *smoothed* velocity, overshoots, and pins a frame early; `scrub: true` then passes that spike straight through 1:1.
-
-**Agency:** **no `anticipatePin`** with smooth scroll + `scrub: 1` (pairs with Lenis lerp ~0.09 so the track settles softly). If only the *first* scroll-in snaps, the cause is stale pin positions, so add the delayed initial `lenis.resize()` + `ScrollTrigger.refresh()` from [setup.md](setup.md) §2. Tuning `scrub` is not the fix; removing `anticipatePin` is. ([pinning-scrub.md](pinning-scrub.md) §2; every other pin cause, symptom first: [pitfalls.md](pitfalls.md) §2)
-
----
-
-## 8. Section transitions
-
-**Reflex:** every section a watertight `py-16` box; boundaries are just background-color changes at a hard line.
-**The tell:** uniform vertical rhythm + zero cross-boundary elements. The page is a stack of slides.
-
-**Agency:** padding varies by section role (8/16/24rem); at least one element trespasses each major seam (negative margin + z); one act-break uses a scrubbed curtain sweep. ([composition.md](composition.md), [transitions.md](transitions.md) §2)
-
----
-
-## 9. Page navigation
-
-**Reflex:** hard cut between routes, or a 200ms full-page opacity crossfade.
-**The tell:** navigation is an event, not a moment. No surface moves, content just swaps.
-
-**Agency:** quint-in-out curtain sweep (`scaleY` with flipping `transform-origin`) + incoming content rising with expo-out after a 0.25s overlap. Total ≤ 900ms. ([transitions.md](transitions.md) §1; for full-screen route transitions on multi-page sites see [route-transitions.md](route-transitions.md))
-
----
-
-## 10. Buttons & hovers
-
-**Reflex:**
-```tsx
-<button className="rounded-lg bg-blue-600 px-4 py-2 text-white transition hover:bg-blue-700 hover:scale-105">
-```
-**The tell:** color-darken + scale-up + `transition-all duration-300`, identical on every interactive element.
-
-**Agency:** one primary CTA with a *scene*: fill swelling from the bottom edge, label rolling through a mask or trailing magnetically, elastic return. Secondary links get the origin-flipping underline. Cards get three-clock hovers + sibling dimming. Press = `scale 0.97` at 150ms. ([micro-interactions.md](micro-interactions.md))
-
----
-
-## 11. Color & accent
-
-**Reflex:** `bg-gradient-to-r from-blue-600 to-purple-600` (buttons, hero glow, `bg-clip-text` headline), accents in 4 hues, pure white page with gray-500 text.
-**The tell:** the blue-purple gradient is the watermark of generated design; multiple accents mean no hierarchy decision was made.
-
-**Agency:** temperature-shifted neutrals doing 95% of the work; **one** accent appearing at most once per viewport; headline color = ink, with hierarchy from scale. If a gradient exists at all it is a subtle same-hue tonal ramp on a surface, never on text. ([vibe-presets.md](vibe-presets.md))
-
----
-
-## 12. Type scale
-
-**Reflex:** h1 `text-4xl`, h2 `text-3xl`, h3 `text-2xl`, h4 `text-xl`: five steps between 20 and 36px, all `font-bold`, default tracking.
-**The tell:** compressed mid-range hierarchy. Nothing leads, everything is "kind of big."
-
-**Agency:** two extremes, set through the role tokens so nothing is improvised: `font-display text-display` for the hero (the token carries the pairing's clamp, tracking and leading), `font-display text-h2` per section, `type-h3 text-h3` for items, `text-body` at 1 to 1.0625rem, and `eyebrow text-eyebrow text-ink-muted` (uppercase 0.75rem, tracked 0.12 to 0.18em per face) as wayfinding between. No `tracking-tight`: tracking belongs to the face and the role ([typography.md](typography.md) §3.1). **Hero/display runs light (300 to 400)**. Large + light is the agency signal; heavy display (600+) is a deliberate genre choice only, never the reflex. **Floor:** body ≥1rem, muted ≥0.875rem, nothing below 12px. **Contrast:** body ≥4.5:1 (WCAG AA), large/≥24px ≥3:1; `ink-faint` is never text. ([baseline-prompt.md](baseline-prompt.md); the Signature pairings, roles and fluid scale are in [typography.md](typography.md))
-
----
-
-## 13. Iconography & ornament
-
-**Reflex:** 🚀✨💡 as feature icons; the AI-cliché trio (`Sparkles`, `Rocket`, `Zap`/lightning, in any set) standing in for "magic / launch / fast"; reflexive Lucide for everything; icons at 5 sizes/strokes in brand-blue circles with light-blue backgrounds; an animated icon looping forever in a dashboard, or a 500ms+ animation lagging a click; a complex decorative icon turned to mud at 16px.
-**The tell:** icon-as-filler. `Sparkles`/`Rocket`/`Zap` are the visual signature of generated UI; the icon circle chip is the card-grid's sidekick; constant-loop animation reads as distraction, not delight.
-
-**Agency:** icons only where they inform (UI affordances, scannability, button anchors, never decoration); **one coherent family chosen for the brand** (its own set, else Struq Icons, else Phosphor light; never reflexive Lucide, never two families), one size, `strokeWidth={1.5}`, ink-colored; system icons small, decorative/animated big. Animated icons: ≤500ms on click, 1.5 to 3s on hover, never loop in standard UI, natural physics, reduced-motion falls back to static. Decoration jobs otherwise go to hairline rules, ghost type, a single oversized numeral as an accent (not a per-row counter, see §16), real photography/render. Often the strongest move is **no icon at all**. (Full doctrine: [iconography.md](iconography.md); drawn or morphing line art belongs to [svg-motion.md](svg-motion.md))
-
----
-
-## 14. The exit problem
-
-**Reflex:** choreographed entrances, then `display: none` exits: accordions snapping shut, modals vanishing, filtered items teleporting.
-**The tell:** asymmetry of care. The system only performs in one direction.
-
-**Agency:** every exit designed at ~60% of entrance duration with `power2.in` / `easeIn`, reverse stagger for groups, `AnimatePresence` for unmounts. ([transitions.md](transitions.md) §4)
-
----
-
-## 15. Loading & lorem
-
-**Reflex:** lorem ipsum, "John Doe, CEO at Acme", `https://via.placeholder.com/600x400`, spinner gif while content pops in.
-**The tell:** placeholder *anything*. It signals nobody made content decisions, and layout was never tested against reality.
-
-**Agency:** real (or convincingly written) copy with opinions; image areas with explicit aspect ratios; entrances double as load choreography (content reveals when ready, no spinner, no CLS).
-
----
-
-## 16. Numbered everything
-
-**Reflex:** `01 / 02 / 03 / 04` stamped on every section header, every feature, every list row (often oversized in a corner) as the page's wayfinding system.
-**The tell:** uniform sequencing is reflexive, not editorial. No art director numbers *everything*; it is the same impulse as `py-16` on every section, applied to labels. It signals "I needed a decoration and reached for the nearest one."
-
-**Agency:** wayfinding through variety: tracked uppercase eyebrows, hairline rules, scale jumps, surface changes. A numeral earns its place only as a **single deliberate accent** (one oversized `03` against a manifesto line), never as a per-row counter. If you can delete the numbers and lose no meaning, they were filler.
-
-**The boundary:** ordinal numbering *inside one genuinely stepped component* (the phase kickers of a pinned sequence, see [pinning-scrub.md](pinning-scrub.md) §1, or a numbered process that really is ordered) is legitimate content, not this tell. The tell is *page-wide* stamping: numerals as the default decoration on every section, feature, and row.
-
----
-
-## 17. Monospace as flavor
-
-**Reflex:**
-```tsx
-<p className="font-mono text-xs uppercase tracking-widest">// System online</p>
-<span className="font-mono text-sm">[ 2024 ]</span>
-```
-**The tell:** monospace on eyebrows, labels, stats, badges, timestamps, or body to look "technical / engineered / terminal." It is the aesthetic of a code editor, not a designed page, and it has become a default reach for "techy," which makes it read as generated.
-
-**Agency:** a real text face carries all UI and copy; "precision" comes from tracking, `tabular-nums` on figures, and tight type, not from a typewriter font. **Mono is reserved for literal code** (snippets, inline `code`, terminal output on a dev-tool site where it is genuinely the subject). Anywhere else, it is a tell. The same logic kills the scramble/decode "terminal" loader ([loaders.md](loaders.md)).
-
----
-
-## 18. Per-viewport pixel-fixing
-
-**Reflex:**
-```tsx
-<h2 className="text-2xl md:text-4xl lg:text-5xl xl:text-6xl">
-<section className="px-6 py-12 md:px-12 md:py-20 lg:px-24 lg:py-32">
-// fixed px widths everywhere; a fresh override added each time a new screen breaks
-```
-**The tell:** every size hand-tuned per breakpoint, layout authored in px, and it *still* drifts at 1440 and 2560, so each new viewport means another round of element-by-element fixes. The hours sink is real and it never converges.
-
-**Agency:** one fluid root-rem knob (an a11y-safe `clamp` that keeps a rem term so zoom works), everything authored in rem, breakpoints reserved for **layout changes** (column count, stack/row) not resizing; display type carries its own `clamp()` on top. The whole UI scales proportionally at every width with zero per-element overrides. ([scaling.md](scaling.md))
-
----
-
-## The 30-second tell scan
-
-Before shipping, run these grep-level checks:
-- `shadow-md|shadow-lg` on cards → §1 · `from-blue|to-purple|bg-clip-text` → §11
-- `py-16` ≥3 times → §8 · `grid-cols-3` of identical children → §2
-- `hover:scale-105|transition-all` → §10 · `duration-300` as the only duration → [feel-layer.md](feel-layer.md)
-- `opacity` tweens with no transform partner → §3 · emoji in JSX → §13
-- `anticipatePin` anywhere while Lenis/smooth scroll is mounted → §7b (jagged pin handoff)
-- `Sparkles|Rocket|Zap` icon imports (any set) / icon in a colored chip / looping animated icon → §13 · `font-mono` outside a code block → §17
-- `grep -P '0\d\s*[/.\-\u2014\u2013]'` (catches `01 /`, `01.`, `01 -` and the dash variants) / `0{i + 1}` numbering every section or row → §16
-- `font-bold` on the hero/`h1` / largest size = `text-4xl` → §12 · faint text on body copy / contrast below AA → §12
-- size ladders like `text-2xl md:text-4xl lg:text-6xl`, `px-`/`py-` tuned per breakpoint, fixed-`px` layout widths, or no fluid root font-size → §18
-- `text-4xl` as the largest size on the page → §12 · "Lorem|Acme|John Doe" → §15
-- `tracking-tight`, `text-ink-faint`, or `text-xs uppercase tracking-[` on headings and eyebrows (role tokens bypassed) → §12 · `Inter|Roboto|Open_Sans|Poppins|Montserrat|Lato|Space_Grotesk|Geist` in `next/font` imports → [typography.md](typography.md) §3.4

package/skills/struq/references/baseline-prompt.md

@@ -1,118 +0,0 @@
-# The Minimal Baseline: rationale + standalone paste block
-
-**The canonical baseline block lives in [SKILL.md](../SKILL.md).** This file does two jobs. It explains **why each rule earns its place** (the rationale below), and it carries the one **standalone copy-paste block** for agents that do not load Struq as a skill: the canonical block plus two role-priming lines.
-
-<!-- GENERATED FROM SKILL.md: the block below is a copy of the canonical baseline block, with two role-priming lines above its title and one blank line between them. Do not edit it here. Edit SKILL.md, then re-copy the block and keep the two role-priming lines. -->
-
-## The paste block (generated, for any LLM, any stack)
-
-Paste this at the top of any project prompt to lift the output into the top tier. Include the rationale section only when the agent has room.
-
-```
-Act as a senior design engineer at an award-winning studio (Awwwards SOTD
-caliber). Apply every rule below; they override your defaults.
-
-STRUQ BASELINE: NON-NEGOTIABLES
-
-TYPE: Signature first: one pairing id from typography.md §3.1 (S1 to S7;
-Extended E1 to E6 only when no Signature temperament fits), two faces max.
-Never Inter, Roboto, Open Sans, Poppins, Montserrat or Lato; never Space
-Grotesk or Geist as a reflex. Scale 1.333 with skipped steps (body 1, lead
-1.25, h3 1.78, h2 3.16, display 7 to 8). Hero h1 = text-display,
-clamp(2.875rem, 1.2rem + 6.86vw, 8rem), leading 0.92 to 1.0; S4 and S5 set
-larger, S7 smaller (typography.md §3.1). Display runs LIGHT (300 to 400);
-heavy display only as a declared genre (the Brutalist appendix), never a
-reflex. Tracking per face, never one tracking-tight on every size: sans
-display about -0.025 to -0.03em, serif display about -0.01 to -0.025em, h2
-about half that. Body 1rem to 1.0625rem at 400, leading 1.6+, 55 to 75ch;
-emphasis 500, never 700. Hierarchy from scale contrast, not medium sizes.
-ROLES: every string takes a role token, never text-xs, text-lg or text-5xl:
-font-display text-display, font-display text-h2, type-h3 text-h3,
-text-lead, text-body, text-small, eyebrow text-eyebrow, font-ui text-ui,
-stat text-stat, and font-display text-statement for the one Orient line
-or manifesto. Eyebrows: uppercase 0.75rem (the 12px floor), tracked 0.12
-to 0.18em per face, ink-muted, one per section, never ink-faint.
-FLOOR: body at least 1rem, muted at least 0.875rem, nothing under 12px.
-CONTRAST: body at least 4.5:1, large text at least 3:1. ink-faint is never
-text: hairlines and disabled states only.
-SIGNATURE: every STRUQ.md declares one typographic signature move
-(typography.md §5: weight-in, soft-scrub, type-mask-media,
-fit-width-wordmark, a cropped display). The masked line rise is a
-technique, not the default hero. Mono only for literal code. Headings get
-text-wrap: balance; body gets text-wrap: pretty.
-
-SPACING: Base-8 rhythm with deliberate asymmetry. Section padding varies by
-role: hero 12 to 20rem, dense content 6 to 8rem, breathers 16 to 24rem. NEVER
-uniform py-16 on every section. Whitespace is a material: at least one section
-should feel "too empty" by SaaS standards.
-
-SCALING: One fluid root-rem knob, not per-breakpoint size ladders:
-html { font-size: clamp(1rem, 0.92rem + 0.2vw, 1.125rem); }
-16px at 390, about 17.6px at 1440, frozen at 18px from about 1640. Every
-clamp() keeps a rem term in its middle so zoom works; a vw-only middle is a
-bug. Author everything in rem; px only for 1px hairlines. Breakpoints change
-LAYOUT (columns, stack or row), never size. Display roles carry their own
-clamp() on top.
-
-SURFACE: Elevation is a tonal step, not a drop shadow. Dark mode: each layer
-steps LIGHTER (#0A0A0B, #111113, #19191C, #232328). Light mode: pick one
-direction and keep it (panels a shade deeper than a toned page, or white lifted
-off a toned page). Hairline borders about 8 to 12% off the surface; in light
-mode a border is the ink at low alpha (rgb(<ink> / 0.08 to 0.14)), never a
-flat gray hex. Shadows only for true floating elements, then large, soft and faint
-(0 24px 80px -12px rgb(0 0 0 / 0.4)). Never shadow-md or shadow-lg.
-
-COLOR: One accent, used sparingly (links, the key CTA, one highlight per
-viewport). Neutrals are temperature-shifted (warm cream and off-black, or cool
-charcoal), never pure #FFF and #000 with gray-500 text. A second accent is a
-declared genre choice with its own token and the same budget. No blue to
-purple gradients, no gradient text, no glassmorphism cards.
-
-MOTION: Lenis smooth scroll (lerp 0.09 to 0.11) on one gsap.ticker clock,
-unless the genre calls for native scroll. Every entrance animates opacity AND
-transform (y 24 to 80px, or a clip or overflow mask). Opacity-only fades are
-forbidden. Stagger siblings 0.06 to 0.1s. Durations: micro 0.2 to 0.3s,
-standard UI 0.3 to 0.6s, reveals 0.6 to 1.0s, hero and cinematic 1.0 to 1.6s;
-exits run about 60% of their entrance. Eases: entrances expo-out
-cubic-bezier(0.16, 1, 0.3, 1) (expo.out); exits power2.in; position swaps
-quart-in-out cubic-bezier(0.76, 0, 0.24, 1) (power3.inOut); curtains and
-panels quint-in-out cubic-bezier(0.83, 0, 0.17, 1) (power4.inOut). Never
-default ease-in-out everywhere.
-Scroll-tied effects scrub; they do not fire time-based tweens at a threshold.
-prefers-reduced-motion: gate transforms, keep opacity.
-
-COMPOSITION: Break the grid at least twice per page: an image bleeding off
-the viewport, an element overlapping two sections, oversized type running off
-canvas, a sticky element. No three identical icon cards in a row. Vary section
-layout: after a 50/50 split comes full-bleed or an asymmetric 1/3 and 2/3.
-Icons: ONE coherent family chosen for the brand, one stroke and size,
-ink-colored. Never emoji, never the AI-cliche icons (Sparkles, Rocket, Zap),
-never icons in colored chips. Animated icons run under 500ms on click and
-never loop in standard UI.
-
-DETAILS THAT SELL IT: Real running copy. Tracked uppercase eyebrows as
-wayfinding, not 01/02/03 stamped on every section (one deliberate oversized
-numeral is fine). The footer is designed as hard as the hero. Custom
-::selection color. Visible, designed focus-visible states. Every route change
-is a designed transition, not a hard cut.
-```
-
-The block is the floor, not the ceiling. For the full recipe stack (two-face type system, the Lenis + GSAP single clock, showpieces, route transitions, WebGL) start from [direction.md](direction.md), which turns a brief into one contract file, `STRUQ.md`, that cites the other reference files.
-
-## Why each rule matters
-
-**Spacing asymmetry.** Uniform `py-16` is the single most reliable template tell. Real art direction treats vertical rhythm as pacing: a hero breathes, a feature block is dense, a manifesto line sits in 20rem of air. Varying section padding by role is free and reads instantly as "someone decided this." The "too empty" instruction exists because LLMs systematically under-use whitespace; what feels wasteful in code feels expensive in the browser.
-
-**Type scale contrast.** Templates use five sizes between 16 and 36px, so nothing leads. Agencies compress hierarchy into two extremes: enormous display type (it is the visual, not decoration around the visual) and small, quiet everything else. Negative tracking matters because text faces are spaced for 16px, and at 96px+ the gaps look broken; how much depends on the face (a geometric sans takes about -0.03em, a hairline serif about -0.01em), which is why tracking lives in the pairing row and not in one `tracking-tight`. The tracked-uppercase eyebrow replaces the "medium subhead" that flattens hierarchy. Role tokens (`text-display`, `text-h2`, `eyebrow text-eyebrow`) exist so no component improvises a size, and the one signature move exists so two Struq sites never open the same way. The deeper type system (Signature pairings, roles, fluid scale, SplitText typography) lives in [typography.md](typography.md).
-
-**Tonal elevation.** Drop shadows on light cards are the Bootstrap-era elevation model; design-led products (Linear, Vercel, Arc) moved to tonal ladders, where closer surfaces are lighter (dark mode) or distinguished by hairline borders and a subtle tone step (light mode). The light-mode direction is a preset decision: editorial/luxury pages are the lightest layer with panels stepping deeper; brutalist pages are toned with white panels lifting off them. One step per layer keeps depth legible either way. When you do shadow a floating element, the large/soft/low-opacity recipe reads as ambient light, while `shadow-lg` reads as a 2015 component library.
-
-**One accent.** Restraint is the strongest single luxury signal. Multiple accents (or a gradient) means no decision was made. Temperature-shifted neutrals are why agency sites feel "warm" or "cinematic" while AI output feels like a wireframe: pure white + gray-500 is the absence of a palette, not a palette. The second-accent escape hatch exists because playful/consumer genres legitimately run two voices, but it is a *declared token with the same budget*, mirroring how heavy display weight is allowed only as a genre choice, never a reflex.
-
-**Transform + mask in every entrance.** An opacity-only fade has no physicality: nothing arrives from anywhere. Adding y-travel or a mask (the element slides out from behind a clipped edge) gives motion a direction and a surface to interact with, which is what reads as "crafted." Stagger matters because simultaneous arrival is visual noise; 0.06 to 0.1s offsets create reading order. Ease asymmetry (fast-out entrances, accelerating exits) mirrors how physical objects behave; symmetric ease-in-out everywhere is the uncanny valley of motion.
-
-**Scrub over trigger.** Effects that progress with scroll position feel connected to the user's hand; effects that fire once at a threshold feel like a slideshow. This one distinction separates most award sites from most marketing sites.
-
-**Grid-breaking.** A layout where every element respects the container communicates "theme." Bleed, overlap, and stickiness communicate "art direction" because they require coordinating elements across section boundaries, which is exactly what templates cannot do. Twice per page is the floor; it should look intentional, not chaotic.
-
-**Details.** Real copy forces real layout decisions (lorem hides widow/orphan and width problems). Tracked eyebrow labels give long pages an editorial spine. Note what is *removed* here: stamping `01/02/03` on every section/feature/row is one of the most reliable AI tells. It is reflexive wayfinding that no editor would apply uniformly. One deliberate oversized numeral can be a strong accent; sequencing the whole page is filler. (Ordinal numbering *inside* one genuinely stepped component, such as a pinned phase sequence or a numbered process, is legitimate; page-wide stamping is the tell.) The same logic bans two other reflexes: **monospace as flavor** (it is the look of a code editor, not a designed page, and belongs only around literal code) and the **cliché icon set** (`Sparkles`/`Rocket`/`Zap` and their emoji forms 🚀✨💡 are the visual signature of generated UI). The footer is where everyone quits, so finishing it signals the whole build is finished. Selection color and focus states are tiny, but they are the difference between "surface-level styling" and "someone touched every state."