@damiangilgonzalez/harness 1.3.7

package/skills/tastemaker/references/interface-quality-rules.md

@@ -0,0 +1,148 @@
+# Interface quality rules
+
+The craft details that separate a page that *looks* designed from one that *is* built well. `references/anti-slop-checklist.md` catches output that reads as AI-generated; this file catches output that reads as amateur — broken keyboard access, layout shift, dead paste handlers, hardcoded date formats.
+
+Adapted from **Vercel's Web Interface Guidelines** (`github.com/vercel-labs/web-interface-guidelines`), which is the best public codification of this layer. Fetch the current version when it matters — it's actively maintained and this is a snapshot:
+
+```
+https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+```
+
+Apply at **Step 4 (build)** and verify at the gate sweep. Framework-agnostic in principle; the syntax examples are React/Tailwind because that's the source's idiom.
+
+---
+
+## Accessibility
+
+- Icon-only buttons need `aria-label`.
+- Every form control needs a `<label>` or `aria-label`.
+- Interactive elements must work from the keyboard.
+- `<button>` for actions, `<a>`/`<Link>` for navigation. Never `<div onClick>`.
+- Images need `alt`; decorative images take `alt=""`, decorative icons take `aria-hidden="true"`.
+- Async updates announce via `aria-live="polite"` (toasts, validation).
+- Semantic HTML before ARIA. Reach for `<button>`, `<a>`, `<label>`, `<table>` first.
+- Headings follow `<h1>`–`<h6>` order. Include a skip link to main content.
+- Heading anchors need `scroll-margin-top`.
+
+## Focus
+
+- Every interactive element has a visible focus indicator.
+- Never remove a focus outline without replacing it.
+- Prefer `:focus-visible` over `:focus` (no ring on mouse click).
+- `:focus-within` for compound controls.
+
+## Forms
+
+- Inputs need `autocomplete` and a meaningful `name`.
+- Correct `type` (`email`, `tel`, `url`, `number`) with matching `inputmode`.
+- **Never block paste.**
+- Labels clickable via `htmlFor` or by wrapping the control.
+- `spellCheck={false}` on emails, codes, usernames.
+- Checkbox/radio: label and control are one hit target, no dead zones.
+- Submit stays enabled until the request starts; show a spinner during.
+- Errors inline next to the field; focus the first error on submit.
+- Placeholders end with `…` and show a real example of the pattern.
+- Warn before navigating away from unsaved changes.
+
+## Animation
+
+These overlap with `references/animation-guidelines.md`'s motion gate and `scripts/audit_motion.py` — both should pass.
+
+- Respect `prefers-reduced-motion`.
+- Animate `transform` and `opacity` only (compositor-friendly).
+- **Never `transition: all`** — list properties explicitly.
+- Set an intentional `transform-origin`.
+- SVG: transform a `<g>` wrapper with `transform-box: fill-box; transform-origin: center`.
+- Animations must be interruptible and respond to input mid-flight.
+
+## Typography
+
+- Ellipsis character `…`, never three periods.
+- Curly quotes, not straight ones.
+- Non-breaking spaces in measurements (`10&nbsp;MB`), shortcuts (`⌘&nbsp;K`), brand names.
+- Loading states end with an ellipsis: `Loading…`, `Saving…`.
+- Numeric columns and comparisons use `font-variant-numeric: tabular-nums`.
+- Headings use `text-wrap: balance`.
+
+## Content handling
+
+- Text containers handle overflow: `truncate`, `line-clamp-*`, or `break-words`.
+- Flex children need `min-w-0` for truncation to work at all.
+- Design the empty state — don't render broken UI for an empty array.
+- Test copy at short, medium, and very long. Real user content is not one line.
+
+## Images
+
+- Explicit `width`/`height` to prevent layout shift.
+- `loading="lazy"` below the fold; `fetchpriority="high"` for the critical above-fold image.
+
+> Related real bug worth remembering: setting HTML `width`/`height` attributes *and* a CSS `aspect-ratio` without `height: auto` makes the browser use the literal attribute height. It silently blew up a card layout on this project's own site. Set `height: auto` when `aspect-ratio` drives the box.
+
+## Performance
+
+- Lists over ~50 items: virtualize (`virtua`, or `content-visibility: auto`).
+- Don't read layout during render (`getBoundingClientRect`, `offsetHeight`, `scrollTop`).
+- Batch DOM reads and writes; never interleave.
+- Prefer uncontrolled inputs.
+- `<link rel="preconnect">` for CDN/asset domains; `preload` critical fonts with `font-display: swap`.
+
+## Navigation & state
+
+- **URL reflects state** — filters, tabs, pagination, expanded panels belong in query params.
+- Navigation uses real `<a>`/`<Link>` so Cmd-click and middle-click work.
+- Deep-link stateful UI.
+- Destructive actions get a confirmation or an undo window. Never immediate.
+
+## Touch
+
+- `touch-action: manipulation` to kill the double-tap zoom delay.
+- Set `-webkit-tap-highlight-color` deliberately.
+- Modals/drawers use `overscroll-behavior: contain`.
+- While dragging: disable text selection, mark the dragged element `inert`.
+- `autoFocus` sparingly — desktop only, one primary input, never on mobile.
+
+## Layout & safe areas
+
+- Full-bleed layouts handle `env(safe-area-inset-*)` for notches.
+- No unwanted horizontal scrollbars.
+- Flex/Grid over JavaScript measurement.
+
+## Theming
+
+- `color-scheme: dark` on `<html>` for dark themes — fixes native scrollbars and inputs.
+- `<meta name="theme-color">` matches the page background.
+- Native `<select>` needs explicit `background-color` and `color` (Windows dark mode).
+
+## Locale
+
+- `Intl.DateTimeFormat` and `Intl.NumberFormat`. Never hardcode date or currency formats.
+- Detect language from `Accept-Language`/`navigator.languages`, not IP.
+- `translate="no"` on brand names, code tokens, identifiers.
+
+## Hydration (SSR frameworks)
+
+- An input with `value` needs `onChange`, or use `defaultValue`.
+- Guard date/time rendering against server/client mismatch.
+- `suppressHydrationWarning` only when genuinely necessary.
+
+## Interactive states
+
+- Buttons and links need a `hover:` state.
+- Hover/active/focus increase contrast relative to rest — see `references/style-tokens.md`'s contrast floor; a hover state that drops below the floor is a real failure, not a style choice.
+
+## Copy
+
+Overlaps with the stop-slop discipline; both apply.
+
+- Active voice: "Install the CLI," not "The CLI will be installed."
+- Second person. Avoid first person.
+- Numerals for quantities: "8 deployments," not "eight."
+- Specific button labels: "Save API Key," not "Continue."
+- Error messages state the resolution, not just the problem.
+- `&` over "and" only where space is genuinely constrained.
+
+---
+
+## Flag these on sight
+
+`user-scalable=no` or `maximum-scale=1` · `onPaste` + `preventDefault` · `transition: all` · `outline-none` with no `:focus-visible` replacement · `<div>`/`<span>` with click handlers · images without dimensions · big `.map()` with no virtualization · inputs without labels · icon buttons without `aria-label` · hardcoded date/number formats · unjustified `autoFocus`

package/skills/tastemaker/references/library-selection.md

@@ -0,0 +1,50 @@
+# Library selection
+
+Use this before adding or hand-rolling complex interface behavior. Tastemaker should raise the floor by picking proven parts for hard interaction problems, then spend design energy on hierarchy, fit, and polish.
+
+**Read alongside `references/component-sourcing.md`.** This file covers *behavioral* primitives — the things that are hard to get **right** (focus management, keyboard access, virtualization, gesture physics). That file covers *visual* components and whole blocks — the things that are hard to make **look finished** (heroes, pricing tables, bento grids, dashboards, charts), and the shadcn-compatible registries they come from. A page usually needs both: a Base UI dialog for correctness, a registry block for finish.
+
+## Decision order
+
+1. Identify the task, not the library the user mentioned.
+2. Check `package.json`, lockfiles, and existing imports.
+3. Prefer the healthy library already in the repo when it covers the task.
+4. If the repo has no answer, pick one library from the table below.
+5. Hand-roll only when the behavior is static, simple, or the project forbids dependencies.
+
+Do not replace an existing working library just because this file names a different default. Flag the better choice, then change dependencies only when the user asks or the current library blocks the requested experience.
+
+## Defaults
+
+| Task | Default | Use when |
+|---|---|---|
+| Accessible dialogs, popovers, menus, selects | Base UI | You need focus management, dismissal, keyboard behavior, anchored overlays, or trigger-aware positioning |
+| Command palette | cmdk | Users search, jump, or run actions from a keyboard-first palette |
+| Toasts | Sonner | You need stacked notifications with polished entrance, exit, swipe, and timing behavior |
+| One-time password input | input-otp | You need paste handling, focus movement, and accessible segmented codes |
+| General animation in React | Motion | You need springs, layout animation, exit animation, gesture animation, or interruptible values |
+| Simple hover, press, reveal | CSS transitions or GSAP | The motion is predetermined and does not need a spring or gesture state |
+| Numbers and counters | NumberFlow | Digits change and should not jitter or reflow |
+| Static or dashboard charts | Recharts, or a **bklit** registry chart | Recharts for ordinary product charts with tooltips and responsive layouts. On a shadcn project, prefer pulling a bklit chart (`npx shadcn@latest add @bklit/<name>`) — 17+ types including candlestick, sankey, and heatmap, arriving as editable source already styled to a coherent system rather than assembled from primitives. Not benchmarked head-to-head against Recharts here; the argument is finish and breadth of chart type, not raw capability. Either way: **never hand-roll a chart.** |
+| Real-time charts | Liveline | Data streams over time and the chart advances continuously |
+| Drag and drop | dnd kit | Users reorder, drag between containers, or need accessible drag behavior |
+| Long lists and large tables | Virtuoso | Rendering every row would hurt scrolling or memory |
+| Shared client state | Zustand | Multiple distant components read and write the same state |
+| Conditional class names | clsx | Classes depend on state but do not deserve a variant API |
+| Variant-driven Tailwind components | cva | A component has intent, size, state, or density variants |
+| Theme switching | next-themes | A Next.js app needs dark mode without a flash on load |
+
+## Mismatches to catch
+
+- A custom dropdown, dialog, or menu with manual focus handling: use Base UI unless the project already has a strong primitive layer.
+- A toast built with a modal or alert component: use Sonner.
+- A number ticker built by replacing text each render: use NumberFlow.
+- A 1,000-row table rendered directly: use Virtuoso before inventing pagination.
+- A hand-built drag system without keyboard behavior or pointer capture: use dnd kit.
+- A large component with nested ternary class strings: move to `clsx` or `cva`.
+
+## Motion library boundary
+
+Use CSS for simple state feedback: hover, press, opacity, transform, and small entrances. Use GSAP for scroll storytelling, sequenced page moments, and static marketing timelines. Use Motion for React components that need springs, layout animation, exit states, or gesture-driven values.
+
+Do not install an animation library for a button press. Do not hand-roll a spring.

package/skills/tastemaker/references/logo-sourcing.md

@@ -0,0 +1,43 @@
+# Logo design
+
+Every project scoped in Step 1 with a landing page, nav bar, or favicon needs a logo. First determine whether the project already has one. Search the repository, public assets, manifest, favicon links, brief, and supplied references. An existing mark is a brand constraint, especially if it is already distributed: reuse the exact asset and do not recolor, redraw, or replace it unless the user explicitly asks for a rebrand. If it feels visually disconnected from the new page, adapt spacing, surrounding color, scale, or lockup—not the mark itself.
+
+Only when no identity exists should you create a **mark** (a small symbol) paired with a **wordmark** (the product name set in the locked heading font). The rest of this file covers that cold-start path.
+
+## The one rule that matters most: no letter-in-a-box
+
+A single letter dropped inside a rounded square or circle — `[t]`, `[C]`, a monospace character on a colored tile — is the logo equivalent of the indigo-to-purple gradient. It's what every AI generates when it isn't really trying, and it reads as "placeholder someone forgot to replace," not "brand." **Never ship this as the final mark.** It fails the anti-slop checklist. A real mark is a *symbol* — an abstract geometric form or a single concrete object — that could stand on its own without the letter.
+
+## What a good mark actually is
+
+- **Simple and geometric.** 2-5 primitive shapes (circles, arcs, rounded rects, triangles, a single custom path), flat fill, following the same visual language as `ideagram/references/style-contract.md`. If you can't describe it in one sentence ("two overlapping leaves," "a stack of offset swatches," "an upward arc breaking a circle"), it's too complex for a logo.
+- **On-concept, one idea.** Pick the single concept the product is about and find the simplest shape for it — the same discipline as choosing an illustration metaphor in `ideagram/references/metaphor-library.md`, but reduced further. A mindfulness app → a lotus/petal or a calm arc. A design-taste tool → stacked color swatches or a refracting prism (raw input → refined output). A finance tool → an upward path. Don't try to encode the whole product; encode one thing.
+- **Recognizable at 16px.** The mark has to survive being a favicon. If its details disappear or it turns to mud at favicon size, simplify until it doesn't. Test this deliberately (render it small), don't assume.
+- **Two colors max**, from the locked palette — base + accent, per the style contract. A mark that needs three colors to read is too busy.
+- **Balanced negative space.** The shape should sit comfortably in a rough square bounding box with even optical weight — not crammed to one edge, not floating tiny in a large tile.
+
+## How to produce the mark — two paths
+
+**Path A — construct it (the reliable default).** A logo mark is just a very small, very simple illustration, and `ideagram` (vendored, always available) is already built for flat geometric SVG. Compose the mark directly from primitive shapes in the locked palette, following `ideagram/references/style-contract.md`. This is the default because it's automatic, original (no licensing question), on-brand by construction, and doesn't depend on a manual browse step. Build it, then validate with `scripts/validate_assets.py`.
+
+**Path B — an existing brand asset already in the repo.** If the project already has a mark, favicon, or brand kit anywhere in the repository or the brief, that is the mark. Reuse it byte-for-byte (see the preservation rule above) rather than producing a new one.
+
+> **Removed: third-party symbol libraries.** An earlier version of this file recommended a browsable third-party SVG symbol site as an optional manual source. It was removed after a security audit flagged the domain as a phishing risk, and because its license was never verifiable (no terms, license, or FAQ page existed). Do not reintroduce it or a substitute without a verifiable license **and** a clean reputation check — `scripts/check_domains.py` will fail the build on any domain not in the vetted allowlist. Constructing the mark (Path A) has no licensing question at all, which is why it is the default.
+
+## Assemble mark + wordmark
+
+- Set the product name in the project's **locked heading font** (from `references/style-tokens.md`'s matched set) at a weight that balances the mark — don't introduce a separate logo-only typeface unless asked.
+- Place the mark left of the wordmark (or above it for a stacked/centered lockup) with generous, consistent spacing. The mark and the wordmark's cap height should feel optically aligned.
+- Save the mark SVG and a combined mark+wordmark SVG (or lockup markup) to `design/assets/logo/`.
+
+## Export the favicon set
+
+Once the mark exists, run `scripts/export_favicons.py <mark>.svg --out design/assets/favicons/` for favicon.ico, apple-touch-icon, manifest icons, and an OG-card render — and actually wire them into the page `<head>`. A shipped site with a browser-default blank favicon reads as unfinished. (Degrades gracefully if cairo is missing; the SVG still works as `<link rel="icon" type="image/svg+xml">`.)
+
+## Record it in the style lock
+
+Note the mark's concept, the shapes it's built from, and the wordmark font in `.tastemaker/style-lock.md`'s Assets/Logo line, so later work reuses the same mark instead of reinventing it.
+
+## Honesty
+
+Don't imply a constructed mark is bespoke agency work — it's a clean, fast, legitimate logo, just don't oversell it.

package/skills/tastemaker/references/macrostructures.md

@@ -0,0 +1,41 @@
+# Macrostructures — named page shapes
+
+A **macrostructure** is the whole-page skeleton: heading placement, section rhythm, how the fold hands off to the scroll, where proof and CTA live, what the divider language is. It is a separate axis from mood (which sets color + type) and from screen type (which sets what content a screen holds). Two landing pages can share a mood and still be structurally different pages — or share the generic hero → 3-feature-cards → testimonial → CTA → footer rhythm and read as the same template in two color-swaps.
+
+That generic rhythm is the single most recognizable "an AI built this" tell at the page level, and it survives a perfect palette. This file exists so structure varies per project the same way `scripts/generate_palette.py` makes color vary per project. **The color engine already prevents color monoculture; this prevents structural monoculture.** Both axes have to move for two projects to actually feel like different sites.
+
+**Shape is not the same question as story.** This file (and `component-catalog.md`) answer what the page looks like. `references/narrative-arc.md` answers why each section exists and in what order — work that out *first* (Step 2.5 in `SKILL.md`), then pick the shape that carries it. A page can rotate through every macrostructure in this file and still read as sections-with-no-throughline if the arc was never worked out — variety and coherence are different properties, and a real build needs both.
+
+## How to use this file
+
+0. **Work out the narrative arc first**, per `references/narrative-arc.md` — the hook/problem/solution/how-it-works/proof/close beats. The macrostructure pick below should carry that arc, not the other way around.
+1. **Pick one macrostructure by name before building** — from the index below, not by reaching for the first shape that comes to mind (that reach is always the generic one). Picking on the page, out loud, is the accountability step that breaks the default-attractor.
+2. **Diversify against the last build.** Read `references/diversification.md` and the project's `.tastemaker/log.json` first — your pick must differ from the last macrostructure this project (or this session) produced. State the rotation in one line: *"Last build was Feature Stack; picking Editorial Index this time because the brief is a content-led studio site."*
+3. **Then pick the component archetypes** that fill it, from `references/component-catalog.md` — a macrostructure is the page shape; the catalog is the parts inside it.
+4. **Record the pick** in `.tastemaker/style-lock.md`'s Structure section and stamp it in the built CSS (see `references/diversification.md`).
+
+Macrostructures below are for **public/marketing pages** (landing, product, about, pricing-as-page) — that's where structural sameness bites hardest. **App shells** (dashboards, internal tools behind a sidebar) have their own governing shape in `references/component-patterns.md`'s App shell section — don't pick a marketing macrostructure for a shell; the sidebar-plus-topbar frame *is* its macrostructure.
+
+## The index
+
+Pick one. Each line is name — one-line shape — when to reach for it — mood affinity (not a hard restriction; any mood can wear any shape if the brief wants it).
+
+- **1 · Feature Stack** — Hero, then features revealed one full-width band at a time down the scroll, each an alternating text/visual split. The workhorse product page — but built as *bands*, not a 3-up card grid, and every band leads with a real mockup/chart, not a paragraph. *When:* a product with 3-6 distinct capabilities that each deserve a real visual. *Mood:* any; the default reach for premium/technical SaaS.
+- **2 · Bento Showcase** — An asymmetric grid of mixed-span tiles (1×1, 2×1, 2×2) where each tile shows one capability as a small live-looking UI fragment. Visual rhythm comes from tile size, not repetition. *When:* a product with many small features that are more compelling shown-at-a-glance than explained in sequence. *Mood:* premium, technical, playful.
+- **3 · Editorial Index** — Reads like a well-set magazine or a studio's index page: a masthead, a numbered or categorized list of work/sections, generous type, hairline rules. Content-led, not conversion-led. *When:* portfolios, agencies, publications, "this is who we are" pages. *Mood:* elegant, premium.
+- **4 · Long-Scroll Narrative** — the narrative arc from `references/narrative-arc.md` told top to bottom, one full-section beat at a time, with a scroll-linked reveal between them. The page is a story, not a menu — this is the macrostructure where the arc is most visually literal, but the arc itself applies to every macrostructure, not just this one. *When:* a non-obvious product that needs explaining before the pitch lands; a manifesto; a launch. *Mood:* any; strong for warm, elegant, technical.
+- **5 · Stat-Led** — A single dominant number or a tight row of real metrics is the hero and the spine of the page; everything else supports the figures. *When:* the product's story is genuinely quantitative and the numbers are **real** (never invented — see the honesty rule below). *Mood:* premium, technical.
+- **6 · Gallery Grid** — The work is the pitch: a grid of real photography, product shots, or case tiles fills the page, chrome kept minimal. *When:* commerce, photography, food, travel, physical product, anything where the imagery sells. *Mood:* elegant, warm, playful.
+- **7 · Product Demo / Workbench** — The hero is the product in use (a real annotated mockup, an interactive-looking capture, a clipped-by-viewport demo), and the page is organized around *doing*, not describing. *When:* dev tools, apps, anything where seeing it work is the strongest argument. *Mood:* technical, premium.
+- **8 · Split Diptych** — The page runs as a two-column composition — a persistent statement/nav column beside a scrolling content column, or a hard left/right split fold. *When:* studios, single-voice products, anything wanting an art-directed rather than stacked feel. *Mood:* elegant, premium, playful.
+- **9 · Conversational FAQ** — The page is built around real questions the audience actually asks, answered directly, with proof and CTA folded into the answers. *When:* products fighting a specific objection or a trust gap (regulated, high-consideration, "is this legit"). *Mood:* warm, technical.
+- **10 · Manifesto** — Type-forward, few images, one strong point of view carried by big statements and short lines. The restraint *is* the design. *When:* brand-led launches, opinionated products, a studio staking a position. *Mood:* elegant, premium, technical.
+- **11 · Catalogue** — A structured, almost tabular listing (products, plans, specs, releases) presented with editorial care rather than as a bare table. *When:* commerce with many SKUs, pricing-as-page, changelogs, spec-heavy products. *Mood:* technical, elegant.
+- **12 · Poster Fold** — One full-bleed art-directed fold (a photograph, a hand-built illustration, a bold type composition) carries the whole first screen; the page below becomes something quieter. *When:* the brand or a single image *is* the message — events, fashion, a hero launch moment. *Mood:* elegant, playful, warm.
+
+## Choosing well
+
+- **Match shape to argument, not to habit.** The Feature Stack is the right answer surprisingly often *and* the wrong answer to reach for reflexively — the whole point is that the pick is deliberate. If the brief's strongest argument is "look how much people use this," that's Stat-Led; "look at the work," Gallery Grid; "let me explain why this matters," Long-Scroll Narrative. Pick the shape that carries the actual argument.
+- **Vague brief → offer, don't default.** If there's genuinely no signal (no tone, no clear argument), offer the user three macrostructures from categorically different groups (one grid-led like Bento, one document-led like Long-Scroll, one poster-led like Manifesto) — three concrete choices, not a survey of all twelve.
+- **Honesty rule (binds every macrostructure).** Stat-Led, Catalogue, and any proof band must use **real** numbers, logos, and testimonials, or an honest placeholder (`—` plus a labelled "metric to confirm" block) — never an invented "+47% conversion" / "trusted by 50,000+ teams" to fill the shape. A fabricated stat is slop the moment it's invented, and it's the fastest way a proof-led page loses trust. If the user supplied no real figures, pick a shape that doesn't demand them, or leave the slot honestly empty.
+- **The macrostructure picks most of the structure; you still choose the components.** It sets heading placement, section rhythm, divider language, and reveal. You choose the nav, hero, feature, proof, CTA, and footer archetypes from `references/component-catalog.md` to fill it — and those diversify too.

package/skills/tastemaker/references/narrative-arc.md

@@ -0,0 +1,57 @@
+# Narrative arc — why each section exists, not just what it looks like
+
+Three files now govern a landing page, and they answer three different questions. `references/macrostructures.md` answers **what shape is the whole page**. `references/component-catalog.md` answers **what does each section look like**. This file answers **why does each section exist, and in what order** — the one question nothing answered before, and the gap that produces a page where every section is individually well-built but the page as a whole doesn't add up to an argument.
+
+This is not a taste preference. It's grounded in real, established frameworks:
+
+- **StoryBrand (SB7)** — the dominant framework in current landing-page copywriting practice: the customer is the hero, the brand is the guide. Seven parts: Character, Problem, Guide (empathy + authority), Plan, Call to Action, Failure (the stakes of not acting), Success (the transformation).
+- **PAS** (Problem–Agitate–Solution) — a narrower copy-level pattern: name the pain, make its real consequences concrete, then present the fix.
+- **The converged modern SaaS convention**: Hero → Problem → Solution → How it works → Social proof → CTA — cited consistently across current landing-page structure guidance, not invented for this file.
+
+## The default arc
+
+Six beats, adapted from StoryBrand/PAS into what a page actually builds:
+
+1. **Hook** (the hero) — the promise, sized and scoped per `references/hero-guidelines.md`.
+2. **Problem / stakes** — what's actually broken or at risk. Specific to *this* product, never generic ("teams struggle with X" is not a story beat — it's a placeholder for one). This is StoryBrand's Problem plus a dose of Failure: what happens if nothing changes.
+3. **Solution / mechanism** — how the product actually solves it, *shown* per the show-don't-tell table in `references/component-patterns.md`, not just asserted. This is StoryBrand's Guide moment — the product demonstrates it understands the problem and has the authority to fix it.
+4. **How it works** — the concrete steps or flow. StoryBrand's Plan: keep it simple, a handful of steps, not an exhaustive manual.
+5. **Proof** — real evidence: logos, a testimonial, real numbers. Honest per the existing no-invented-metrics rule (`references/anti-slop-checklist.md` gate 45) — a fabricated proof beat is worse than no proof beat. Also has its own visual-density floor: a label + description + small icon in a bordered box is not enough to carry a proof beat — see `references/component-patterns.md`'s show-don't-tell section for the specific floor.
+6. **Close / CTA** — the ask, tied back to the hook's promise. StoryBrand's Success: what the visitor's world looks like after they act.
+
+## Mapping beats to archetypes (the arc picks the job; the catalog still picks the look)
+
+| Beat | Typical archetypes (from `component-catalog.md`) | Notes |
+|---|---|---|
+| Hook | Any `H#` hero | Governed by `hero-guidelines.md`, not re-litigated here. |
+| Problem / stakes | A section built from prose + a supporting visual (an `F#` band showing the *broken* state, a before/after), or folded into the hero's subhead for a short arc | Rarely needs its own dedicated archetype — often the shortest, sharpest beat on the page. Resist turning it into a wall of text just because it doesn't map to a named archetype. |
+| Solution / mechanism | `F1` alternating bands, `F2` bento tiles, `F5` annotated capture | Pick per the show-don't-tell table — this beat exists specifically to *show* the fix. |
+| How it works | `F4` numbered step sequence, `F3` spec sheet, `F6` spec sheet for technical detail | Keep it simple — 3-5 steps, not an exhaustive walkthrough. |
+| Proof | `P1` logo wall, `P2` pull-quote, `P3` single quote, `P4` stat strip | Every number and quote real, per gate 45. |
+| Close | `C1` inline form, `C2` statement + action, `C4` sticky bar | Echo the hook's actual promise, don't introduce a new pitch here. |
+
+## Minimum section count: 4-5
+
+Hook + Problem + Solution + Proof + Close is already five. **Never collapse below four distinct beats** — a page that goes straight from hook to proof to close skips the part that actually persuades (why this is a problem, how the product fixes it). Thinness here is exactly what real output was caught doing: a handful of sections stretched to fill a page, not a page built from enough real beats to carry an argument.
+
+`How it works` is the one beat that can legitimately fold into `Solution` for a simple enough product — that's a deliberate merge, not an accidental omission (see below).
+
+## Skipping or merging beats — deliberately, and say so
+
+Not every product needs all six beats at full weight. A Manifesto macrostructure might spend most of its length on Problem/stakes with a single-line Solution and no separate How-it-works. A Stat-Led page might fold Proof into the hero itself. That's fine — **when it happens, it should be a stated choice tied to the macrostructure and the brief's actual argument, not a section that quietly never got built.** State which beats were merged or skipped and why, the same way macrostructure and archetype picks get stated out loud at Step 2.5.
+
+## The self-check, before finalizing
+
+The page, read top to bottom, should answer these questions in order:
+
+1. Who is this for, and what's the promise? (Hook)
+2. What's actually wrong, or at stake? (Problem)
+3. How does this fix it? (Solution)
+4. Why should I believe it? (Proof)
+5. What do I do now? (Close)
+
+If a section on the page doesn't serve one of these — or a deliberately stated variant, per the merging rule above — that's a gap in the arc, not just a design choice to shrug off. This is a distinct check from the diversification engine's structural-variety gates: a page can pass every structure gate (real macrostructure, varied archetypes, no generic template) and still fail this one, because variety and coherence are different properties. A page needs both.
+
+## Recording the arc
+
+State the beat sequence out loud at Step 2.5, alongside the macrostructure and archetype rotation: *"Arc: Hook (H2 split demo) → Problem (prose + before/after) → Solution (F1 bands) → How it works (F4 steps) → Proof (P4 stat strip) → Close (C2 statement). No beats skipped."* Note it in the build stamp the same way the structural picks are recorded (see `references/diversification.md`) so a later `audit` pass (per `references/verbs/audit.md`) can check the arc held together, not just that the structure varied.

package/skills/tastemaker/references/prototype-variants.md

@@ -0,0 +1,70 @@
+# Prototype variants
+
+Use this when the design direction is uncertain and the cost of guessing is high. A working picker teaches more than static explanation because you can feel density, hierarchy, and motion in context.
+
+## When to prototype
+
+Prototype before committing when the user asks for any of these and the direction is not obvious:
+
+- Hero section
+- Pricing card or plan comparison
+- Dashboard summary card
+- Onboarding step
+- Empty state
+- Toast or notification
+- Command palette
+- Data table interaction
+- Motion-heavy feature explanation
+
+Do not prototype routine wiring, backend work, or tiny visual fixes. Use the skill's normal workflow for those.
+
+## Variant rules
+
+- Build 2-3 variants by default. Use 4 only when the design space is wide.
+- Each variant must differ on a named axis: layout, density, hierarchy, interaction model, or motion.
+- Color swaps are not variants.
+- Every variant uses the project's locked tokens and real content.
+- Every variant must be shippable on its own. No dead controls, lorem ipsum, or placeholder states.
+- The picker swaps variants instantly. Switching variants is a repeated action, so it gets no animation.
+
+## Direction set
+
+Before coding, write this small table in your working notes:
+
+| Variant | Axis | Bet | Cost |
+|---|---|---|---|
+| Quiet | Lower density, minimal motion | Better for a daily-use tool | Less memorable |
+| Editorial | Larger type, stronger visual rhythm | Better for a launch page | Uses more vertical space |
+| Operational | Dense controls, faster motion | Better for repeated work | Less emotionally polished |
+
+If two rows differ only by accent color, merge them and create a real alternative.
+
+## Picker requirements
+
+The prototype surface must render one variant at a time at real size, inside realistic surrounding context. Do not use side-by-side thumbnails for final judgment.
+
+The picker chrome stays neutral and fixed:
+
+- Floating pill, bottom center unless it covers the work.
+- Number keys switch variants.
+- Left and right arrows cycle.
+- `R` replays entrance motion when a variant has motion worth replaying.
+- URL parameter stores the current variant, for example `?v=2`.
+- Exactly one variant has active state and `aria-current="true"`.
+
+The picker may use its own dark glass style. It does not inherit product tokens because it is test harness chrome, not part of the product design.
+
+## Promotion
+
+When the user picks a variant, promote only that variant into production code. Delete the prototype surface unless the user asks to keep it. Record the decision in `.tastemaker/decisions.log` as kept or rejected evidence for future taste memory.
+
+## Verification
+
+Before showing the picker:
+
+- Run the dev server or open the static file.
+- Flip through every variant with mouse and keyboard.
+- Replay motion.
+- Check the console.
+- Check 390px mobile and a desktop viewport.
+- Confirm reduced motion drops movement while keeping clear state changes.

package/skills/tastemaker/references/reference-intelligence.md

@@ -0,0 +1,121 @@
+# Reference intelligence
+
+Use this when a project starts with no supplied references, or when the brief asks for a modern, professional, current-feeling direction without naming examples. The goal is to build from a real reference field instead of the model's default memory of "good UI."
+
+## Design read
+
+Before picking colors or writing code, state one line:
+
+`Design read: <surface type> for <audience>, mode <Persuade|Operate|Read|Experience>, with <visual lane>, dials <variance>/<motion>/<density>/<art direction>.`
+
+Modes:
+
+- **Persuade:** landing pages, campaigns, pricing, portfolios where the visitor must decide and act.
+- **Operate:** apps, dashboards, editors, admin tools, settings, workflows.
+- **Read:** docs, articles, changelogs, help centers, explainers.
+- **Experience:** galleries, showcases, immersive portfolios, demos where the artifact leads.
+
+Default dials, then adjust from the brief:
+
+| Dial | Default | Meaning |
+|---|---:|---|
+| Variance | 7 | 1 = symmetrical and conventional, 10 = asymmetric and art-directed |
+| Motion | 5 | 1 = still, 10 = cinematic or physics-led |
+| Density | 4 | 1 = gallery-airy, 10 = cockpit-dense |
+| Art direction | 7 | 1 = safe commercial, 10 = strong point of view |
+
+Adjust by surface:
+
+- Persuade: variance 7-9, motion 5-8, density 3-5.
+- Operate: variance 3-6, motion 2-5, density 6-9.
+- Read: variance 4-6, motion 1-4, density 3-6.
+- Experience: variance 8-10, motion 6-9, density set by the artifact.
+
+The dials are not user-facing decoration. They decide layout asymmetry, amount of motion, section density, and how much visual risk the first viewport can carry.
+
+## Build a reference board
+
+Create `.tastemaker/reference-board.md` on cold starts and major redesigns.
+
+Use five lanes:
+
+1. **Direct competitors:** what this category already ships.
+2. **Adjacent products:** tools or brands with a similar audience, but a different category.
+3. **Cultural sources:** publications, physical objects, places, rituals, or graphics the audience already understands.
+4. **Interface systems:** official design systems or product languages that fit the surface.
+5. **Anti-references:** common category defaults this project should avoid.
+
+If web search or screenshot tools are available, collect 5-9 concrete references across those lanes and write the source URLs, dates viewed, and the traits you are borrowing. If browsing is unavailable, write an inferred reference board and label it `inferred, not viewed`; do not pretend you saw sources.
+
+Reference board format:
+
+```markdown
+# Reference board
+
+Created: <date>
+Mode: <Persuade|Operate|Read|Experience>
+Design read: <one-line read>
+Dials: variance <n>, motion <n>, density <n>, art direction <n>
+
+## Quality bar
+- <source or inferred reference>: <what sets the craft bar>
+
+## Borrow
+- Palette/material: <source> -> <trait, not copied pixels>
+- Type/hierarchy: <source> -> <trait>
+- Layout/composition: <source> -> <trait>
+- Motion/interaction: <source> -> <trait>
+- Asset language: <source> -> <trait>
+
+## Avoid
+- <category rut or anti-reference>
+
+## Direction contract
+- Thesis: <what this surface proves>
+- First viewport: <composition and primary visual>
+- System: <tokens, structure, motion, assets>
+- Risk: <what could go wrong if overdone>
+```
+
+## Pick the implementation foundation
+
+Use official systems when the brief clearly lives inside one:
+
+| Brief reads as | Reach for |
+|---|---|
+| Microsoft or enterprise productivity | Fluent UI |
+| Google or Android-adjacent product | Material 3 |
+| IBM or enterprise analytics | Carbon |
+| Shopify admin surface | Polaris |
+| GitHub/dev community | Primer |
+| UK public service | GOV.UK Frontend |
+| US public service | USWDS |
+| Accessible custom React app | Radix primitives or shadcn/ui, adapted away from defaults |
+
+One system per project. Check the repo's dependency files before importing anything. If the package is missing, either install it or use the existing stack and record the reason.
+
+When the brief is an aesthetic rather than a system, build with the project's stack and state what is inspiration versus official design-system use. Glass, bento, editorial, brutalist, kinetic, and dark-tech directions are aesthetic lanes, not packages.
+
+## Turn references into a direction
+
+Do not copy a reference composition. Extract:
+
+- A color/material strategy.
+- A type and hierarchy strategy.
+- A layout grammar.
+- A motion grammar.
+- An asset grammar.
+- A list of tells to avoid.
+
+Then write the direction contract into `.tastemaker/style-lock.md` and the build stamp. The contract should be recognizable even if all copy is removed.
+
+## If no user references exist
+
+You still need a quality bar. Use the reference board lanes above and search current sources when tools allow it. When search is not available, derive the board from the product's world and mark it as inferred. This keeps the work grounded without blocking the build.
+
+## Do not
+
+- Do not ask the user for CSS values, color preferences, or font names unless the brand requires them.
+- Do not default to a familiar category treatment just because the user gave no references.
+- Do not treat a generated image or reference screenshot as a promise to copy. It is a quality bar and grammar source.
+- Do not invent customer logos, metrics, quotes, or public proof while building a reference-led surface.