@struq/skill 0.3.0 → 0.4.1

package/skills/struq/references/iconography.md

@@ -1,255 +1,53 @@
-# Iconography: one icon family + craft doctrine
+# Icons
 
-## Decide here
+Struq Icons is the default: `npm i @struq/icons` (MIT), the Iconify set `struq` for non-React stacks, browsable at
+[struq.nl/iconen](https://struq.nl/iconen). A two-tone set on one 24 grid, the base tone for the shape and the accent
+on the part that carries the meaning, each icon with its own hover motion.
 
-Planning reads only this section ([direction.md](direction.md) §4); the rest is for the build.
+## Whether an icon earns its place
 
-- **Family, in this order, stop at the first that fits:** (1) the brand's own drawn set; (2) **Struq Icons**, the default (`npm i @struq/icons`, MIT, 182 icons: 118 two-tone with a hover motion, 14 status, 50 glyphs; browse at [struq.nl/iconen](https://struq.nl/iconen)); (3) **Phosphor, weight `light`** (`@phosphor-icons/react`, `thin` for luxury) when the set lacks what the site needs and drawing it is not worth it, or the concept wants a softer, rounder line; (4) **Iconoir or Tabler** at stroke 1.25 when the concept wants a sharper, technical line.
-- **One icon family per site, never mixed.** Never two, never Lucide by reflex. If the chosen family lacks an icon, draw it to that family's rules or move the whole site down the list (§2).
-- **Struq Icons on a Struq site:** `strokeWidth={1.5}` next to light display type (`1.25` for luxury); the accent mapped to the site's own `--color-accent` (§2), not the set's default flame; `states.css` on, so icons rest in one tone and the accent shows where you act.
-- **Size and color:** one size per context (`size={20}` inline, `size={24}` nav, or a `size-5` / `size-6` class so the icon rides the root-rem knob), ink-colored; color only for state and semantics.
-- **Budget:** functional icons only (nav, close, chevrons, form states, CTA anchors). No 3-up feature-card icons, no Sparkles, Rocket or Zap, no emoji, no colored chips.
-- **Motion:** the set's own hover motion (200ms, hover and focus only, never on load, never looping, off under reduced motion) is inside the budget. Other animated icons under 500ms on click, never looping in standard UI, static under reduced motion.
-- **Record in STRUQ.md SYSTEM:** `Icons: Struq Icons, @struq/icons, strokeWidth 1.5, accent = --color-accent, states.css on`.
+Functional only: navigation, close, chevrons, an arrow on a text link, form states. Never a row of feature-card icons,
+never an icon in a coloured chip, never sparkles, rocket, lightning, bulb, wand or emoji. Most studio sections need
+none: the blocks carry their links as type.
 
----
-
-
-Two separate decisions, never collapse them:
-
-1. **Whether an icon earns its place**: the Struq taste gate. Most marketing
-   sections need *fewer* icons than the reflex wants; icon-as-filler is an AI tell.
-2. **How the icon behaves once it's in**: the craft doctrine below (family, register,
-   color, state, animation timing, accessibility).
-
-The gate (§1) governs *where*; the doctrine (§2 to §8) governs *how*. A perfectly-crafted
-icon in the wrong place is still wrong.
-
----
-
-## 1. The gate: does it earn its place?
-
-Keep the existing bans hard:
-
-- **Never** as 3-up feature-card filler (centered icon + h3 + two gray lines), the single
-  most recognizable generated section ([anti-patterns.md](anti-patterns.md) §2, §13).
-- **Never** Sparkles / Rocket / Zap / lightning, or emoji (🚀✨💡). They are the visual signature
-  of generated UI.
-- **Never** in a colored circle/chip background.
-- **Never** five sizes / five strokes scattered across a page.
-
-Icons **earn their place** when they do real work:
-
-- **Functional affordances**: nav, search, close, chevrons, form-field states, toggles.
-- **Scannability** in menus and dashboards: a per-row icon lets the eye decode the list
-  faster than text alone (humans parse a glyph in ~1/10s).
-- **Button visual-anchors**: an icon on a CTA gives a fast hint of the action.
-- **Paragraph / feature separators**: between blocks of a "wall of text," an icon marks a
-  visual point of separation. It must *reinforce* the message, never *replace* it.
-
-When in doubt, **no icon**. Hairline rules, ghost type, a single oversized numeral as an
-accent, or real imagery often carry decoration better in a marketing context.
-
----
-
-## 2. Source: one coherent family per project, chosen in this order
-
-The family is a SYSTEM decision, recorded in STRUQ.md ([direction.md](direction.md) §4), not
-something picked per component. Resolve it top to bottom and stop at the first that fits:
-
-| # | Family | When | Install | Weight to match light display type |
-|---|---|---|---|---|
-| 1 | **The brand's own icons** | The client already has a drawn set | their files, inlined as components | as drawn |
-| 2 | **Struq Icons** | The default for every Struq build: a two-tone set on one 24 grid (a base tone for the shape, an accent on the part that carries the meaning), each icon with its own hover motion and a draw-in variant | `npm i @struq/icons`; sprite, plain SVG and Iconify JSON (prefix `struq`) for non-React stacks | `strokeWidth={1.5}` (the set's default 2 is Lucide weight; `1.25` for luxury) |
-| 3 | **Phosphor** | A softer, rounder line, or a site that needs icons the Struq set does not have | `npm i @phosphor-icons/react`, or Iconify `ph:` | `weight="light"` (or `"thin"` for luxury) |
-| 4 | **Iconoir** or **Tabler** | A sharper, more technical or architectural line | `npm i iconoir-react` / `@tabler/icons-react`, or Iconify `iconoir:` / `tabler:` | Tabler `stroke={1.25}`; Iconoir `strokeWidth={1.25}` |
-
-### Struq Icons: the wiring
-
-Import the stylesheets once, at the root, before the site's own stylesheet; then import icons by name. Every icon is a named PascalCase export (`Search`, `ArrowRight`, `External`, `ChevronDown`, `Close`); the barrel tree-shakes. Check a name against the installed `dist/index.d.ts` or [struq.nl/iconen](https://struq.nl/iconen) before using it: the set names icons by meaning, so the up-right arrow is `External`, not `ArrowUpRight`.
+## Wiring (React)
 
 ```tsx
-// app/layout.tsx (Next) or src/main.tsx (Vite): once, before globals.css
+// app/layout.tsx, once, before globals.css
 import "@struq/icons/tokens.css";
 import "@struq/icons/icons.css";
-import "@struq/icons/states.css"; // optional: one tone at rest, the accent on hover, focus and current
+import "@struq/icons/states.css"; // one tone at rest, the accent on hover, focus and current
 ```
 
 ```css
-/* globals.css: the set's accent follows the site's palette, not its default flame.
-   On body, so it wins over tokens.css's :root and .dark rules by inheritance. */
+/* globals.css: the set's accent follows the palette, not its default. On body, so it wins by inheritance. */
 body {
   --icon-base: currentColor;
-  --icon-accent: var(--color-accent);
-  --icon-accent-live: var(--color-accent);
+  --icon-accent: var(--accent);
+  --icon-accent-live: var(--accent);
 }
 ```
 
 ```tsx
 import { ArrowRight, Search } from "@struq/icons";
 
-<a href="/work" className="font-ui text-ui inline-flex items-center gap-2">
-  Selected work <ArrowRight size={20} strokeWidth={1.5} />
-</a>
-
-<button type="button" className="grid size-12 place-items-center">
-  <Search size={24} strokeWidth={1.5} label="Search" /> {/* the only content: give it a label */}
-</button>
-```
-
-- **Props:** `size` (16, 20, 24, 32 or 48 px; a `size-5` class overrides it in rem), `strokeWidth`, `label` (names it for screen readers; without one it is `aria-hidden` decoration), `animate` (`"hover"` default, `"draw"`, `"none"`), `color` and `accentColor` (any CSS colour, set per icon; they beat the variables). Other SVG props pass through.
-- **Server components.** The icons use no hooks, so they render in server components. Only the draw-in entry is a client component.
-- **Draw-in** for one empty state, first run or hero moment, never a list: `import { StruqIconDraw } from "@struq/icons/draw"`, `<StruqIconDraw icon={Inbox} size={48} delay={0.2} />`. It needs `motion` (already in the stack), draws once, never loops, and shows the finished icon on the server, without JS and under reduced motion.
-- **Name clashes.** `Link`, `Image`, `File` and `Text` collide with `next/link`, `next/image` and DOM globals; import the `LinkIcon`, `ImageIcon`, `FileIcon` and `TextIcon` aliases instead.
-- **Accent off in one area:** `data-icon-accent="off"` on a parent paints the accent in the base colour (needs `icons.css`). `data-icons="live"` keeps the accent on at rest in an area when `states.css` is loaded.
-- **Status icons** (one tone) take their colour from the place they sit in: they follow `currentColor`, or a token through `color="var(--color-...)"`, never a hex.
-- **Without React:** `sprite.svg` (copy it to `public/`, `<use href="/sprite.svg#search" />`, two-tone, no hover motion), plain SVG files under `svg/`, or `iconify.json` (prefix `struq`, for Iconify loaders in Vue, Svelte, Astro or Tailwind: the icon in the text colour with the accent at half strength, no hover motion, and `struq:<name>-draw` for a draw-in that plays once and ignores reduced motion). Same family, same rules.
-- **A missing icon** is drawn to the set's rules (24 grid, round caps and joins, the site's stroke, base and accent as two parts) or the whole site moves to row 3. Never patch the gap with a Phosphor glyph.
-
-**Never Lucide as the reflex.** It is the default of every generated UI, so it reads as
-generated. **Never two families on one site.** If the chosen family is missing an icon, either
-draw the missing icon to its rules (its grid, its stroke, its caps and joins) or move the whole
-site to the next family. Patching gaps with a second set is the icon version of three display
-fonts on one page.
-
-**Iconify** is an optional transport for families 3 and 4 (and for Struq Icons outside React) when you want any family through one
-component: one API over about 200k icons across every major set. It is a delivery method, not a
-second family.
-
-```bash
-# Next / any React              # Vite (compile-time, zero runtime, tree-shaken)
-npm i @iconify/react            npm i -D unplugin-icons @iconify/json
-```
-
-```tsx
-// @iconify/react: works in both Next and Vite
-import { Icon } from "@iconify/react";
-<Icon icon="ph:arrow-up-right" className="size-5 text-ink" />   // Phosphor
-<Icon icon="iconoir:search" className="size-5 text-ink" />       // Iconoir
-```
-
-```ts
-// Vite alternative: unplugin-icons, imported as components (no runtime fetch)
-import ArrowUpRight from "~icons/ph/arrow-up-right";
-<ArrowUpRight className="size-5 text-ink" />
+<a href="/werk">Bekijk het werk <ArrowRight size={20} strokeWidth={1.5} /></a>
+<button type="button"><Search size={24} strokeWidth={1.5} label="Zoeken" /></button>
 ```
 
-**Pick one family and stay in it.** Consistency in *style, weight, corner treatment, and
-fill-vs-stroke* is what makes an icon set read as designed. Lock the chosen family in the
-project's icon component so nothing else can be imported by accident.
-
----
-
-## 3. Two registers: system vs decorative
-
-| Register | Use | Traits |
-|---|---|---|
-| **System** | menus, buttons, inputs, table rows, anything **≤24px** | minimal, reduced to essentials, legible at small size, single stroke |
-| **Decorative / expressive** | bigger explanatory moments, feature anchors, animated (Lordicon/Lottie) | richer, more detail, only at **larger** sizes |
-
-**Complex/decorative icons die at small sizes**: their detail turns to mud below ~24px.
-If it's small, it's a system icon. If it's expressive, it's big. Don't mix the registers
-within one role.
-
-One stroke across the set, as the §2 table sets it (Struq Icons `strokeWidth={1.5}`,
-Phosphor `weight="light"`, Tabler `stroke={1.25}`, Iconoir `strokeWidth={1.25}`), one size per
-context (e.g. `size-5` inline, `size-6` nav), ink-colored by default. Struq Icons' two tones
-are not two colours in the §4 sense: at rest under `states.css` they read as one tone, and the
-accent is the site's one accent, shown only where the visitor acts.
-
----
-
-## 4. Color
-
-- **One color across the set** by default: ink. An icon set in four hues reads as no
-  decision made (same rule as the one-accent color system).
-- Color earns its place only for **state** (hover/pressed/active) and **semantics**:
-  red/warning for errors, a success check, etc.
-- Never rely on color *alone* to carry meaning (accessibility, see §7).
-
----
-
-## 5. States & feedback
-
-An icon the user can act on must *look* actionable and must confirm the action:
-
-- Distinct **default / hover / pressed**, via motion, color, or both. A clickable icon
-  that never changes reads as decoration.
-- **Feedback through the icon itself:** a checkmark confirms success, a warning sign flags
-  an error, a state-swap (empty→full trash) signals what happened. Digital UI lacks the
-  physical click of a real switch, so this feedback matters *more*, not less.
-
----
-
-## 6. Animated icons (Lordicon / Lottie): timing is locked
-
-Animated icons convey more meaning than static ones and drive engagement, but only with
-discipline. The same budget as micro-interactions applies: **2 to 3 per view**, never a field
-of looping motion.
-
-**Timing (hard limits):**
-
-| Trigger | Duration | Notes |
-|---|---|---|
-| **Click / tap** | **≤ 500ms** | must keep up with repeat clicks; longer feels out of sync and becomes a distraction by the 3rd press |
-| **Hover (decorative)** | **1500-3000ms** | the delight sweet spot; more complex symbol → longer end of the range |
-| GIF fallback loop | **2000-5000ms delay between loops** | only if tech forces a looping GIF |
-
-**Rules:**
-
-- **No constant loops in dashboards / standard UI.** They become an unwelcome
-  distraction (especially for attention-sensitive users). Trigger on hover instead.
-  A looping animation is fine *as a page loader*, not as ambient dashboard decoration.
-  (This rhymes with the skill-wide "nothing moves that the user didn't cause" principle,
-  [feel-layer.md](feel-layer.md) §5.)
-- **No extreme flashing or flickering**: a seizure/motion-sensitivity hazard. Smooth the
-  frequency; never strobe.
-- **Natural physics only.** Motion that breaks real-world dynamics (unnatural bounce,
-  impossible 3D, irregular movement) leaves users unsettled and confused. Smooth, weighted,
-  accurate. Every movement must serve a purpose and match the icon's meaning (a security
-  icon shouldn't "wave and wiggle").
-- **Don't overload.** Too many animated icons, especially on loop, drown the message.
-
-Animated icons are a micro-interaction: they obey the same library split and gating as
-everything in [micro-interactions.md](micro-interactions.md). Lottie/Lordicon players are
-state/lifecycle-driven (Motion territory for triggering), hover effects are
-`@media (hover: hover)`-gated, and **reduced-motion → static icon** (render the still
-frame, never the animation).
-
----
-
-## 7. Accessibility
-
-- **Meaningful icon:** give it an accessible name via `aria-label` (or visible label, §8).
-  An icon that carries content needs alt text so screen readers convey it.
-- **Decorative icon:** `aria-hidden`, which keeps it out of the a11y tree entirely.
-- **Never color-alone** for meaning (color-vision-deficient and low-vision users). Pair
-  with shape, label, or motion.
-- **Touch target ≥ 48×48px**: the tappable area can exceed the visual glyph. Keep spacing
-  between grouped tappable icons so they don't misfire.
-- **Reduced motion** → static icon (see §6).
-
----
+- `strokeWidth={1.5}` beside light display type (1.25 for a luxury register); one size per context (20 inline, 24 in
+  the bar). `label` names an icon that is a control's only content; without it the icon is decoration.
+- Names are by meaning: the up-right arrow is `External`. Check a name in `dist/index.d.ts` before using it.
+  `Link`, `Image`, `File` and `Text` clash with Next: import `LinkIcon`, `ImageIcon`, `FileIcon`, `TextIcon`.
+- The hover motion is the set's own (hover and focus only, never on load, off under reduced motion).
 
-## 8. Labels, universal icons, conflicts
+## Without React
 
-- **Labels:** before users click, they need to know what to expect. Universal icons (home,
-  play, stop, pin, search) are self-evident; anything ambiguous needs a **1 to 3 word label**
-  using an action word (Buy, Continue, Subscribe). Icons reinforce; labels disambiguate.
-- **Universal icons reduce cognitive load.** Lean on the globally-recognized set where it
-  fits, beyond cultural differences.
-- **Conflicting icons** (heart vs star both mean "favorite/save/rate"): don't avoid them,
-  **consciously pick one** and label its function clearly. Don't use one icon for two
-  purposes or two icons for one purpose.
-- **Cultural context** matters for unique/symbolic icons, so consider the audience.
-- **Test** new icons with outsiders for *recognizability* (do they understand it?) and
-  *memorability* (do they recall it a week later?). Re-design or add a label if not.
+`iconify.json` with the prefix `struq` (`struq:search`, `struq:<name>-draw` for a draw-in), `sprite.svg` with
+`<use href="/sprite.svg#search" />`, or the plain SVG files. Same rules.
 
----
+## The one fallback
 
-**Cheap tell:** Lucide `Sparkles`/`Rocket`/`Zap` in colored circle chips, 3-up, as
-feature decoration; an animated icon looping forever in a dashboard; a 500ms+ click
-animation that lags the cursor; a tiny decorative icon turned to mud at 16px.
-**Instead:** One deliberately chosen icon family, system vs decorative registers kept separate,
-ink-colored with color only for state/semantics, animated only where it informs and
-within the timing limits, labeled where not universal, `aria` correct, ≥48px targets.
+When the set lacks an icon and drawing it to the set's rules (24 grid, round caps and joins, the site's stroke, base
+and accent as two parts) is not worth it, move the whole site to **Phosphor at `weight="light"`**
+(`@phosphor-icons/react`, or Iconify `ph:`). One family per site, never mixed, never Lucide by reflex.

package/skills/struq/references/stack-targets.md

@@ -1,78 +1,27 @@
-# Stack Targets: detect Vite vs Next.js, then adapt
+# Vite and other React stacks
 
-Every other reference file is written for **Next.js App Router** (Struq's default
-stack). Most of the doctrine is framework-agnostic, but a handful of primitives are
-Next-specific and will break or mislead in a Vite project. **Detect the stack before
-writing any wiring code**, then translate the Next-only pieces.
+The blocks are written for Next.js App Router. Only four things tie them to it; everything else (GSAP, Lenis, the
+kit, the CSS, the tokens) is plain React and Tailwind v4. Detect the stack first: `next` in package.json and an `app/`
+folder is Next; `vite.config.*` with `src/main.tsx` is Vite.
 
----
+`blocks.mjs` refuses a project without `next`: copy the files by hand instead, keeping the layout of `blocks/` under
+`src/components/struq/` so the relative imports hold (each block's files are listed in `blocks/catalog.json`).
 
-## 1. Detect first
-
-| Signal | Stack |
+| Next.js | Vite |
 |---|---|
-| `next.config.{js,ts,mjs}` present, or an `app/` directory with `layout.tsx` | **Next.js App Router**: use the reference files as written |
-| `next.config` present but `pages/` not `app/` | **Next Pages Router**: providers wrap in `_app.tsx`; `template.tsx` patterns use route events instead |
-| `vite.config.{js,ts}` present | **Vite**: translate per §2 (React assumed; Vue/Svelte share the concepts, different syntax) |
-| neither (CRA, Astro island, Webflow, plain Vite-less) | framework-agnostic core only: Lenis/GSAP provider + CSS; skip Next primitives |
-
-Check `package.json` deps to confirm: `next` vs `vite` + `react-dom`. If a router is
-present in Vite, it is almost always `react-router-dom`, and that is what the transition
-patterns below assume.
-
-Then read the installed majors (`vite`, `react`, `tailwindcss`, `gsap`, `lenis`, the router) and record them on the `Stack:` line; the installed version beats this file whenever they disagree ([setup.md](setup.md) §0, Known API shifts). Scaffold an empty folder with `npm create vite@latest`.
-
----
-
-## 2. Translation table: Next App Router → Vite
-
-| Concern | Next App Router | Vite (React SPA) |
-|---|---|---|
-| **Fonts** | `next/font/google` / `next/font/local` exposing CSS vars | `@fontsource/<face>` (npm) **or** self-hosted `@font-face` in CSS; `<link rel="preload">` the woff2 in `index.html`. Map the same `--font-display-face` / `--font-body-face` vars. (Pairing and weight decisions: [typography.md](typography.md).) |
-| **Lazy / SSR-free island** (WebGL) | `next/dynamic(() => import("./X"), { ssr: false })` | `React.lazy(() => import("./X"))` + `<Suspense fallback={poster}>`. A Vite SPA is already client-only, so there is no SSR tree to exclude; the lazy boundary is purely for bundle-splitting. |
-| **Client/server boundary** | `"use client"` directive on leaf components | **Drop it.** It is a no-op in Vite; everything is a client component. Remove the directive when porting snippets. |
-| **Providers mount point** | `app/layout.tsx` wrapping `{children}` | `src/main.tsx` (or `App.tsx`) wrapping `<App/>`: `<SmoothScrollProvider>`, etc. Same component, different host file. |
-| **Per-navigation remount** (page-transition entrance) | `app/template.tsx` (re-mounts each navigation) | a wrapper keyed on `useLocation().pathname`, e.g. `<motion.div key={pathname}>` or an `<AnimatePresence mode="wait">` around the routed outlet. Same effect: fresh mount per route. |
-| **Route-change transitions** | `template.tsx` + `PageTransitionProvider` ([route-transitions.md](route-transitions.md)) | `AnimatePresence` driven by the router location; the curtain/overlay logic is identical, only the trigger source changes. |
-| **Images** | `next/image` (auto sizing, lazy, AVIF/WebP) | `<img>` with **explicit `width`/`height`** (or aspect-ratio box) + `loading="lazy"` + `decoding="async"`; for responsive sources use `srcset` or `vite-imagetools`. Keep explicit dims for CLS regardless. |
-| **Metadata / head** | `metadata` export / `generateMetadata` | `react-helmet-async` or set tags in `index.html`. |
-| **Icons** | `@struq/icons` (the default; Phosphor light the fallback) | The same React package and root CSS imports in `src/main.tsx`; non-React or Iconify-based stacks use its `iconify.json` (prefix `struq`) or `sprite.svg` ([iconography.md](iconography.md) §2). |
-| **Env / public assets** | `/public`, `process.env.NEXT_PUBLIC_*` | `/public`, `import.meta.env.VITE_*`. |
-
----
-
-## 3. What is identical on both (do NOT re-derive)
-
-These carry over unchanged. Only the *mount file* differs:
-
-- **The smooth-scroll provider**: Lenis driven by `gsap.ticker` with `autoRaf: false` +
-  `lagSmoothing(0)` ([setup.md](setup.md) §2). One RAF clock. Identical code; mount it in
-  `app/layout.tsx` (Next) or `main.tsx` (Vite).
-- **The GSAP registry module** (`lib/gsap.ts`), `gsap.defaults`, and **all `useGSAP`
-  rules**: scope ref, `contextSafe`, `autoAlpha`, animate `from` so the SSR/initial HTML
-  is the final state ([setup.md](setup.md) §1, §3). The same registry covers the plugins used by [svg-motion.md](svg-motion.md) (DrawSVG, MorphSVG).
-- **`gsap.matchMedia` reduced-motion guard** ([setup.md](setup.md) §4).
-- **The WebGL island's `frameloop:"never"` + GSAP-ticker bridge** ([webgl-r3f.md](webgl-r3f.md) §2,
-  scene recipes in [webgl-scenes.md](webgl-scenes.md)). R3F is router-agnostic; the single-clock
-  wiring is the same. Only the lazy-boundary primitive changes (`next/dynamic` → `React.lazy`, per §2).
-- **The scaling knob**: one CSS rule in the global stylesheet ([scaling.md](scaling.md)),
-  `app/globals.css` vs `src/index.css`.
-- **All Iconify usage**, the token/`@theme` system, every ScrollTrigger/scrub/pin
-  technique (including every recipe in [showcase.md](showcase.md)), and all motion *values* ([feel-layer.md](feel-layer.md)).
-
-The rule of thumb: **anything that touches the DOM, the GSAP ticker, or CSS is portable;
-anything that says `next/...` or `"use client"` needs the §2 translation.**
-
----
-
-## 4. Vite gotchas worth flagging
-
-- **No SSR safety net by default.** Code that reads `window` at module scope is fine in a
-  Vite SPA (no server render), but keep it in effects anyway for correctness and so the
-  component stays portable back to Next.
-- **`ScrollTrigger.refresh()`** is still needed after route changes and after fonts/images
-  settle. Wire it to the router's location change (the App Router note in
-  [setup.md](setup.md) §6 applies, just via `react-router` instead of `template.tsx`).
-- **StrictMode double-invoke** in dev re-runs effects twice. `useGSAP` cleanup handles
-  it, but raw `useEffect` GSAP setup will leak, which is another reason never to write raw
-  `useEffect` for GSAP ([setup.md](setup.md) §3).
+| `next/image` (`<Image fill sizes priority>`) | `<img>` with `width`, `height`, `loading`, `decoding="async"`, and `object-cover` on a positioned box for `fill`. `getImageProps` (page-transition-stack) becomes the plain `src`. |
+| `next/link` | `<a>`, or your router's `Link`. |
+| `next/navigation` in the page transitions (`usePathname`, `useRouter`, `useSearchParams`) | Your router's location and navigate (React Router `useLocation`, `useNavigate`). The transitions only need the current path and a push. |
+| `"use client"` | Delete it, or leave it: Vite ignores it. |
+
+The shell, in Vite terms:
+
+- `index.html`: in `<head>`, the gate script `<script>document.documentElement.classList.add('sq-js')</script>` before
+  any stylesheet, and one `<link rel="stylesheet">` per URL that `canon.mjs print <palette> <pairing>` prints;
+  `<body data-blocks>`.
+- `src/index.css`: `@import "tailwindcss";`, the kit import, the `@theme inline` names and the STRUQ TOKENS block from
+  `recipes/app/globals.css` (the block comes from `canon.mjs print`).
+- `src/main.tsx`: wrap the app in `SmoothScroll` from the kit.
+
+`check.mjs` reads `app/layout.tsx` for the gate; on Vite it reports that line as missing. Check `index.html` by eye
+and note it under Verify in STRUQ.md.

package/skills/struq/references/tells.md

@@ -0,0 +1,52 @@
+# The tell list
+
+One list: Struq's tells, the slop audit and Roy's rules. Each is something a generator does by reflex and a studio
+never does. `check.mjs` detects the marked ones (and `struq_controle` returns the same rules when the MCP is
+connected); the rest are judged by eye. The fix is beside each.
+
+## Type and labels
+
+- **Eyebrows:** a small label above a heading ("OUR APPROACH", "PREMIUM SERVICE"), any uppercase tracked label or
+  marquee. Fix: the heading carries itself; wayfinding is a hairline, a change of surface step, a jump in scale. A
+  caption under or on an image (`<figcaption>` or `data-caption`) is media metadata and allowed. (check)
+- **Numbered steps** (01 / 02 / 03) and section numbers. Fix: hairline rows or a sequence the layout makes obvious. (check)
+- **Mono on marketing:** monospace as a design face. Fix: mono only for literal code. (check)
+- **The generator faces:** Inter, Roboto, Arial, Helvetica, Open Sans, Poppins, Montserrat, Lato, Geist, Space
+  Grotesk, and Playfair, Anton, Oswald, Cormorant or Manrope as a display. Fix: a canon pairing. (check)
+- **Heavy display** outside the poster pairings, `font-bold` on headings, raw sizes (`text-5xl`) and breakpoint size
+  ladders. Fix: the type roles and `--display-weight`. (check)
+
+## Colour and surface
+
+- **Gradients of any kind,** gradient text, glass, tinted translucent fills. Fix: flat tokens; a flat veil over a
+  photo is the only translucent layer. (check)
+- **Glow:** coloured shadows, neon edges, blurred light behind a card. Fix: none. (check)
+- **Default purple or blue:** an indigo or violet accent nobody chose. Fix: a canon palette; blue only when the brand
+  is blue, declared in STRUQ.md as `Cool hue: declared because <the brand colour>`. (check)
+- **Pills,** above all a pill with a dot; pulsing live dots; pastel status badges. Fix: a text link or a rectangular
+  button. (check)
+- **Drop-shadow elevation** and side-stripe borders. Fix: a surface step and a hairline.
+
+## Layout and motion
+
+- **Icon grids:** three or six identical cards, each an icon, a heading and two grey lines. Fix: hairline rows,
+  `hover-list`, `panel-accordion`, or one statement. (check)
+- **Stat banners** ("20+", "99%", "51+") the brief did not give. Fix: leave them out. (check)
+- Uniform section padding, the same hover on everything, opacity-only entrances, single-layer parallax. Fix: the
+  craft rules in [craft.md](craft.md).
+- An empty or placeholder frame, a grey box, "photo to come". Fix: a beeldbank photo. (check)
+
+## Copy and icons
+
+- **Em and en dashes** in any form, in copy, comments and alt text. Fix: restructure the sentence: a comma, a colon, a
+  full stop. (check)
+- Generic CTAs ("Learn more", "Get started", "Lees meer"), generic headings ("Our Services", "Over ons"), hype words
+  ("seamless", "naadloos", "next-level"), lorem, Acme, leftover template text. Fix: specific words from the brief. (check)
+- Emoji and the cliche icons (sparkles, rocket, lightning, bulb, wand). Fix: Struq Icons, functional only. (check)
+- Invented facts: testimonials, client logos, stats, awards, prices, addresses, hours, bios, quotes the brief did not
+  give. Fix: leave them out and list them under Assumptions.
+
+## Judged by eye
+
+The hero-metric template (big number, small label, three times), category-reflex colours (green for eco, blue for
+finance), a heading the paragraph restates, a page that reads as a SaaS template in a studio's palette.

package/skills/struq/references/triage.md

@@ -37,25 +37,25 @@ change its dress.
 ## Fair game: fix freely (this is what you were called for)
 
 - **Layout / structure / IA**: restructure sections, reorder, break the grid, fix the
-  symmetric "SaaS stack." Layout is execution, not identity. ([page-architecture.md](page-architecture.md))
+  symmetric "SaaS stack." Layout is execution, not identity: swap in blocks where the page is weakest (the hero, the work, the footer first).
 - **Spacing rhythm**: kill uniform `py-16`, vary padding by section role.
 - **Type scale + weight**: fix the five-mid-sizes problem, lighten hero weights, enforce
-  the readable floor and contrast minimums ([anti-patterns.md](anti-patterns.md) §12). If the
+  the readable floor and contrast minimums. If the
   brand already owns its typefaces, keep them and change how they are set, not which they are
-  ([typography.md](typography.md)).
+  (their faces go into --face-display and --face-body).
 - **Surfaces / elevation**: replace `shadow-lg` cards with the tonal ladder.
 - **Motion / reveals**: replace opacity-only fades, add transform+stagger, fix easing.
 - **Scaling**: convert px-everything + per-breakpoint size ladders to the fluid root-rem
-  system ([scaling.md](scaling.md)).
+  system ([craft.md](craft.md)).
 - **Icon misuse**: remove Sparkles/Rocket/Zap/emoji, colored chips, decorative filler;
   consolidate to one icon family ([iconography.md](iconography.md)): the brand's own set if it has one, else Struq Icons (`@struq/icons`). A redesign that already uses one coherent non-Lucide family keeps it (preserve by default); one family per site, never mixed.
-- **Everything in [anti-patterns.md](anti-patterns.md)**: that gallery is the fix list.
+- **Everything in [tells.md](tells.md)**: that list is the fix list.
 
 ---
 
 ## Workflow
 
-1. **Scan** with [anti-patterns.md](anti-patterns.md) and collect every tell.
+1. **Scan** with check.mjs (and struq_controle when connected) and [tells.md](tells.md); collect every tell.
 2. **Filter** the findings through the preserve-list above. A "fix" that reassigns brand
    color, rewrites copy, or replaces a component primitive is dropped (or downgraded to a
    *suggestion* the user can opt into), not applied.
@@ -68,4 +68,3 @@ change its dress.
 When unsure whether something is identity or execution, **ask** rather than assume, but
 default to preserving the three categories above.
 
-If the work started from a brief, [brief-router.md](brief-router.md) still runs, with this file's rules overriding it: identity is preserved and the router only re-decides execution.