@damiangilgonzalez/harness 1.3.7

package/skills/tastemaker/references/animation-guidelines.md

@@ -0,0 +1,252 @@
+# Motion
+
+Animation is one of the fastest ways to make a UI feel expensive or cheap. The rule that separates the two: **motion should clarify, not decorate.** Every animation should answer "what changed", "where did this come from", or "did the interface hear me?" If movement cannot answer one of those, delete it.
+
+## Motion decision gate
+
+Run this gate before writing animation code.
+
+| Question | Ship motion when | Delete or reduce when |
+|---|---|---|
+| How often will users see it? | Occasional, rare, first-run, or explanatory moments | Keyboard actions, command palettes, core navigation, dense lists, and anything seen dozens of times per day |
+| What purpose does it serve? | Feedback, spatial consistency, state indication, explanation, or preventing a jarring change | The only answer is "it looks cool" |
+| Can it stay within budget? | UI motion stays under 300ms, with smaller pieces under 200ms | The effect needs slow showmanship to work |
+| Does it help the task? | It makes state, hierarchy, or progress clearer | It moves data the user is trying to read or act on |
+
+High-frequency UI should feel instant. Rare moments can carry more personality. A daily-use dashboard often needs less motion than a launch page.
+
+## GSAP is the default motion engine
+
+A static-looking site is one of the fastest ways a generated UI reads as a template rather than a real product. **GSAP + ScrollTrigger is the default for Tastemaker marketing pages** because it handles scroll-driven reveals, staggered entrances, and timeline-sequenced hero moments cleanly. For app shells, use GSAP without ScrollTrigger, CSS transitions, or a motion library that matches the stack.
+
+Install it per `references/tech-stack-guides.md`, then wire up `assets/gsap-starter.js`:
+
+```html
+<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/ScrollTrigger.min.js"></script>
+<script src="gsap-starter.js"></script>
+<script>
+  TastemakerMotion.init({
+    duration: 0.22,
+    distance: 16,
+    ease: "power3.out",
+    staggerStep: 0.06,
+  });
+</script>
+```
+
+```html
+<div data-reveal>Fades/rises in on scroll</div>
+<div data-reveal data-reveal-group>
+  <div>Child 1</div>
+  <div>Child 2</div>
+</div>
+```
+
+`gsap-starter.js` uses `gsap.matchMedia()` for reduced motion. The fallback pair, `assets/reveal.css` and `assets/reveal.js`, uses the same `data-reveal` markup and exists for constrained contexts that cannot load GSAP.
+
+## Exact curves and durations
+
+Use these as CSS tokens unless the project lock has stricter values:
+
+```css
+:root {
+  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
+  --duration-press: 120ms;
+  --duration-popover: 180ms;
+  --duration-panel: 240ms;
+}
+```
+
+| Element | Duration | Easing |
+|---|---:|---|
+| Button press | 100-160ms | `var(--ease-out)` |
+| Tooltip or small popover | 125-200ms | `var(--ease-out)` |
+| Dropdown or select | 150-250ms | `var(--ease-out)` |
+| Modal or drawer | 200-500ms | `var(--ease-drawer)` for sheets, `var(--ease-out)` for centered modals |
+| On-screen movement or morph | 180-300ms | `var(--ease-in-out)` |
+| Scroll storytelling | as needed | `power3.out` or a scrubbed timeline |
+
+Avoid `ease-in` for UI. It starts slow at the exact moment the user expects a response.
+
+## anime.js — a scoped alternative, not a GSAP replacement
+
+GSAP stays the default for every project (above). anime.js was evaluated as a second option — a real side-by-side test (bundle weight measured directly, the reveal/reduced-motion pattern hand-built and run in a browser, not assumed from docs) found it's not a better general-purpose default, but it does have two genuine, narrow use cases where it's the better tool:
+
+1. **A page that needs both scroll-reveals and SVG motion-path/shape-morphing for constructed logo marks or hand-built illustrations** (`references/logo-sourcing.md`). Measured directly via each library's current CDN "latest" tag, the same one this repo's own install snippets point at: anime.js v4's full bundle — animation engine, ScrollObserver, Draggable, spring physics, *and* the SVG toolset (`svg.morphTo`, `svg.createMotionPath`, `svg.createDrawable`), everything included — is **~118KB minified / ~41KB gzipped**. Matching that same feature set in GSAP means core + ScrollTrigger + Draggable + MorphSVGPlugin + DrawSVGPlugin, which comes to **~179KB minified / ~69KB gzipped** — genuinely, verifiably larger (~34% more over the wire, gzipped). For a page whose brief calls for both scroll storytelling *and* a morphing/drawing SVG mark, anime.js's single bundle is the lighter way to get both.
+2. **SVG motion-path/shape-morphing alone, on a page that otherwise doesn't need scroll-triggered motion.** Same tools, same reasoning as above, just without the reveal engine attached — reach for anime.js's SVG toolset directly rather than adding two more GSAP plugin files for one moment on the page.
+
+**Bundle size alone does not justify anime.js for simple reveals with no SVG need — this was checked and doesn't hold up.** The obvious-sounding case ("anime.js is lighter, use it for basic scroll-reveals") was tested and rejected: loaded via a plain `<script>` CDN tag (this project's default, no-build-step pattern), anime.js's bundle is **~118KB min / ~41KB gzip** against GSAP core + ScrollTrigger's **~117KB min / ~46KB gzip** — a wash on minified size, and only a modest ~11% gzip difference, because a plain script tag can't tree-shake away the Draggable/spring/SVG code a reveal-only page never uses. (A project actually using a bundler with anime.js's ESM submodule exports could tree-shake further, but that's a different build setup than the CDN-tag default this skill assumes — not a reason to switch the default.) Reach for anime.js on bundle-size grounds *only* when the SVG toolset is also genuinely needed, per the two cases above.
+
+**Everything else stays on GSAP.** The reasoning that ruled out a full swap: this project has a real, working, tested investment in GSAP already (`assets/gsap-starter.js`, the `data-reveal` convention, the App-shell/marketing motion-track split, `gsap.matchMedia()` as the reduced-motion backbone) — porting all of that gets no payoff for the standard case, since what actually makes a page feel premium is choreography and restraint, not which engine executes the tween. anime.js's `createScope({ mediaQueries })` is a real, working equivalent to `gsap.matchMedia()` — verified, not assumed — so reduced-motion support isn't a blocker where anime.js *is* used. Spring-based draggable micro-interactions (a real gap in current App-shell motion guidance) were identified as a plausible third use case but not built into a starter yet — flagged as open follow-up work, not silently dropped.
+
+If a project's brief calls for anime.js under either scoped case, use `assets/anime-starter.js` — it mirrors `gsap-starter.js`'s `[data-reveal]`/`[data-reveal-group]` convention so a project can use either engine without touching markup. Two real porting gotchas found by hands-on testing, not by reading docs:
+
+- **Scroll-threshold syntax does not carry over from GSAP.** GSAP's `"top 85%"` string means nothing to anime.js's `ScrollObserver` — it silently matches nothing and the element never reveals. anime.js's own syntax (position keywords `top`/`bottom`/`start`/`end`, on both target and container) is different enough that copying a GSAP trigger string is a real, silent failure mode. Use the library's own defaults unless a specific threshold is actually needed.
+- **No automatic on-creation visibility check.** GSAP's `ScrollTrigger` checks whether a target is already in view at creation and fires immediately if so. anime.js's `ScrollObserver` only fires `onEnter` on an actual scroll-crossing transition — left alone, anything already above the fold (a hero's own `[data-reveal]` group) sits invisible until the user's first scroll. `anime-starter.js` fixes this by calling each observer's own `handleScroll()` once right after wiring it; any bespoke anime.js scroll animation needs the same explicit initial check.
+
+## Motion (motion.dev) — the React-component engine, and the one that also works build-free
+
+GSAP stays the default for this skill's own page-level motion (above). Motion — formerly Framer Motion — is the right engine in two specific situations, and `references/library-selection.md` already names the first:
+
+1. **React projects where components need springs, layout animation, exit animation (`AnimatePresence`), or gesture-driven values.** GSAP can do most of this, but Motion's component model fits React's lifecycle without the manual cleanup that ScrollTrigger instances demand in `useEffect`.
+2. **A component pulled from a registry that already ships with Motion** (`references/component-sourcing.md`). Don't rip out its animation layer to redo it in GSAP — retune its durations/easings to the lock's Motion values instead, and note that the project now carries Motion.
+
+Install: `npm install motion`. It also loads with **no build step**, which matters for this skill's plain-HTML default:
+
+```html
+<script type="module">
+  import { animate, scroll, inView, stagger } from "https://cdn.jsdelivr.net/npm/motion@12/+esm"
+</script>
+```
+
+Pin the major version rather than `@latest` in anything shipped — Motion's own docs say this explicitly.
+
+Verified API shapes:
+
+```js
+animate(el, { scale: [0.4, 1] }, { ease: "circInOut", duration: 1.2 })
+animate(el, { rotate: 90 }, { type: "spring", stiffness: 300 })
+animate("li", { y: 0, opacity: 1 }, { delay: stagger(0.1) })
+inView("section", () => animate("section", { opacity: [0, 1] }))
+
+// scroll-linked: build the animation, then hand it to scroll()
+const a = animate("div", { transform: ["none", "rotate(90deg)"] }, { ease: "linear" })
+scroll(a, { target: document.getElementById("item"), offset: ["start end", "end start"] })
+```
+
+**One engine per project.** Never load GSAP and Motion together to get one effect from each — the only acceptable reason for both is a pulled component that brought its own, and that should be stated rather than left for the next person to discover. Motion's docs don't document a `prefers-reduced-motion` helper for `scroll()`, so gate it yourself with `matchMedia("(prefers-reduced-motion: reduce)")` and render the end state directly, the same contract `gsap.matchMedia()` gives on the default track.
+
+## Scroll storytelling — for landing/marketing pages that should unfold as you scroll
+
+`gsap-starter.js` covers the baseline (things fade/rise in on scroll). A *storytelling* page goes further: it uses scroll position as a timeline, so scrolling feels like advancing through a narrative rather than paging past static blocks. This is what makes a landing page feel crafted rather than assembled. Build these directly with ScrollTrigger (they're page-specific, so they live in the project, not in the shared starter):
+
+- **Scrubbed reveals** (`scrub: true`) tie an animation's progress to scroll position, so an element draws/moves *as* the user scrolls rather than firing once. Great for a hero visual that assembles, a number that counts up, a path that draws.
+- **Pinned sections** (`pin: true`) hold a section in place while its content advances through steps — the classic "one sticky panel, content changes as you scroll" storytelling beat. Use sparingly (one, maybe two per page); pinning everything is disorienting.
+- **Sequenced hero timeline**: a `gsap.timeline()` on load with at most four coherent beats — context/navigation → headline → subhead + actions → the single proof visual. Animate the visual as one composition rather than staggering all its internal labels. This preserves the hierarchy established in `references/hero-guidelines.md` instead of making every element ask for attention.
+- **Parallax depth**: move background/foreground layers at slightly different scroll rates (small `y` offsets tied to scroll) for a sense of depth — subtle is the whole game; large offsets read as a gimmick.
+
+Keep it coherent with the locked motion feel (`.tastemaker/style-lock.md`): a "premium/confident" project storytells with restraint (slow, smooth, minimal), a "playful" one can be more energetic. And every one of these must degrade under `prefers-reduced-motion` — wrap them in the same `gsap.matchMedia()` pattern `gsap-starter.js` uses, showing the end state without the scroll-driven motion.
+
+## App shell motion — for internal tools, dashboards, and anything that isn't a scroll narrative
+
+The scroll-storytelling track above is the right model for a page the user scrolls through once, top to bottom. It is close to meaningless for a sidebar-plus-topbar internal tool: most of the screen loads once and stays in place while the user works, there is no scroll narrative to tell, and a scrubbed hero reveal or a pinned section has nothing to attach to. Motion is still not optional here (per this file's own "motion should clarify, not decorate" rule), it just answers different questions: what changed, what's about to happen, is this still loading.
+
+- **Panel/tab switches**: a short cross-fade or directional slide (8-12px translate + opacity) tied to the navigation direction, so moving forward and back through the app reads consistently rather than a generic fade every time. Ties to the "page/state transitions" rule below.
+- **List/table entrances**: when a view first populates, stagger rows/cards in with the same `data-reveal`/`data-reveal-group` convention `gsap-starter.js` already provides, just triggered on data-load instead of on scroll-into-view, rather than letting the whole table snap into existence at once.
+- **State changes**: a KPI ticking to a new value, a status badge changing, a row being added or removed, a field validating. Animate the specific thing that changed, not the surrounding layout. This is what "what changed" from the top of this file actually looks like in an app shell.
+- **Loading states, promoted to first-class**: skeleton screens that mirror the real layout, not a generic spinner. This used to be a single bullet under the marketing-oriented guidance below; it earns the promotion because it is the motion moment most internal tools actually need right, and it is a genuinely different problem from a scroll reveal.
+- **Draggable, spring-based micro-interactions**: a draggable panel with snap points, a reorderable list row, a snap-to-position control — physics-based release motion reads as more tactile than an eased tween for anything the user directly manipulates with a pointer. See the dedicated section below for which engine and how.
+
+None of this needs ScrollTrigger. `gsap.to()`/`gsap.from()` with the same duration and easing recorded in `.tastemaker/style-lock.md`'s Motion section is enough, wired reduced-motion-aware the same way as everything else in this file.
+
+### Draggable interactions: use whichever engine the project is already on
+
+Evaluated GSAP's `Draggable` + `InertiaPlugin` against anime.js's `createDraggable` + `createSpring` for this specific case — a draggable panel with snap points — the same rigor the original GSAP-vs-anime.js evaluation used (`references/animation-guidelines.md`'s anime.js section above). The finding here is the same shape as that one, for the same underlying reason: **bundle size is a wash between the two options on their own** (GSAP core + `Draggable` + `InertiaPlugin` measures ~116KB minified / ~44KB gzipped; anime.js's full bundle, which already includes its draggable and spring tools, measures ~118KB minified / ~41KB gzipped) — so it is never worth loading a *second* motion engine just to get draggable support. Extend whichever engine the project is already using:
+
+- **GSAP-track projects (the default)**: `Draggable.create(target, { type: "x" | "y" | "x,y", bounds: containerSelector, inertia: true, snap: [...points], onDragEnd })`. `InertiaPlugin` is what makes the release feel like it has real momentum instead of stopping dead where the pointer let go — it's free (see the GSAP-is-the-default section above), so there's no reason to skip it once `Draggable` is in use.
+- **anime.js-track projects** (per this file's anime.js section — a page already using anime.js for SVG motion-path/shape-morphing): `anime.createDraggable(target, { x: true, snap: [...points], releaseMass, releaseStiffness, releaseDamping, onSnap })`. `releaseMass`/`releaseStiffness`/`releaseDamping` are anime.js's spring-physics equivalent of `InertiaPlugin` — tune stiffness/damping together (higher damping relative to stiffness settles faster with less overshoot) rather than reaching for `InertiaPlugin`'s more velocity-based feel; they're different physical models, not drop-in equivalents of each other.
+
+**The drag-follow itself is never gated by `prefers-reduced-motion`** — it's direct manipulation tracking the user's own pointer 1:1, not decorative or autoplaying motion, so reduced-motion doesn't apply to it any more than it applies to scrolling itself. What *does* need a reduced-motion branch is the **release/snap settle** — the bouncy, physics-driven motion after the user lets go. Branch it the same way every other animation in this file does (`gsap.matchMedia()` / anime.js's `createScope({ mediaQueries })`): a lower-damping, more visibly springy settle by default, and a critically-damped or near-instant snap (no overshoot) under `prefers-reduced-motion: reduce` — overshoot on release is exactly the kind of motion that reads as uncomfortable for vestibular sensitivity, even though the drag itself is user-initiated.
+
+**Which track applies is a per-screen decision, not a per-project one.** A marketing/landing page uses scroll storytelling; a dashboard, settings screen, or any persistent app shell uses this track instead. A single project can need both (a public landing page plus an authenticated app behind it), in which case each screen gets the track that actually fits it rather than one default applied everywhere. See `SKILL.md` Step 4 for where this branch happens in the build.
+
+## What to animate, and how much
+
+- **Entrances** (page load, scroll-into-view): a small, consistent fade + upward translate (8-16px) is almost always right. Bouncy easing, large distances, or rotation on entrance reads as playful/consumer — only use it if the locked mood (`.tastemaker/style-lock.md`) actually calls for playful. A "premium/confident" project should use a quick, restrained fade (150-250ms, ease-out), not a bounce.
+- **Hover/focus states**: fast (100-150ms), subtle (a slight scale, a border/background shift, a shadow lift) — the point is to confirm interactivity, not to perform. Anything longer than ~200ms on hover starts to feel laggy rather than smooth.
+- **Loading states**: skeleton screens that mirror the actual layout beat a generic spinner — they set an expectation of what's coming, which is what makes a wait feel shorter. See the App shell motion section above for this promoted to a first-class pattern, not an afterthought.
+- **Page/state transitions**: keep direction consistent (things that mean "forward" always animate the same way) — inconsistent transition direction is disorienting even when each individual transition looks fine in isolation.
+
+## Performance rule, non-negotiable regardless of style
+
+Animate only `transform` and `opacity`. Anything that animates `width`, `height`, `top`/`left`, or box-shadow spread triggers layout recalculation on every frame and will visibly stutter on anything but a high-end device — this is true no matter how good the animation curve is conceptually.
+
+## Physicality rules
+
+- Pressable elements respond on pointer down. Default: `transform: scale(0.97)` and `transition: transform 120ms var(--ease-out)`.
+- Do not animate from `scale(0)`. Start from `scale(0.95)` plus `opacity: 0`.
+- Trigger-anchored popovers, menus, and tooltips scale from their trigger. Use `transform-origin: var(--transform-origin)` when the primitive exposes it.
+- Modals stay centered. `transform-origin: center` is correct for a modal.
+- Enter and exit along the same path. A toast that enters from the top exits to the top.
+- Use percentages for off-screen travel when size varies. `translateY(100%)` means the element's own height.
+- Add a subtle `filter: blur(2px)` only when a crossfade visibly double-exposes two states. Keep blur under `20px`.
+
+## Gesture and spring rules
+
+Use springs for drag, swipe, interruptible layout changes, and any object the user can grab mid-motion. Start with a critically damped feel: no bounce for standard UI, slight bounce only when a gesture carries momentum.
+
+Recommended Motion spring defaults:
+
+```js
+// Standard UI, no overshoot
+{ type: "spring", duration: 0.4, bounce: 0 }
+
+// Momentum-driven gesture release
+{ type: "spring", duration: 0.4, bounce: 0.2 }
+```
+
+Gesture details:
+
+- Respond on pointer down, commit on pointer up.
+- Use Pointer Events and `setPointerCapture`.
+- Respect where the user grabbed the object. Do not snap the object center to the pointer.
+- Track release velocity and hand it to the spring.
+- Use soft resistance at boundaries instead of hard stops.
+
+## Performance rule
+
+Animate only `transform` and `opacity`. Anything that animates `width`, `height`, `margin`, `padding`, `top`, `left`, or box-shadow spread risks layout and paint work every frame.
+
+Also avoid `transition: all`. Name the properties. If a React app uses Motion for animations under load, prefer a full `transform` string over separate `x`, `y`, or `scale` shorthands when frame rate matters.
+
+## Accessibility
+
+Every animation must respect reduced motion. Reduced motion means gentler feedback, not a dead interface: keep opacity/color changes that aid comprehension and drop slides, springs, parallax, and large movement.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .sheet {
+    transition: opacity 200ms ease;
+    transform: none !important;
+  }
+}
+
+@media (hover: hover) and (pointer: fine) {
+  .button:hover {
+    transform: translateY(-1px);
+  }
+}
+```
+
+If a design uses translucent surfaces, also handle `prefers-reduced-transparency` and `prefers-contrast: more` by increasing opacity, dropping blur, and adding clearer borders.
+
+## Locking motion per project
+
+Once a project settles on a motion feel, record it in `.tastemaker/style-lock.md`:
+
+- Feel: quick and restrained, soft and bouncy, crisp and operational, or another concrete phrase.
+- Curves: exact cubic-bezier or library spring values.
+- Durations: press, popover, panel, page/story.
+- Distance: reveal and panel travel.
+- Frequency rules: where to delete or reduce motion for this project.
+
+Motion inconsistency is as visible as color inconsistency, just harder to name.
+
+## Motion review before delivery
+
+Run:
+
+```bash
+python3 scripts/audit_motion.py site assets references
+```
+
+Then do a human feel pass:
+
+- Slow key animations to 25% speed in DevTools or by temporarily multiplying durations.
+- Check origin: popovers grow from triggers, modals from center.
+- Spam toggles, tabs, and toasts. Motion should retarget, not restart from zero.
+- Toggle reduced motion. Movement drops, but state feedback remains.
+- Test mobile hover behavior. Touch should not trigger pointer-only hover motion.

package/skills/tastemaker/references/anti-slop-checklist.md

@@ -0,0 +1,118 @@
+# Anti-slop gates + pre-emit self-critique
+
+Two checks stand between a build and handoff: a **pre-emit self-critique** (run *before* you finalize, to catch weakness while it's cheap to fix) and the **numbered gate list** (run *after* build, as a precise sweep). These are the specific, recognizable tells that make output read as AI-generated regardless of how good the underlying tokens were — catching them is often higher-leverage than getting the palette exactly right.
+
+---
+
+## Pre-emit self-critique (run before you finalize)
+
+Before handing anything back, score the planned output **1-5 on each of six axes**. Anything **< 3 on any axis triggers a revision pass** before the gate sweep — don't carry a known weakness into a 50-gate review. Two passes is normal; a third is usually a sign the *brief* is underspecified, not the design — re-read it.
+
+| Axis | What you're scoring |
+|---|---|
+| **Show-don't-tell** | Is each section mostly something to *look at* (mockup, chart, comparison, illustration, real photo) with text as caption — or mostly prose with a decorative icon? This is tastemaker's top principle; score it first. |
+| **Philosophy** | Is there a clear *why* — a position this design takes, a reason it looks like *this* — or is it just a competent layout? |
+| **Hierarchy** | Can a viewer tell, in 2 seconds, what's primary, secondary, tertiary? Or is everything the same weight? |
+| **Specificity** | Does this look like *this* product/brief — or like a generic page that could be anyone's, just in different colors? |
+| **Restraint** | Has everything that isn't earning its place been removed — decoration, redundancy, padding-for-padding's-sake, motion that carries no information? |
+| **Variety** | Does this share a structural fingerprint (macrostructure, nav/footer/hero archetype) with a previous build in this project? Score by *structural* distance — a palette swap doesn't count as variety. See `references/diversification.md`. |
+
+Record the six scores in the build's CSS stamp so a later run can see them: `/* tastemaker · critique: ShowTell 5 · Phil 4 · Hier 5 · Spec 4 · Restr 5 · Var 5 */`.
+
+---
+
+## The gate list (run after build)
+
+Run through these before handing back any generated UI. Every answer must land on the safe side. **Gates are universal unless a *Mood note* scopes them** — tastemaker's five moods are premium, warm, technical, playful, elegant (from `references/style-tokens.md`). A mood note loosens or tightens a gate for a specific mood; where there's no note, the gate binds every mood.
+
+Run the static scanner before the manual sweep:
+
+```bash
+python3 scripts/anti_slop_scan.py <changed-ui-paths>
+```
+
+The scanner catches high-confidence source tells: generic purple/cyan gradients, gradient text, `h-screen`, dead links, missing alt text, placeholder copy, AI-copy phrases, emoji icons, repeated eyebrow labels, and `transition-all`. Fix HIGH findings. For MEDIUM findings, either fix them or record why the brief earned the exception. The scanner is a floor, not the full review; the gates below still decide the work.
+
+### Show, don't tell & structure
+
+1. **Shows, doesn't tell — visuals carry meaning, not paragraphs.** Go section by section: is each one mostly something to *look at* (a UI mockup, a chart, a comparison, a diagram, a numbered visual flow, a stat callout, an illustration) with text as its caption — or is it mostly prose with a decorative icon? A page where most sections are heading-plus-two-sentences-of-explanation is the text-wall failure mode, and it reads as generic even with perfect tokens. Replace explanatory paragraphs with the thing they describe: "fast analytics" → an actual chart; "simple 3-step setup" → three visual panels; "powerful editor" → a mockup of the editor. Text stays only where a visual genuinely can't carry it (headline, short subhead, caption, CTA). This is the highest-leverage anti-slop check there is — a beautiful palette on a wall of text still reads as AI slop. **A section can pass this gate technically and still fail it in spirit** — a proof/evidence section built as small label + description + tiny-icon cards floating in mostly-empty background is a card, not a paragraph, but is still too sparse to carry a proof beat. See `references/component-patterns.md`'s show-don't-tell section for the proof-specific floor: real supporting visuals (an annotated capture, a real chart, a constructed diagram), not undersized cards padded out by empty space.
+2. **Structure is a named macrostructure, not the generic template.** The page is one of `references/macrostructures.md`'s named shapes, not the reflexive hero → 3-feature-cards → testimonial → CTA → footer rhythm that reads as "an AI built this" even with a perfect palette. Within one page, no two sections use the same archetype from `references/component-catalog.md`.
+3. **Structure differs from the last build.** The build carries the CSS stamp and a `.tastemaker/log.json` entry (`references/diversification.md`), and its macrostructure + nav + footer + hero archetypes each differ from the last build's per the rotation rule. Reaching for the mood's default nav/footer on every build is the specific failure this catches.
+4. **The page follows a real narrative arc, not just a varied shape.** Per `references/narrative-arc.md`: reading the page top to bottom, can you name what each section is doing in the argument — hook, problem, solution, how it works, proof, close — or a deliberately stated variant? At least four distinct beats, five by default. This is a different failure from gates 2-3: a page can pass those (real macrostructure, differs from the last build) and still fail this one, because a well-varied *shape* with no throughline still reads as sections that don't add up to anything. Check specifically for a problem/stakes beat that's actually specific to the product, not a placeholder sentence, and a proof beat with real evidence, not an assertion.
+5. **No generic-template chrome tells.** Nav isn't the reflexive wordmark-left + inline-links + button-right minimal bar unless the page genuinely has ≤2 destinations (reach for a real product bar instead); footer isn't the reflexive 4-column Product/Company/Resources/Legal + social-row unless it's a genuine docs root; no eyebrow-left/heading-right two-column section head (stack the eyebrow above the heading); no hand-drawn fake browser/phone/IDE chrome (use a real screenshot or omit — the environment already supplies real chrome). See `references/component-catalog.md`'s cross-cutting rules.
+6. **One intentional rule-break exists.** The hardest gate, and the most important. A design where everything sits on the grid, evenly spaced and perfectly safe, reads as generated even when every token is right. Human-authored work usually has one deliberate break: an element that bleeds past its column, an oversized number, an asymmetric moment, a bit of tension or delight the system didn't require. Find the one intentional break that makes this feel made by a person. If there isn't one, the page is probably too safe.
+
+### Hero & logo
+
+7. **Hero passes the five-second and subtraction tests.** In five seconds, can a new visitor identify the product, its main value, and the primary action? Then remove every hero element that doesn't improve one of those answers. The default budget: one optional eyebrow, one headline, one short subhead, one primary CTA, at most one secondary CTA, one focused visual. Process rails, metric sidebars, floating proof badges, decorative stamps/orbits, file footers, and multiple competing mockups belong below the fold unless the product truly can't be understood without one.
+8. **Hero fits the fold and sizes to its copy.** At 1280×800, the headline, lede, and primary CTA are all visible without scrolling; the headline is sized to its word count — including under 6 words, which still caps at the same ceiling the 6-8 word band uses, never above it — and its line-height clears descenders (see `references/hero-guidelines.md`). A short headline stacking one word per line is this failure, concretely. *Mood note: elegant/premium may run a taller art-directed statement fold, but even then the first screen must read as a complete, deliberate composition, never a headline sliced by the fold.*
+9. **Hero motion preserves the hierarchy.** The entrance sequence reveals the message and focused visual in at most four coherent beats. It doesn't animate every internal label independently or use decorative motion that competes with the headline.
+10. **Hero isn't centered-everything.** The eyebrow, headline, lede, and CTA are not all stacked on one centered vertical axis — pick at most two centered elements and break alignment for the rest (eyebrow or CTA sits off-axis). *Mood note: playful and elegant-narrow may center the hero when the canvas itself is the design, but even then the eyebrow or CTA sits off-axis.*
+11. **No section headline outside the hero reaches hero scale.** Per `references/component-catalog.md`'s `S#` section-heads: a section headline caps at roughly 50-65% of the hero's full display size, and reads in 1-2 lines regardless of word count. This is a distinct failure from gate 8 — a page can pass the hero's own sizing discipline and still fail this one if a mid-page section headline independently reaches hero-scale type. The one exception is a Long-Scroll Narrative or Manifesto macrostructure's single deliberate large statement moment, stated as such — not the default treatment repeated at every section head.
+12. **Logo is a real mark, not a letter in a box.** A single letter set inside a rounded/colored square or circle is the logo equivalent of the indigo gradient — the instant "AI generated this" tell. The mark is a simple, memorable geometric symbol (or a recolored library symbol per `references/logo-sourcing.md`), recognizable at 16px, paired with a wordmark in the locked heading font — not a monospace/system letterform dropped in a colored tile.
+13. **Existing brand assets were preserved.** If the repository or brief already contained a logo/favicon/brand kit, the build reuses it unchanged unless the user explicitly requested a rebrand. Visual mismatch is a styling problem, not automatic permission to replace a distributed identity.
+
+### Color & contrast
+
+14. **Not the default gradient.** Indigo-to-purple (or blue-to-cyan) diagonal gradients on hero sections/buttons are the single most recognizable "AI made this" signal — including a `background-clip: text` gradient headline, which no mood allows. If the locked style didn't call for a gradient, don't add one out of habit.
+15. **Contrast checked for every pairing used, not just body-on-background.** Body text vs. its background hits 4.5:1 (WCAG AA), verified against the real hex values. But that's not enough: check the palette *as used*. Run `scripts/check_contrast.py --matrix ...` to get the legal-pairings set, and confirm every pairing the build actually introduced (a badge fill with its label, a disabled state, a hover, a state-carrying border) is in the text-safe or UI-safe list for its purpose. A palette color used as a fill with white text is the classic miss: it can pass body-on-background and still be illegible as a button. See `references/style-lock-format.md`'s Color contract. Purely decorative hairline borders are exempt from the 3:1 floor; a border that's the only thing conveying state is not.
+16. **The contrast failures that ship most often.** Fail on any: **button text ≈ button fill** (text color and fill within ~5% lightness in OKLCH — the black-on-black bug where the model forgot the on-fill color); **a dark section left with ink-on-ink** (any panel with OKLCH lightness < 50% must also swap its text to a light color in the same rule, and nested children must inherit it); **an accent used as a text-bearing fill with no verified on-accent color**. These are the real-world failures a single body-on-bg check misses.
+17. **Neutrals are tinted toward the anchor hue, not flat grey.** Pure `oklch(... 0 ...)` neutrals read as flat and disconnected from the palette. *Mood note: technical (and any deliberately monochrome/minimal build) may use zero-chroma neutrals — the Stripe/Linear school; every other mood tints neutrals toward the anchor hue.*
+18. **Accent stays an accent (~≤5% of any viewport).** If the accent covers more than ~5% of a screen by area (solid fills, large accent headings, full-bleed accent bands), retreat — accent is for emphasis, not filling. *Mood note: playful may run a higher accent footprint when the color energy is the point.*
+19. **Nothing contradicts the "Do not" list** in `.tastemaker/style-lock.md`, if the project has accumulated specific rejections.
+
+### Spacing & layout
+
+20. **Spacing follows the scale, and internal padding never exceeds external gaps.** Per `references/style-tokens.md`'s Spacing scale: content cards (pricing tiers, feature cards, testimonials) have a real internal-padding floor (`space-6`/24px). Check the relationship, not just raw numbers: a card's internal padding ≤ the gap between it and its neighbors — if padding is *larger* than the space around it, the layout reads as cramped inside and empty outside at once. Every gap/margin/padding value is on the named scale; an arbitrary `padding: 17px` is a tell.
+21. **Two-column sections have a deliberate column-balance treatment.** If one column (a headline block) is visibly taller than the other (a card stack, a short label list), it was vertically centered, filled with a real supporting element, or capped to match — not left to trail into empty space. A pricing section with three cards clustered at the top and dead space beneath them is this failure, concretely. See `references/component-patterns.md`'s Column balance section.
+22. **Section-to-section separation is one consistent mechanism.** Every section boundary uses the same treatment (alternating tint, hairline divider, or fixed padding alone) recorded in the style lock — a page that mixes them boundary to boundary reads as unplanned.
+23. **On a landing page, section padding is generous enough that each section reads as its own moment — not capped at a uniform, cramped value.** Check the actual numbers, not a vague impression: a pivotal section (hero, primary proof/demo) should be padded in the `space-32`–`space-48` (128–192px per side) range, and the combined gap between two adjacent sections should read as roughly 120–250px on desktop. See `references/style-tokens.md`'s Section-level padding section. This is a distinct failure from gate 22 (mechanism consistency) — a page can use one consistent separation mechanism and still fail this gate if that mechanism is applied at a cramped value everywhere. Does not apply to app-shell screens, which stay dense per the density guidance in `references/component-patterns.md`.
+24. **Density matches the mood.** A premium/confident project shouldn't be cramped and cluttered; a dense/information-heavy dashboard shouldn't have so much whitespace that scanning takes longer than it should.
+25. **No horizontal scroll at any width 320-1920px.** `overflow-x: clip` (not `hidden`, which breaks `position: sticky`) on both `html` and `body`; any `grid-template-columns` track holding an image uses `minmax(0, 1fr)`, never bare `1fr` (bare `1fr` takes the image's intrinsic width as its floor and blows past the viewport on phones); display headers set `overflow-wrap: anywhere; min-width: 0` so long compound words break instead of overflowing.
+26. **No two-line clickable text.** No button label, primary nav link, footer link, tab label, breadcrumb, or CTA wraps to two lines at any width 320-1920px — it reads as a styling error, not intent. Fix by shortening the label, `white-space: nowrap` + parent reflow, or collapsing the nav into a menu. Hit targets ≥44×44px below 40rem.
+
+### Motion & microinteractions
+
+27. **Not static.** GSAP + ScrollTrigger (`assets/gsap-starter.js`) is wired for scroll-reveal, staggered entrances, and hover/press feedback — a finished page with zero motion is a skipped step, not a minimalist choice. Check for it explicitly. (App-shell screens get the App-shell motion track instead of a scroll timeline — see `references/animation-guidelines.md`.)
+28. **No `transition: all`.** Name the specific properties that transition. `transition: all` animates layout and paint properties you didn't intend and is a reliable tell.
+29. **Animate only `transform` and `opacity`.** Never animate `width`, `height`, `top`, `left`, `margin`, or `padding` (they trigger layout on every frame). Motion that needs to move something uses `transform`.
+30. **No uniform hover-scale, no stacked hover effects, no bouncy easing on UI state.** No `hover:scale-105` applied across unrelated elements; no single element carrying translate + scale + shadow + color at once; no overshoot/bounce easing (`cubic-bezier(0.34, 1.56, …)`) on buttons/modals/tooltips — reserve overshoot for genuinely physical interactions. Use the named easings, not the browser default `ease`.
+31. **Focus ring appears instantly and is visible.** Every interactive element has `:focus-visible` with a ring at ≥3:1 contrast, and the ring **never** fades/transitions into existence — keyboard users need it immediately.
+32. **Every motion has a `prefers-reduced-motion: reduce` fallback.** Spatial motion collapses to a ≤150ms opacity crossfade, not nothing-and-not-full-motion. `gsap-starter.js` handles this via `matchMedia`; bespoke timelines branch the same way.
+33. **Motion carries information, and there's not too much of it.** Prefer silent success over a celebratory toast for an effect the user can already see; prefer optimistic update + Undo over a confirmation dialog; hover-tooltips delay ~800ms, focus-tooltips 0ms. If removing an animation wouldn't lose the user any information, remove it — most pages have too much motion, not too little.
+34. **Motion passes the executable audit.** Run `python3 scripts/audit_motion.py <paths>` and review the findings. No `transition: all`, `ease-in` on UI, `scale(0)`, layout-property animation, ungated hover motion, or missing reduced-motion handling. UI motion over 300ms has a reason: modal, drawer, marketing story, or deliberate confirmation.
+
+### Typography
+
+35. **No emoji as icons.** Emoji standing in for icons in a "real" product UI is an instant tell. Use the mood's fetched Iconify set, a built SVG, or lead with the visual.
+36. **Body copy is not set in a monospace face.** Mono/semi-mono for paragraph text reads as "developer template." Reserve mono for code, data, timestamps, and short technical labels. Holds even for a technical mood — see the note in `references/style-tokens.md`.
+37. **Headline line-height is tightened but never below its floor.** Tighten as size grows, but 1.0 is the floor for a bold, large-clamp display headline — below it (e.g. 0.87), descenders and punctuation touch the line below. Verify visually at the actual weight/size, not by reading the CSS number. (For non-Latin scripts, the floor is higher — see `references/style-tokens.md`'s Non-Latin section.)
+38. **No italic headers.** Headings and display type are roman (`font-style: normal`). An italicized emphasis word inside an upright heading (`Built to <em>think</em>`) is one of the most reliable AI tells; so is an all-italic display face. Carry emphasis with weight, accent color, or a drawn underline. Italic survives only as body-copy emphasis inside running paragraphs.
+39. **At most three font families on the page.** Display + body + at most one outlier (wordmark / hero stat / pull quote), and the outlier appears in at most two slots. Same family at different weights counts once. A fourth family — or an outlier used as a third body font — is slop.
+
+### Assets, states & honesty
+
+40. **Not asset-empty.** Every section that calls for real photography has a real photo, every concept-driven section (mission, values, feature explainers) has an illustration, and icons are real fetched icons — not flat color blocks, emoji, or placeholders. All present in this pass, not deferred.
+41. **Core app states are real.** Loading, empty, error, disabled, focus, hover, pressed, and success states exist for app screens. A dashboard or form that only looks good in the happy populated state is unfinished.
+42. **Assets share one visual DNA.** Multiple icons/illustrations in a batch visibly belong to the same family (consistent stroke width, consistent color treatment), not independently sourced. One icon library per page — never two mixed.
+43. **SVG assets pass `scripts/validate_assets.py`.** A malformed SVG (classically a `--` inside a comment) reads as normal text but renders broken in strict browsers — check by parsing, not by reading the source.
+44. **Every chart/graph card has a caption, and its geometry was actually looked at.** A chart with axis labels but no title is still unlabeled — state what it shows in one line, and connect it to any related stats nearby. `validate_assets.py` only confirms well-formed XML; before shipping, render the chart and visually confirm the marks are internally consistent — a trend line spans the plotted range, bar heights reflect their labeled values, segments sum to a sensible whole.
+45. **Interactive states exist.** Hover / `:focus-visible` / `:active` / disabled / loading states are specified, not left to browser defaults. Inputs specifically: border-width stays constant across states (state goes to color/outline/shadow, never `border-width` — it shifts layout); disabled is signalled by three channels (opacity + `cursor: not-allowed` + the native attribute), not opacity alone; input height matches adjacent button height.
+46. **Real content, not lorem-ipsum-adjacent placeholders**, wherever the PRD gives enough to write real copy. "Lorem ipsum," "Sample text," and placeholder names ("Jane Doe," "Acme," "Nexus") read as unfinished even in a first draft.
+47. **No invented metrics or fabricated proof.** Any quantitative claim — "10× faster," "trusted by 50,000+ teams," "+47% conversion," "99.9% uptime" — that the user didn't supply and the model made up to fill a stat-led layout or proof bar is slop the moment it's invented. Replace with a real number, an honest `—` + "metric to confirm" placeholder, or a section that doesn't need the proof slot. Same rule for testimonials, logos, and case-study counts.
+
+### Token & honesty discipline
+
+48. **No mid-render token improvisation.** Every color and every `font-family` in the artifact references a named token (`var(--color-accent)`, `font-family: var(--font-display)`). An inline hex / `oklch()` / `rgb()` value, or a `font-family: "Some Font"` that bypasses the token block, means the model picked the palette then freestyled past it. Lift the value into the token block as a named variable, or replace it with an existing token.
+49. **No attribution hindrance anywhere on the page.** No "Photo by …," no "Icons by …," no visible credit line. The default sources (Openverse CC0 photos, ideagram illustrations, Iconify icons) are attribution-free by license — a *visible* credit means an attribution-requiring source slipped in; swap it. Voluntary source credits belong in a code comment (the `CREDITS` block `fetch_photos.py` writes), never rendered as page text.
+50. **Honest about fallbacks.** If asset generation fell back to curated icons + code-native visuals because no image-gen tool was available, that's stated plainly, not implied to be custom-generated.
+51. **No caption that just narrates what the visual already shows.** Before writing a caption under a proof visual, check whether the visual already labels itself (tags, headers, on-image text). If it does, a caption restating the same fact in prose is redundant chrome, not clarification — cut it rather than trim it. This is a stricter case of the show-don't-tell rule (item set above), applied specifically to captions: the failure isn't just "worded defensively," it's that a caption exists at all where the visual already speaks for itself. When a caption genuinely adds information the visual can't carry, state it directly and stop — never as a defense of its own authenticity ("this is the real X, not a mockup," "genuinely Y, not staged"). Real, confirmed instance: a compare-slider hero visual already tagged "no skill" / "tastemaker" on the image itself did not need "Same prompt, both times" underneath it — the user flagged the caption twice, first for the defensive wording, then for existing at all, before the fix was to delete it, not further edit it.
+
+---
+
+## Generic aesthetic tells (the "AI taste" cluster)
+
+The gates above catch process failures: a missing asset, wrong contrast, a wall of text. This group catches something harder. A page can pass every gate and still read as generated, because its visual language is the safe, generic, modern default one-shot output keeps reaching for. Treat these as reflective prompts, not just boxes.
+
+51. **Not the same pill eyebrow on every section.** The little rounded label above a heading — often with a leading dot or trailing hairline — is a template signature. Once is fine; the identical treatment on every section is a tell. Vary how section context is signalled, or drop the label where the heading already carries it.
+52. **Semi-brutalist is a deliberate choice, not the reflex.** Hairline borders instead of shadows, flat fills, high-contrast mono, sharp/minimal radius — a legitimate style when it fits the product, a tell when it's the house default applied regardless of mood. Ask whether this aesthetic actually fits *this* product, or whether it's just the safe modern look reached for again.

package/skills/tastemaker/references/asset-curation.md

@@ -0,0 +1,80 @@
+# Asset Curation
+
+Use this before Step 3 on landing pages, visual product sites, galleries, launch pages, and any request where the user expects a premium or artistic result.
+
+Good pages do not use assets as decoration. They build a small visual cast, then reuse that cast with changing scale, crop, material, and motion.
+
+## The Asset Cast
+
+Pick 4-6 asset roles before writing markup:
+
+- **Hero anchor:** the main object that proves the product exists. Use a real screenshot, generated hero artwork, product photo, or constructed scene.
+- **Mode range:** 3-5 different visual registers that prove the system can change taste, not just recolor one layout.
+- **Process artifacts:** files, commands, checklists, contrast matrices, logs, receipts, or annotations that explain how the product works.
+- **Human or market proof:** real logos, avatars, demos, repo links, public artifacts, or deployment receipts. Do not invent these.
+- **Texture object:** one tactile element such as paper, stone, fabric, poster, card, device, plant, or stamp to keep the page from feeling purely digital.
+- **Micro assets:** icons, swatches, cursors, arrows, labels, pins, and small crops used to connect the larger pieces.
+
+If a page repeats one screenshot family more than twice, add another asset role or crop family. Repetition needs a story reason.
+
+## Curation Pass
+
+Create a short asset board in `.tastemaker/reference-board.md` or the style lock:
+
+```markdown
+## Asset cast
+- Hero anchor:
+- Mode range:
+- Process artifacts:
+- Proof:
+- Texture object:
+- Micro assets:
+- Rejected:
+```
+
+For each section, assign one primary asset role. A section with no assigned asset role must be intentionally text-led, such as a manifesto poster.
+
+## Composition Patterns
+
+Use the bundled artifact kit when the project has no mature design system:
+
+- `assets/artifact-kit.css` for artifact boards, proof stacks, mode runways, command strips, swatch rails, and tactile cards.
+- `assets/artifact-kit.js` for GSAP helpers that animate artifact boards, mode cards, pinned ledgers, and parallax proof images.
+
+The kit is not a theme. Treat it like composition scaffolding, then map it to the project tokens.
+
+Patterns:
+
+- **Artifact board:** layered screenshots, notes, swatches, and command blocks around one anchor image.
+- **Mode runway:** overlapping cards that each show a different aesthetic lane.
+- **Process ledger:** dark or calm file cards that explain the system with real paths or commands.
+- **Poster break:** one typographic section with 1-2 tiny image fragments.
+- **Tactile close:** a physical-feeling object or still-life tied to the brand.
+
+## Asset Quality Gates
+
+- Every important image must have a distinct role. Do not reuse the same poster or screenshot as hero, demo, and proof unless the page is explicitly about that artifact.
+- At least one section must show range: different product category, mode, layout density, or mood.
+- At least one section must show process: files, commands, scans, or decisions.
+- At least one section must show physicality: texture, paper, object, shadow, or material.
+- Motion must belong to assets, not only text. Scroll should move, reveal, pin, scrub, or transform the visual cast.
+- Captures must be local or deploy-safe. If a static site deploys only `site/`, copy needed assets into `site/assets/...`.
+
+## When To Add A Component Library
+
+For production React or Next apps, prefer a real primitive library for interaction and build the visual kit on top of it:
+
+- Radix or shadcn/ui for dialogs, menus, popovers, tabs, selects, sheets, tooltips, and command palettes.
+- Motion or GSAP for choreographed asset movement. Use GSAP for scroll-storytelling landing pages.
+- React Aria for complex accessible components when design needs custom structure.
+
+For static marketing pages, do not install a full UI library only for cards. Use `artifact-kit.css` plus GSAP. A heavy component library cannot fix weak asset taste.
+
+## Anti-Patterns
+
+- A whole page made from the same screenshot repeated in different card sizes.
+- Decorative screenshots that do not teach anything.
+- A mode claim with no visible mode gallery.
+- Motion only on opacity while all assets sit still.
+- Stock assets that could belong to any AI tool.
+- Product claims without visual proof beside them.

package/skills/tastemaker/references/component-catalog.md

@@ -0,0 +1,97 @@
+# Component catalog — named archetypes with stable IDs
+
+A macrostructure (`references/macrostructures.md`) is the page shape; this file is the **parts inside it**. Each archetype has a stable ID (so builds and the project log can reference it precisely), a one-line shape, a "use when," a "don't confuse with," and a set of **variation knobs** so the *same* archetype built twice is not identical.
+
+Two axes of variety, both mandatory:
+
+1. **Across pages** — no two consecutive builds (per `.tastemaker/log.json`, see `references/diversification.md`) share the same nav archetype, footer archetype, or hero archetype. Reaching for the mood's *default* on every build is exactly the monoculture this catalog exists to break.
+2. **Within a page** — no two sections use the same archetype (two identical feature blocks read as templated), and if you must reuse an archetype across builds, change at least one knob value.
+
+**This catalog is asset-forward on purpose.** tastemaker sources real photos, illustrations, icons, and builds real mockups (Step 3) — so the feature and hero archetypes here *show* (a live-looking UI fragment, a real chart, an annotated capture, a sourced illustration) rather than settling for a heading + two sentences + a decorative icon. That is the show-don't-tell default from `SKILL.md` Step 4, expressed as concrete parts. An archetype that would collapse into a text-wall is marked as such.
+
+**Loading discipline:** read this index, pick your archetype IDs, and carry only those forward — you don't need every archetype's detail in context to build one page. A typical page uses one each of Nav / Hero / Footer, one or two Feature, one Proof, one CTA, and a Section-head treatment.
+
+---
+
+## Navigation — `N#`
+
+- **N1 · Minimal wordmark** — Wordmark left, at most two text links + one action right. *Use when:* the page genuinely has ≤2 destinations. *Don't confuse with:* N2 (dense SaaS bar). ⚠️ **This is the most-recognized AI nav fingerprint when used reflexively** — reach for it only when the page really is that minimal.
+- **N2 · Balanced product bar** — Wordmark left · a centered cluster of 3-6 links (some with hover panels) · sign-in + filled CTA right. Frosts/blurs on scroll. The dense, deliberate marketing nav. *Use when:* a real product with several destinations. *Default for* premium/technical/warm product sites (in place of the reflexive N1).
+- **N3 · Floating pill** — A rounded, visibly-detached pill sitting a margin off the top, blur backdrop, soft shadow. *Use when:* the hero has a surface/imagery beneath for the blur to sit over; contemporary feel. *Don't confuse with:* N1 (full-width). ⚠️ A pill that's ~95% viewport-wide is just a rounded full-width bar — keep it content-sized.
+- **N4 · Editorial masthead** — Full-width header, larger centered wordmark, a thin issue/date/section line, optional inline link row, a rule beneath. *Use when:* Editorial Index / Manifesto / publication feel. *Mood:* elegant, premium.
+- **N5 · Side rail** — A thin vertical strip on one edge — rotated wordmark + a few section indicators. Collapses to a menu trigger on mobile. *Use when:* portfolio/editorial, or a docs-adjacent page. *Mood:* elegant, technical.
+- **N6 · Command bar / ⌘K** — A visible search pill (or a hidden ⌘K) opening a spotlight of grouped, keyboard-navigable destinations. *Use when:* search/docs-heavy or keyboard-first audiences (dev tools). *Mood:* technical.
+- **N7 · Announcement + retract** — A colored promo banner above one real nav; banner retracts on scroll-down, returns on scroll-up, dismissible. *Use when:* a launch/commerce moment with something genuinely worth announcing. *Mood:* playful, warm, commerce.
+- **Knobs:** *Position* (static · sticky · frost-on-scroll) · *Link density* (2 · 4 · 5-6) · *Action* (filled CTA · outline · text+arrow · none).
+- **Routing (default → also OK):** premium **N2** → N4, N3, N1 · warm **N2** → N7, N3 · technical **N2** → N6, N5, N1 · playful **N7** → N3, N2 · elegant **N4** → N5, N1, N3.
+
+## Hero — `H#`
+
+- **H1 · Statement fold** — A single bold headline (one promise) fills the fold; one primary action; no feature dump. Typography *is* the visual, or one restrained supporting mark. *Use when:* the brand/promise is the message (Manifesto, Poster Fold, single-voice products). *Don't confuse with:* a text-wall — it's one line done large, not paragraphs.
+- **H2 · Split demo** — Headline + one-line lede + primary CTA on one side; a real product mockup / annotated capture on the other, often tilted 1-3° or clipped by the viewport edge to imply "there's more." *Use when:* a product whose value is obvious once seen (Product Demo, Feature Stack). *Mood:* technical, premium. **Asset-forward:** the mockup is a real capture or a built UI fragment, never a redrawn fake browser bar (see the no-fake-chrome rule below).
+- **H3 · Photographic fold** — One full-bleed sourced photograph carries the fold; headline and caption sit in a corner or below. *Use when:* commerce, food, travel, physical product, brand launch (Gallery Grid, Poster Fold). **Asset-forward:** real Openverse/Pixabay photography from Step 3, never an invented stock look.
+- **H4 · Stat hero** — A giant real number (with a short qualifier line that says what it means) anchors the fold. *Use when:* Stat-Led, and the figure is real. *Never* a bare number with no words, and *never* an invented metric.
+- **H5 · Illustration centerpiece** — A single sourced-and-recolored `ideagram`/unDraw illustration (or a Tier-A CSS/Tier-B SVG build) sits as the hero's one illustrative element, recolored to the locked accent. *Use when:* an abstract/concept-led product (warm, wellness, community), or a bakery/studio/atelier brief. *Mood:* warm, playful, elegant.
+- **H6 · Letter / first-person** — Opens like personal correspondence ("Dear reader,"), no buttons in the fold, reads as a piece of writing. *Use when:* Long-Scroll Narrative, founder-voice, community. *Mood:* warm, elegant.
+- **Knobs:** *Display size* (xl · xxl) · *Alignment* (left-bias · centered · right-bias — never all four of eyebrow/headline/lede/CTA stacked on one centered axis) · *Support* (none/typographic · real mockup · photo · illustration · stat).
+- **Governing rule:** every hero obeys `references/hero-guidelines.md` — one job, one visual focus, headline sized to word count, line-height above its clipping floor, fits the fold at 1280×800.
+
+## Feature / showcase — `F#`
+
+- **F1 · Alternating bands** — Each feature is a full-width band, text and a real visual alternating sides down the scroll. *Use when:* 3-6 features that each deserve a real mockup/chart/diagram. *Don't confuse with:* a 3-up card grid (the generic tell). **Asset-forward:** every band's visual is real, not a paragraph with an icon.
+- **F2 · Bento tiles** — Asymmetric grid of mixed-span tiles, each a small live-looking UI fragment or a stat or a mini-visual. *Use when:* many small features better shown-at-a-glance than sequenced. *Knob:* tiles (4·6·9), spans (regular·irregular·mosaic), border (hairline·accent-corner·none).
+- **F3 · Sticky scroll stack** — A pinned pane (the running visual) beside a scrolling column of steps that swaps the visual as you pass each step. *Use when:* a workflow or a multi-part product told in sequence. *Mood:* technical, premium.
+- **F4 · Numbered step sequence** — Ordered stages (1 → 2 → 3) flow down the page, each with a heading, a short line, and a small real visual. *Use when:* onboarding, "how it works," a process. **Not** a bulleted list — each step shows a state.
+- **F5 · Annotated capture** — One real product capture centre-stage with numbered pins / margin labels pointing at real UI detail. *Use when:* one screen carries most of the value and the detail is the story. **Asset-forward:** a real capture, real annotations.
+- **F6 · Spec sheet** — Each row is a feature; hairline rules, tabular figures, editorial restraint. *Use when:* spec-heavy/technical products, comparisons, Catalogue. *Mood:* technical, elegant.
+- **F7 · Product card grid** — Each card is a real product (image · name · price · one micro-action), reads like a shop floor. *Use when:* commerce (Gallery Grid, Catalogue). **Asset-forward:** real product photography.
+- **Knobs (cross-cutting):** *Visual source* (mockup · chart · photo · illustration · diagram) · *Density* · *Rhythm* (even · irregular).
+
+## Proof — `P#`
+
+(All bind the honesty rule: real logos, real quotes, real numbers, or an honest placeholder — never invented.)
+
+- **P1 · Logo wall (hairline)** — A monochrome row/grid of real customer logos separated by hairlines, no card boxes. *Use when:* credibility is a real conversion blocker and the logos are real.
+- **P2 · Pull-quote with marginalia** — One real testimonial in the wide column; attribution + source in the narrow margin. *Use when:* one strong, real quote carries more than five weak ones.
+- **P3 · Single huge quote** — One real quote set big, a small-caps attribution beneath, a whole section. *Mood:* elegant, warm.
+- **P4 · Stat strip** — A horizontal row of 3-5 real metrics (figure + qualifier), tabular figures. *Use when:* the numbers are real and worth a dedicated band.
+- **Knob:** treatment (row · grid · single) · figure weight · attribution position.
+
+## CTA — `C#`
+
+- **C1 · Inline form** — The CTA *is* the form (one email input + "Submit →"), no separate landing. *Use when:* newsletter/waitlist/signup is the one action. *Mood:* warm, technical, playful.
+- **C2 · Statement + action** — One large closing line (not a sitemap) with a single primary action beneath. *Use when:* Long-Scroll/Manifesto closes. *Mood:* any.
+- **C3 · Typographic link** — Just a word, an arrow, a 1px underline — no box. *Use when:* editorial/minimal pages where a heavy button would break the voice. *Mood:* elegant, premium.
+- **C4 · Sticky bottom bar** — A pinned bar holding a CTA + a one-line reassurance. *Use when:* a long page where the action should stay reachable. *Knob:* reveal (always · scroll-up · after-fold).
+
+## Footer — `Ft#`
+
+- **Ft1 · Masthead** — Wordmark + tagline anchor one band; a few links, address/license beneath. *Default for* editorial/premium.
+- **Ft2 · Inline single line** — One horizontal line of credits/address/copyright, hairline above, no columns. *Default for* modern-minimal/technical.
+- **Ft3 · Index columns** — 3-4 short link columns under small-caps headings. ⚠️ **The 4-column Product/Company/Resources/Legal + social-row footer is an AI fingerprint when used reflexively** — reach for it only on a genuine docs root or hub.
+- **Ft4 · Statement close** — One large display sentence dominates (a closing line, not a sitemap); wordmark + minimal links beneath in muted type. *Mood:* atmospheric/premium.
+- **Ft5 · Newsletter-first** — The signup form is the primary footer element; everything else is small muted type beneath. *Use when:* audience-building is a real goal.
+- **Ft6 · Marquee** — A horizontal infinite-scroll tagline line. *Mood:* playful, brand-forward.
+- **Knobs:** wordmark size · separator style · link density.
+- **Routing (default → also OK):** premium/elegant **Ft1** → Ft4, Ft2 · technical/minimal **Ft2** → Ft1, Ft5 · playful **Ft6** → Ft4, Ft5 · commerce **Ft5** → Ft3, Ft2.
+
+## Section heads — `S#`
+
+How a section announces itself (a quieter axis, but repeating the same treatment down a page is its own tell):
+
+- **S1 · Hanging** — Heading floats in negative space above the section; no rule, no eyebrow.
+- **S2 · Inline** — A small-caps phrase emerges inside the body flow; no spatial break.
+- **S3 · Sticky pinned** — Heading stays in view while its content scrolls beneath (orientation aid for long sections).
+- **S4 · Stacked eyebrow** — An eyebrow/label sits **directly above** the heading, same column, vertical stack only.
+- ⚠️ **Banned: the eyebrow-left / heading-right two-column head** (`01 · THE TOUR` in a left column beside the heading). It is the single most reliable templated-editorial tell. When an eyebrow is used at all (default OFF — most sections don't need one), stack it above the heading in one column. Cap eyebrows at 1-2 per page.
+- ⚠️ **A section headline is not the hero — cap its size well below it.** The hero sizing discipline in `references/hero-guidelines.md` only governs `.hero h1`; nothing else on the page stops a section headline from reaching that same scale, and real output has shown a mid-page headline (e.g. "One failed retry budget becomes a clear product decision.") rendering at room-filling size in a scroll-storytelling section. As a working ceiling: a section headline should render at roughly **50-65% of the hero's full display size** (the size the hero's own 6-8 word band uses at the top of its `clamp()` range) — enough to read as a clear signpost for that section's content, never enough to compete with the hero for dominance. It should also comfortably read in 1-2 lines regardless of word count; if it's stacking one word per line, the size is wrong for the container, same failure as an oversized hero headline. A Long-Scroll Narrative or Manifesto macrostructure that wants one deliberately large mid-page statement (per `references/macrostructures.md`) is the one exception — and it should be a single stated moment on the page, not the default treatment repeated at every section head.
+
+---
+
+## Cross-cutting build rules (bind every archetype)
+
+- **No fake chrome.** Never hand-build a fake browser bar (URL pill + traffic-light dots), fake phone frame, fake code-window, or fake IDE chrome. Use a real screenshot in a `<figure>` (hairline border at most), or omit the chrome. Redrawn chrome is a strong AI tell — the model invented UI the environment already supplies.
+- **One icon family per page.** Never mix two icon libraries on one page, and never use an emoji (✨🚀⚡🔥🎯✅) as a feature/step/value icon. Use the mood's fetched Iconify set (`scripts/fetch_icons.py`), a built SVG, or drop the icon and lead with the visual.
+- **Asset-forward, not text-wall.** If an F-archetype ends up as heading + two sentences + a decorative icon, it failed — swap in the real mockup/chart/illustration/photo the archetype calls for (Step 3 sourced them). This is the show-don't-tell default made concrete.
+- **State every archetype's picks out loud** before building, and stamp them (see `references/diversification.md`): *"Nav: N2. Hero: H2 (split demo, real mockup, left-bias). Features: F1 alternating bands. Proof: P1 logo wall. CTA: C2 statement. Footer: Ft1 masthead."*
+- **Mobile:** every archetype collapses to a single column below ~60rem and steps display type down below ~40rem; hit targets ≥44px; no two-line clickable text; no horizontal scroll. See `references/component-patterns.md` and `references/hero-guidelines.md` for the per-type collapse behavior.