@struq/skill 0.3.0 → 0.4.0

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

@@ -1,330 +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">
-  <h2 className="font-display text-h2 max-w-[18ch]">What we take on, start to finish</h2>
-  <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 hairlines, not from a label or 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 quiet `text-small text-ink-muted` meta lines (sentence case) for captions and dates. No label above a heading (§19). 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: hairline rules, scale jumps, surface changes, the headings themselves. Never tracked uppercase eyebrows: they are a tell of their own (§19). 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 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))
-
----
-
-## 19. Eyebrows
-
-**Reflex:**
-```tsx
-<p className="text-xs font-medium uppercase tracking-[0.18em] text-ink-muted">Restaurant in Amsterdam-Noord</p>
-<h1 className="font-display text-display">Vis en groente, van het seizoen.</h1>
-```
-**The tell:** a small uppercase tracked label above every heading. Generated pages put one on every section because it looks "designed" at no cost; the result is the most recognisable AI marketing page there is, and it competes with the heading it sits on.
-
-**Agency:** the heading carries the section alone. Wayfinding comes from a hairline rule (`border-t border-line`), a change of surface step, a jump in scale, an image. A place or a date the reader needs goes in the lead line under the heading, in sentence case. `check.mjs` fails on `uppercase` with `tracking-`.
-
----
-
-## 20. Gradients, tinted fills and glass
-
-**Reflex:** `bg-linear-to-b from-surface-0 to-surface-2` on a section, `bg-accent/10` behind a label, `bg-white/5 backdrop-blur` on a card, a radial glow behind the hero.
-
-**The tell:** colour that is neither a surface nor the accent. Translucent tints and gradients are the generator's way to make a flat page "rich"; they muddy the palette and read as a template on sight.
-
-**Agency:** flat, opaque surface steps (`bg-surface-1`, `bg-surface-2`) and hairlines. The only translucent fill is a flat black scrim over a photo so type in `text-on-photo` reads. Depth comes from the WebGL hero, the photography and the overlap of sections, not from washes.
-
----
-
-## 21. Pills
-
-**Reflex:** `rounded-full px-4 py-1.5 bg-accent/10 text-accent` badges, a "New" pill with a pulsing dot, pill-shaped buttons.
-
-**The tell:** the pill with a dot is the badge of every generated launch page. Pills everywhere also break the site's radius system.
-
-**Agency:** the site radius (0 to 4px) on every button and frame; status as words in the lead line; no badges. The primary CTA is a `MagneticButton`, square-cornered, its fill rising on hover.
-
----
-
-## 22. Empty frames
-
-**Reflex:** an `aspect-[16/9] bg-surface-2` box with "Foto volgt" in it, or a placeholder component standing in for a photo that never came.
-
-**The tell:** the reader sees the site was not finished, and a plain page with no images at all beats it.
-
-**Agency:** every frame holds a real image: the client's photo, or the Struq beeldbank pack (`scripts/images.mjs`, automatic, CC0), or, when struq.nl is unreachable, the graded fallback plate the script writes. Never ship an empty frame ([struq-imagery.md](struq-imagery.md)).
-
----
-
-## 23. The smaller tells
-
-Each is cheap on its own; three of them together read as generated.
-
-| Tell | Reflex | Instead |
-|---|---|---|
-| Side-stripe borders | `border-l-4 border-accent` down a card or a quote | a hairline, or nothing |
-| Status badges | `bg-green-100 text-green-700` "Available" chips | the fact in the lead line |
-| Live dots | an `animate-ping` dot beside "Now open" | the words alone |
-| Uppercase marquees | a scrolling band of tracked capitals | a large display line in sentence case, if any marquee at all |
-| Generic CTAs | "Learn more", "Get started", "Lees meer" | a verb and the thing: "Reserveer een tafel", "Bekijk de projecten" |
-| Generic headings | "Our Services", "Why Choose Us", "Over ons" | a heading only this business could write |
-| Hype copy | "seamless", "elevate", "next-level", "naadloos", "revolutionair" | the plain, specific claim from the brief |
-| Hero-metric template | a hero followed by a strip of four big numbers | numbers only when the brief gives them, set inside the copy |
-| Category-reflex colours | green for every eco brand, blue for every bank, purple for every AI | the canon palette that fits the mood; the reflex hue only when it is the brand's own |
-| Restated headings | a paragraph that repeats the heading in more words | the paragraph adds the next fact |
-
----
-
-## The 30-second tell scan
-
-The script does this scan for you: `node <skill-dir>/scripts/check.mjs` prints every hit with its file and line. By hand:
-
-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
-- `uppercase` with `tracking-`, or an `eyebrow`/`kicker` class → §19 · `gradient|bg-linear-|backdrop-blur|bg-accent/` → §20 · `rounded-full` with `px-` → §21 · `Placeholder`, an empty `aspect-` div → §22
-- `tracking-tight`, `text-ink-faint`, or `uppercase` with `tracking-` anywhere (the eyebrow tell, §19), or `text-xs` on headings (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,122 +0,0 @@
-# The Minimal Baseline: rationale + standalone paste block
-
-**SKILL.md carries the short form of this baseline ("The taste baseline") and the Build checklist that enforces it.** 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 paste block below must agree with SKILL.md ("The taste baseline" and "Three rules that never bend"). When a rule changes there, change it here in the same commit. -->
-
-## The paste block (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, meta text-meta, font-ui text-ui,
-stat text-stat, and font-display text-statement for the one Orient line
-or manifesto. NO EYEBROWS: no small uppercase tracked label above a
-heading, no uppercase marquee. The heading, a hairline and scale do the
-wayfinding; captions and dates are meta in sentence case, ink-muted.
-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 gradients
-of any kind, no gradient text, no glass, no tinted translucent fills (a
-flat black scrim over a photo is the one exception), no pills, no pulsing
-dots. No blue or purple unless the brand is that colour.
-
-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, never invented facts. Never
-01/02/03 stamped on every section (one deliberate oversized numeral is
-fine). Never an empty image frame. 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 (Struq's canon, the beeldbank, the Lenis + GSAP single clock, the SplitText hero, a showpiece, the WebGL hero layer) run the Build checklist in [SKILL.md](../SKILL.md).
-
-## 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 fix for the "medium subhead" that flattens hierarchy is not a tracked-uppercase eyebrow (that is a tell of its own) but a bigger gap between display and body. Role tokens (`text-display`, `text-h2`, `meta text-meta`) 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). Long pages get their editorial spine from hairline rules, surface steps and headings that say something, never from tracked eyebrow labels. 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."

package/skills/struq/references/brand.md

@@ -1,143 +0,0 @@
-# Brand: name, logo, mark and the files a site needs
-
-Run this when the project has no name or no logo. When a brand exists, do not redesign it; extract it ([direction.md](direction.md) §2). The output is small on purpose: a name, a wordmark, a mark, the favicon set, and one voice line. A brand guideline PDF is not the job. A site that carries the brand is.
-
-Order matters: **positioning, then name, then type, then logo.** A name chosen first forces the positioning to be bent around it. A logo drawn before the typefaces are chosen never sits right in the site.
-
-## 1. Positioning in two lines
-
-Before naming anything, write:
-
-- **For** <who, specifically> **who** <the need or the frustration>, **<name> is** <the category> **that** <the one thing it does differently>.
-- **Unlike** <the real alternative, including "do it yourself"> **it** <the difference that matters to the buyer>.
-
-If these two lines cannot be written, the brief is missing the facts the name depends on. Ask for them (one round) instead of naming in the dark.
-
-## 2. Naming
-
-**Skip rule.** Sites for a person, a practice or a founder-named business (portfolios, studios named after people, clinics) use the person's name. If the name is unknown, use a placeholder, record it under ASSUMPTIONS in STRUQ.md, skip this section and go straight to the wordmark (§3).
-
-### Territories
-
-Generate across all four, three to four candidates each, so the shortlist is a real choice and not twelve variations of one idea:
-
-| Territory | What it is | Strength | Risk |
-|---|---|---|---|
-| **Descriptive** | Says what it does (a real word or two) | Instantly clear, good for local services | Hard to own, hard to trademark |
-| **Evocative** | A real word that carries the feeling or the metaphor from the concept | Memorable, ownable, carries the motif | Needs the site to explain it |
-| **Invented** | A coined word built from meaningful roots or sounds | Fully ownable, domain-friendly | Empty until the brand fills it |
-| **Founder or place** | A surname, a street, a landmark, a region | Credible, personal, honest | Hard to sell later |
-
-### The filter
-
-Score every candidate, drop anything that fails a hard rule:
-
-- **Hard:** easy to say on first sight, easy to spell after hearing it once, no obvious clash with a major brand in the same category, no unfortunate meaning in the client's main languages.
-- **Soft (rank by):** one or two syllables beats three; a distinctive first letter; works as a wordmark (letter shapes with character, no awkward pairs); a plausible domain or handle pattern (`name.com`, `getname.com`, `name.studio`, the country TLD).
-
-**You cannot verify trademarks or domain availability.** Say so plainly next to the shortlist and tell the user what to check before committing.
-
-### The deliverable
-
-A shortlist of five with one line each (territory, why it fits the positioning, the risk), and one recommendation with the reason. Write it to `brand/NAMING.md`. In a non-interactive run, take the recommendation and record it under ASSUMPTIONS.
-
-## 3. The wordmark
-
-The wordmark is the name set in type, then drawn into something ownable. Start from the **display face chosen in the SYSTEM phase** ([typography.md](typography.md)), so the logo and the headlines are one family of shapes.
-
-1. Set the name in the display face at the weight the site uses (light, 300 to 400) and one step heavier. Pick the one that holds at 24px tall.
-2. Tune it as a logo, not as text: tracking a little tighter than headline tracking, kern every pair by eye, decide on case (lowercase reads friendly, caps read institutional, title case reads like a person's name).
-3. Make **one** deliberate modification. That single change turns a font into a logo: a cut terminal, a joined pair (ligature), a letter replaced by the mark, a counter filled, a stroke extended into a line that the site's motif can continue. Never more than one.
-4. Convert to outlines, so the logo does not depend on the font loading:
-
-```bash
-npm i -D opentype.js
-```
-
-```js
-// scripts/wordmark.mjs:
-//   node scripts/wordmark.mjs "Name" path/to/Display-Light.ttf -0.02 > brand/logo.svg
-// Third argument: tracking in em (the tuned value from step 2). Default -0.02.
-import { readFile } from "node:fs/promises";
-import opentype from "opentype.js";
-
-const [text, fontPath, trackingEm = "-0.02"] = process.argv.slice(2);
-// Newer opentype.js majors removed load(); parse() works on every version.
-const font = opentype.parse(await readFile(fontPath));
-const escapeAttr = (s) =>
-  s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
-const size = 100;
-const tracking = Number(trackingEm) * size;
-
-// One glyph per character, no shaping: font.stringToGlyphs() runs the ccmp feature
-// and throws on GSUB lookups opentype.js does not support yet (seen on variable fonts).
-const glyphs = Array.from(text, (ch) => font.charToGlyph(ch));
-if (glyphs.some((g) => g.index === 0)) console.error("warning: a character is missing from the font");
-
-let x = 0;
-const parts = [];
-const box = { x1: Infinity, y1: Infinity, x2: -Infinity, y2: -Infinity };
-glyphs.forEach((glyph, i) => {
-  const path = glyph.getPath(x, 0, size); // baseline at y = 0
-  const b = path.getBoundingBox();
-  if (!b.isEmpty()) {
-    box.x1 = Math.min(box.x1, b.x1); box.y1 = Math.min(box.y1, b.y1);
-    box.x2 = Math.max(box.x2, b.x2); box.y2 = Math.max(box.y2, b.y2);
-  }
-  parts.push(path.toPathData(2)); // a number keeps y unflipped
-  const kern = glyphs[i + 1] ? font.getKerningValue(glyph, glyphs[i + 1]) : 0;
-  x += ((glyph.advanceWidth + kern) / font.unitsPerEm) * size + tracking;
-});
-
-// The viewBox hugs the ink, descenders included, so the logo aligns by its real edges.
-const vx = Math.floor(box.x1), vy = Math.floor(box.y1);
-const vw = Math.ceil(box.x2) - vx, vh = Math.ceil(box.y2) - vy;
-console.log(
-  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${vx} ${vy} ${vw} ${vh}" fill="currentColor" role="img" aria-label="${escapeAttr(text)}"><path d="${parts.join(" ")}"/></svg>`
-);
-```
-
-Use a **static** file of the chosen weight. A variable file outlines its default instance, usually 400, not the light weight the site uses. The reliable source an agent can fetch without downloading archives is Fontsource on npm, which ships one static file per weight, including for families Google serves as variable only (Sora, for one): `npm i -D @fontsource/<family>`, then use `node_modules/@fontsource/<family>/files/<family>-latin-300-normal.woff`. opentype.js parses WOFF (not WOFF2), and `next/og` reads the same WOFF ([seo.md](seo.md) §3), so copy it once to `assets/fonts/` (outside `public/`) and point both scripts at it. A static TTF or OTF from the foundry works the same way. The script applies the font's own pair kerning plus your tracking; for a hand-kerned result, export each glyph as its own `<path>` and adjust `x` per pair, or finish the outline in a vector editor. Apply the one modification from step 3 on the outlined paths.
-
-5. Use `fill="currentColor"`, so the logo takes the ink color in light and dark surfaces without a second file.
-6. **Test the modification at nav size** (about 1.25 to 1.5rem tall). A thin full-width rule under a word reads as a link underline there, and a cut terminal can vanish. If it fails at nav size, make it thicker, shorter or part of a letter. The modification goes into the SVG as its own element after the outlined path (a `<rect>`, a `<path>`), so it can be tuned without re-outlining.
-
-## 4. The mark
-
-The mark is the logo reduced to one shape that works at 16px: the favicon, the loader, the menu button, the social avatar. Draw it as SVG by construction, never by freehand path guessing:
-
-- **Monogram:** the first letter from the wordmark outlines, with the same modification, sitting in a deliberate bounding shape (or none).
-- **Symbol:** built from the concept's motif with primitives (`circle`, `rect`, `line`, arcs) on a 24 or 48 unit grid. Whole or half units only. One stroke weight or one fill, never both.
-- **Test** at 16, 32 and 512px, on the darkest and lightest surface in the palette. If it turns to mush at 16px, simplify.
-
-Build it so it can move. Strokes (not fills) can be drawn on with DrawSVG for the `draw-mark-loader`; a mark built from the same number of points as a second shape can morph into it for `logo-morph` ([svg-motion.md](svg-motion.md), [showcase.md](showcase.md)).
-
-## 5. The file set
-
-Write these, wired into the framework's conventions (Next.js App Router shown):
-
-| File | What |
-|---|---|
-| `brand/logo.svg` | Wordmark, outlined, `currentColor` |
-| `brand/mark.svg` | Mark, outlined, `currentColor` |
-| `components/brand/Logo.tsx` | Both inlined as components with a `title` for accessibility, so they can animate and take color |
-| `app/icon.svg` | The mark on a solid surface tile; check it at 16px |
-| `app/apple-icon.png` | 180 by 180, the mark on the surface color with padding |
-| `app/opengraph-image.tsx` | Owned by [seo.md](seo.md) §3, and built in the SEO workflow step once the routes exist. The brand supplies the wordmark, surface color and display face it uses. |
-
-Vite: the same SVGs in `public/` and `<link rel="icon" type="image/svg+xml">`; the static OG PNGs are covered in [seo.md](seo.md) §7.
-
-## 6. Voice
-
-One line in STRUQ.md that every piece of copy is checked against: register, sentence length, what it never does. For example: "plain and certain; short sentences; numbers instead of adjectives; never exclamation marks, never 'unlock' or 'elevate'." The copy rules in [page-architecture.md](page-architecture.md) §5 apply on top.
-
-## Tells
-
-- A name chosen before the positioning exists
-- Twelve candidates that are one idea in twelve spellings
-- A wordmark in a different family from the site's display face, for no reason
-- Three modifications on one wordmark
-- A mark that is a generic icon (a leaf, a lightbulb, a rocket, an abstract swoosh, a hexagon network)
-- A gradient logo, a logo that only works on one background
-- A favicon that is the full wordmark at 16px
-- Claiming a name is "available" without having checked