@struq/skill 0.2.2 → 0.4.0

package/skills/struq/cinematic/examples/code/nextjs/app/components/LenisRoot.tsx

@@ -21,7 +21,7 @@ export function LenisRoot({ children }: LenisRootProps): JSX.Element {
   useEffect(() => {
     // Registered unconditionally; the instance is resolved through the ref on
     // every frame. Never capture it once and early-return: that is the
-    // dead-scroll race (references/setup.md §2).
+    // dead-scroll race.
     const update = (time: number) => {
       lenisRef.current?.lenis?.raf(time * 1000);
     };

package/skills/struq/cinematic/examples/code/shared/styles.css

@@ -55,7 +55,7 @@ a {
 }
 
 /* Demo values. In a Struq build the h1 takes `font-display text-display` and the
-   pairing's tracking from typography.md §3.1; the clamp keeps a rem term for zoom. */
+   pairing's tracking; the clamp keeps a rem term for zoom. */
 .experience-copy h1 {
   margin: 0;
   font-size: clamp(2.875rem, 1.2rem + 6.86vw, 8rem);

package/skills/struq/cinematic/examples/code/vite/src/LenisRoot.tsx

@@ -16,7 +16,7 @@ export function LenisRoot({ children }: LenisRootProps): JSX.Element {
   useLenis(() => ScrollTrigger.update());
 
   useEffect(() => {
-    // Registered unconditionally, instance resolved per frame (references/setup.md §2).
+    // Registered unconditionally, instance resolved per frame.
     const update = (time: number) => {
       lenisRef.current?.lenis?.raf(time * 1000);
     };

package/skills/struq/cinematic/references/01-core-mental-model.md

@@ -118,7 +118,7 @@ These transitions should have explicit entry, active, and exit states.
 
 ## One clock, several signals
 
-There is exactly one frame clock. Lenis is advanced from `gsap.ticker`, ScrollTrigger reads from Lenis, and the R3F canvas is advanced from the same ticker (see [`../../references/setup.md`](../../references/setup.md) and [`../../references/webgl-r3f.md`](../../references/webgl-r3f.md)). Nothing in the experience runs its own `requestAnimationFrame` loop. Scroll progress and elapsed time are different signals read on that one clock, not different clocks.
+There is exactly one frame clock. Lenis is advanced from `gsap.ticker`, ScrollTrigger reads from Lenis, and the R3F canvas is advanced from the same ticker (the kit's `SmoothScroll` and [`../examples/code/shared/GsapFrameLoop.tsx`](../examples/code/shared/GsapFrameLoop.tsx)). Nothing in the experience runs its own `requestAnimationFrame` loop. Scroll progress and elapsed time are different signals read on that one clock, not different clocks.
 
 At minimum, distinguish:
 

package/skills/struq/cinematic/references/02-vocabulary.md

@@ -138,7 +138,7 @@ Offsetting related elements. A stagger should communicate reading order, directi
 Mapping scroll progress to a timeline playhead.
 
 ### Smoothing
-Reducing abrupt changes in a signal. Lenis smoothing, ScrollTrigger scrub smoothing, and manual damping should be assigned intentionally rather than stacked without control. Pair them the way the main skill does in [`../../references/feel-layer.md`](../../references/feel-layer.md): lower the Lenis lerp, lower the scrub number, and use `scrub: true` for attached layers and a small number for floating ones.
+Reducing abrupt changes in a signal. Lenis smoothing, ScrollTrigger scrub smoothing, and manual damping should be assigned intentionally rather than stacked without control. Pair them: lower the Lenis lerp, lower the scrub number, and use `scrub: true` for attached layers and a small number for floating ones.
 
 ### Easing
 The mathematical shape of a known transition between values.

package/skills/struq/cinematic/references/07-stack-integration.md

@@ -73,7 +73,7 @@ Key integration responsibilities:
 - Lenis is stopped during states that require scroll lock.
 - native nested scrolling is handled deliberately.
 
-Lenis must be created with `autoRaf: false`. If it keeps its own animation loop it becomes a second clock next to `gsap.ticker`, and scroll, ScrollTrigger and the canvas drift apart by a frame. The canonical setup lives in [`../../references/setup.md`](../../references/setup.md); this is the conceptual shape.
+Lenis must be created with `autoRaf: false`. If it keeps its own animation loop it becomes a second clock next to `gsap.ticker`, and scroll, ScrollTrigger and the canvas drift apart by a frame. The canonical setup is the kit's `SmoothScroll` (`blocks/kit/SmoothScroll.tsx`); this is the conceptual shape.
 
 Conceptual setup:
 
@@ -102,7 +102,7 @@ Do not add CSS `scroll-behavior: smooth` on top of Lenis.
 
 ## R3F frame-loop options
 
-The single-clock rule applies: the canvas is rendered from `gsap.ticker`, the same callback chain that advances Lenis. The exact bridge is documented in [`../../references/webgl-r3f.md`](../../references/webgl-r3f.md) and shown in [`../examples/code/shared/GsapFrameLoop.tsx`](../examples/code/shared/GsapFrameLoop.tsx).
+The single-clock rule applies: the canvas is rendered from `gsap.ticker`, the same callback chain that advances Lenis. The exact bridge is shown in [`../examples/code/shared/GsapFrameLoop.tsx`](../examples/code/shared/GsapFrameLoop.tsx).
 
 ### Ticker-driven loop (default)
 

package/skills/struq/recipes/app/fonts.ts

@@ -0,0 +1,12 @@
+// app/fonts.ts (Struq recipe). canon.mjs type <pairing> rewrites this file; the default is serif-editorial.
+// Each Google face is asked for its real weight range, then as the bare family as a fallback, because Google refuses a
+// request for a weight the family lacks. The layout puts one <link> per URL in <head>; the token block in globals.css
+// names the faces (--face-display, --face-body, --face-accent), so the blocks measure with the real face.
+export const fontHrefs: string[] = [
+  "https://fonts.googleapis.com/css2?family=Fraunces:wght@100..900&display=swap",
+  "https://fonts.googleapis.com/css2?family=Fraunces&display=swap",
+  "https://fonts.googleapis.com/css2?family=Urbanist:wght@100..900&display=swap",
+  "https://fonts.googleapis.com/css2?family=Urbanist&display=swap",
+  "https://fonts.googleapis.com/css2?family=Fraunces:ital,wght@1,100..900&display=swap",
+  "https://fonts.googleapis.com/css2?family=Fraunces:ital@1&display=swap",
+];

package/skills/struq/recipes/app/globals.css

@@ -0,0 +1,42 @@
+@import "tailwindcss";
+/* The block kit: type roles, the motion gate (.sq-js with its 3 s fallback), the contrast scenes and every block's
+   own CSS, all scoped to [data-blocks] (on <body>). */
+@import "../components/struq/kit/blocks.css";
+
+/* The theme names the blocks use that the kit leaves to the site. */
+@theme inline {
+  --color-accent: var(--accent);
+  --color-accent-2: var(--accent-2);
+  --color-photo-ground: var(--photo-ground);
+  --font-display: var(--face-display), ui-serif, Georgia, serif;
+}
+
+/* One fluid root-rem knob: author in rem, breakpoints change layout, never size. */
+html {
+  font-size: clamp(1rem, 0.92rem + 0.2vw, 1.125rem);
+}
+
+/* STRUQ TOKENS: palette graphite-ivory, type serif-editorial. Written by canon.mjs, the block Struq's lab and struq_richting give. */
+[data-blocks] {
+  --surface-0: #F3F0E8;
+  --surface-1: #E8E1D5;
+  --surface-2: oklch(0.8674 0.0168 81.33);
+  --surface-3: oklch(0.8101 0.0154 81.33);
+  --ink: #272826;
+  --ink-muted: color-mix(in oklab, var(--ink) 66%, var(--surface-0));
+  --accent: #995029;
+  --accent-ink: #F3F0E8;
+  --accent-2: #2B4A56;
+  --line: color-mix(in oklab, var(--ink) 13%, transparent);
+  --on-photo: #F3F0E8;
+  --photo-ground: #272826;
+  --inverse: #272826;
+  --on-inverse: #F3F0E8;
+  --field: #995029;
+  --on-field: #F3F0E8;
+  color-scheme: light;
+  --display-weight: 300;
+  --face-display: "Fraunces";
+  --face-body: "Urbanist";
+  --face-accent: "Fraunces";
+}

package/skills/struq/recipes/app/layout.tsx

@@ -0,0 +1,30 @@
+// app/layout.tsx (Struq recipe). Set the title, the description and lang.
+// The inline script puts `sq-js` on <html> before first paint: the kit's motion gate keys off it, so an animated
+// element never flashes before its entrance, shows anyway after 3 s, and a visitor without JavaScript sees the page.
+// data-blocks on <body> is the scope every block and the STRUQ TOKENS block read.
+import type { Metadata } from "next";
+import { SmoothScroll } from "../components/struq/kit/SmoothScroll";
+import { fontHrefs } from "./fonts";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "SITE_TITLE",
+  description: "SITE_DESCRIPTION",
+};
+
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+  return (
+    <html lang="nl" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: "document.documentElement.classList.add('sq-js')" }} />
+        <link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="" />
+        {fontHrefs.map((href) => (
+          <link key={href} rel="stylesheet" href={href} />
+        ))}
+      </head>
+      <body data-blocks="">
+        <SmoothScroll>{children}</SmoothScroll>
+      </body>
+    </html>
+  );
+}

package/skills/struq/references/craft.md

@@ -0,0 +1,77 @@
+# Craft: what makes the blocks feel high end
+
+The blocks already do all of this. Read it when you write the glue between blocks, adapt one, or build a section the
+catalogue does not have: your code has to hold the same bar or it shows as the seam.
+
+## Motion
+
+- **One clock.** Lenis runs on `gsap.ticker` (`kit/SmoothScroll.tsx`, mounted once in the layout); ScrollTrigger reads
+  it. No second `requestAnimationFrame` loop, no `anticipatePin` with smooth scroll. A menu or overlay calls
+  `getLenis()?.stop()` and `start()`.
+- **Clip from numbers.** A reveal is a clip on a layer already at its full size, never a scale of the box. Tween plain
+  numbers (top, right, bottom, left, radius) and write `clip-path: inset(...)` from them in `onUpdate`; never tween
+  one clip-path string into another, which GSAP interpolates through broken intermediate values.
+- **Whole pixels.** Round every computed translate, clip edge and fitted size to whole pixels (`Math.round`, or
+  `gsap.utils.snap(1)`), so type and hairlines never sit on half pixels and shimmer while they move.
+- **Decode before show.** `await img.decode()` (with a catch) before a photo is revealed, cut to or swapped in; a
+  sequence of photos starts only when all are decoded. A reveal over an undecoded image shows a blank frame.
+- **Scroll-tied and reversing.** A scroll effect scrubs (`scrub: true` or a short number) and runs backwards when the
+  visitor scrolls back: scrolling up re-sets the large wordmark, closes the print, lowers the line. A one-way
+  entrance on scroll reads as a template. Entrances on load play once.
+- **Hold on the key frames.** A pinned stretch spends part of its length still on each composed frame. One idea per
+  screen, long eases (`expo.out` in, `power4.inOut` for curtains), nothing bounces.
+- **Every entrance moves and fades,** never opacity alone. Lines rise through masks (`SplitText` with `mask: "lines"`,
+  the `.struq-line-mask` padding keeps descenders).
+- **One handover signal.** Preloaders and page transitions close a cover (`data-curtain="closed"` on `<html>`) and fire
+  `curtain:lift` when it opens; a hero runs its entrance through `whenUncovered` from
+  `preloaders/preloader-slices-uncovered.ts`, so the same entrance serves the first load and every navigation.
+
+## The gate
+
+- `<html class="sq-js">` is set by an inline script before first paint (the layout recipe). The kit's CSS hides only
+  under `.sq-js`: `[data-split]`, `[data-reveal]` children and `[data-frame="mask"]` wait for `data-ready`, and a CSS
+  animation shows them anyway after 3 s. A visitor without JavaScript, or a script that throws, still gets the page.
+- Never hide content with an inline `opacity: 0` or a class your script removes. Use the gate attributes, or your own
+  rule under `.sq-js` with the same 3 s fallback.
+- Under `prefers-reduced-motion` every block lands on a composed still: the final frame, no pin, no scrub. Phones get
+  the same still where a pin would fight the thumb.
+
+## Photos and type on photos
+
+- **The calm side is measured.** `kit/photo-read.ts` reads the photo's luminance under the type's box; the heroes put
+  the headline on the side that needs the weaker veil. The beeldbank's `negativeSpace` sets the first paint and
+  breaks a tie; pass `side` only when you know better.
+- **A light veil.** Type over a photo gets the weakest flat veil that gives the headline 3:1 and a running line 4.5:1,
+  measured from that photo, capped at about a quarter. Never a gradient scrim, never a dark band by habit.
+  `--photo-ground` is the palette's own dark ground for a bar or band laid over a photo.
+- **Never an empty frame.** Every image slot holds a real photo from `lib/struq-images.ts` or the client. A photo shows
+  the world around the client, never their own room, team or product unless it is theirs; captions come from the alt.
+
+## Type
+
+- **Light display weights.** The display face runs at the pairing's weight (`--display-weight`, 300 for most, 400 where
+  the face starts at 400, 700 or 800 only for the poster pairings). Never `font-bold` on a heading; hierarchy comes
+  from scale: `text-display`, `text-h2`, `text-h3`, `text-lead`, `text-body`, `text-small`.
+- **Real faces, measured.** A line fitted to the width (a wordmark, a poster line) is measured after
+  `document.fonts.ready` with the loaded face, and refitted on `loadingdone`. Never fit with the fallback face, and
+  never ask Google for a weight the family does not ship: `canon.mjs type` requests each face's real range.
+- **Word spacing at poster size:** 0.06 to 0.1em on display lines, so tight tracking never runs two words into one.
+- One italic accent face at most, on one word of the page.
+- One fluid root-rem knob (`html { font-size: clamp(...) }` in globals.css): author in rem; breakpoints change the
+  layout, never the size.
+
+## Colour and surface
+
+- Tokens only: `--surface-0` to `--surface-3`, `--ink`, `--ink-muted`, `--accent`, `--accent-ink`, `--line`,
+  `--on-photo`, `--photo-ground`, `--inverse`, `--on-inverse`, `--field`, `--on-field`. The surface steps hold the
+  ground's hue; mixes are `in oklab`, never `in oklch` (an oklch mix walks round the hue wheel and turns cream lilac).
+- **One contrast scene,** at most two: wrap a section in `scene-inverse` (the palette's dark ground, light type) or
+  `scene-field` (the accent at full strength); every block inside follows the turned tokens.
+- Elevation is a surface step plus a hairline, never a shadow. Radius 0 to 4px. Flat fills, no gradients, no glass.
+
+## Composition
+
+- The display type is the composition, not a heading above it: 12 to 20vw on the poster lines, small body beside it.
+- Vary the sections: after a split comes a full-bleed band or hairline rows, never three equal cards. Section padding
+  varies by role; one section should feel too empty by template standards.
+- Never two pinned pieces back to back: a plain section breathes between them.

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). 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.