@palate/cli 0.0.0-stage → 0.0.2

package/kb/moves/pointer-highlight-word.md

@@ -0,0 +1,56 @@
+---
+id: pointer-highlight-word
+name: Pointer-highlight headline word
+kind: type
+fits: [saas, developer, ai, productivity, crafted, friendly, technical, launch]
+avoid: [heritage, luxury, serious-news, crisis, finance-trust-first]
+signature: false
+effort: s
+perf: "two CSS keyframe animations (clip-path on a box, transform/opacity on a cursor), one-time, ~2 s total; no JS"
+a11y: "box and cursor are aria-hidden; the word stays plain text; under reduced motion both simply show"
+pairs_with: [self-playing-product-demo, playful-404, calm-motion-system]
+deps: none
+---
+
+## What it is
+
+One word in the headline gets a selection box drawn around it (the box reveals from its top-left corner), then a small cursor glides in and lands on the box's top-right corner, as if someone (an agent, a collaborator) just selected that word. Pure CSS, plays once on load.
+
+## Why it works
+
+- It puts the product's action into the headline: a design/agent tool *selects and works on things*, and the word that matters is the one being worked on.
+- It directs the eye to the one word that carries the message, without colour shouting.
+- It's small, quick and finishes: a flourish, not a show.
+
+## When to use / when not
+
+Use for tools whose core gesture is selecting, pointing, editing or collaborating (design tools, agents, editors, whiteboards). Highlight the one word that is the product's claim. Reuse it on the 404 or a closing line to make the site feel like one voice; never more than one per screen.
+
+Not for: heritage, luxury or serious-news brands (it reads as software UI), or headlines where no single word carries the meaning. Avoid on long multi-line headlines where the box would break across lines.
+
+## Recipe
+
+1. Wrap the word: `<span class="relative inline-block">` containing (a) the box, `aria-hidden`, `absolute`, inset slightly beyond the word (`-inset-x-[0.1em] top-[0.06em] bottom-[-0.02em]`), 8 px radius, 1.5 px brand border, 5% brand fill; (b) the word in a `relative` span; (c) the cursor, `aria-hidden`, positioned `bottom: 100%; left: 100%` with a −10 px margin so its tip sits on the box's top-right corner.
+2. The cursor: an arrow drawn in your own SVG, rotated so its tip points down-left at the corner, brand fill, 1.5 px white stroke, a soft drop shadow (`0 2px 4px` brand-deep at 25%).
+3. Keyframes: box `clip-path: inset(0 100% 100% 0 round 8px)` → `inset(0 0 0 0 round 8px)` over 0.9 s, `cubic-bezier(0.22, 1, 0.36, 1)`, delay 0.55 s; cursor from `opacity:0; translate(44px, -28px)` to rest over 0.75 s, same curve, delay 1.2 s; both `both` fill.
+4. Wrap both animations in `@media (prefers-reduced-motion: no-preference)`; otherwise they're simply visible. No JS, so server and client render identically.
+5. On a painting or dark hero, a light tone: white border at 90%, white fill at 12%.
+6. Keep the word unbroken: `inline-block` stops the box splitting across lines; check that the headline wraps well at 390 px with the word on one line.
+
+## Pitfalls
+
+- Highlighting a filler word, or two words: it must be the claim.
+- A cursor that overlaps the line above at small widths: check the gap above the headline.
+- Animating it on every scroll into view: once, on load.
+- Using an icon library's cursor: draw your own arrow so it matches stroke weights.
+
+## How to verify
+
+- `palate animate --check`: box reveals then cursor arrives by ~2 s; no layout shift (both are absolute); reduced motion shows the final state immediately.
+- `palate shoot` at 390: the word doesn't break; the cursor isn't clipped by the hero edge.
+- Screen reader reads the headline as plain text.
+
+## Examples
+
+- palate's own site: "intelligence" in the hero headline and "exist" on the 404 (`PointerHighlight.tsx`).
+- Seen on Aceternity UI (https://ui.aceternity.com): a component library that offers a pointer-highlight text effect; palate's version is its own CSS in its brand colour.

package/kb/moves/product-in-context.md

@@ -0,0 +1,56 @@
+---
+id: product-in-context
+name: Product in context, no device frame
+kind: imagery
+fits: [honest, saas, productivity, consumer, b2b, calm, crafted, ai]
+avoid: [hardware, luxury, experimental]
+signature: false
+effort: m
+perf: "real UI rendered as HTML or one optimised image per crop; no device-mockup PNGs; lazy below the fold"
+a11y: "a caption says what the moment shows; live UI fragments are inert (inert or aria-hidden) with a text description"
+pairs_with: [screenshot-detail-crops, hand-drawn-annotations, museum-painting-backdrop, bento-live-tiles]
+deps: none
+---
+
+## What it is
+
+Instead of a laptop or phone mockup, the product appears as the actual moment it's used: a real notification over a real message, the invoice row sitting in the email it came from, a fragment of the UI cropped tight and placed on a meaningful background. No bezels, no stock hands, no floating devices.
+
+## Why it works
+
+- Device frames say "here is a screen"; the context says "here is your Tuesday with this product". The second is what people buy.
+- Removing the frame frees the space for larger, readable UI.
+- Mockup kits are a generic look; real context belongs to this product only.
+
+## When to use / when not
+
+Use for software where the value happens at a specific moment (a reply drafted, a payment matched, a deploy passing) and that moment can be shown in a fragment.
+
+Not for hardware (show the device itself), and not for luxury brands where the photography is the product. Avoid if you can't show real UI: an invented fake UI in context is worse than a plain screenshot.
+
+## Recipe
+
+1. **List three moments** where the product does its job, in the user's words ("the meeting notes arrive before I'm back at my desk").
+2. **Build each moment as a fragment.** Recreate the relevant piece of real UI in HTML/CSS at 1:1 (or render a crisp screenshot crop at 2x): one card, one row, one toast. Real names and values from the project's seed data, never lorem.
+3. **Place it on context.** Behind the fragment: a calm surface that says where it lives (a blurred desktop wallpaper you own, a CC0 painting, a soft tint of the brand, or the neighbouring app it integrates with drawn as a quiet grey outline). Keep the background lower in contrast than the fragment.
+4. **Depth without a device.** One soft shadow (`0 1px 2px rgba(0,0,0,.08), 0 24px 48px -16px rgba(0,0,0,.25)`), 12–16px radius, 1px hairline. The fragment may break out of its container slightly to feel placed, not pasted.
+5. **Caption.** A one-line caption under each scene: what's happening and when.
+6. **Optional life.** A single entrance (fragment rises 8px and fades in, 320ms, `cubic-bezier(0.23,1,0.32,1)`) when it scrolls in, once. Static under reduced motion; HTML fragments render complete without JS.
+7. **Phone.** Scale fragments down with `font-size` in em units on a container (`font-size: calc(100cqw / 40)`) so the whole UI scales, not just the box.
+
+## Pitfalls
+
+- Mixing device mockups and frameless fragments on one page.
+- Lorem, John Doe, or $1,234.56: fake data kills the honesty this move depends on.
+- Busy backgrounds behind dense UI.
+- Fragments too small to read: crop tighter instead of shrinking.
+
+## How to verify
+
+- `palate shoot` 1440/390: each fragment's text is ≥12px rendered and readable; no device frames anywhere.
+- `palate details`: real names, avatars and values in every fragment.
+- JS off: fragments are visible in their final state.
+
+## Examples
+
+- palate's own site: feature rows show real slices of palate's UI (the point overlay, critique board, triage verdicts) in windows on paintings rather than in device frames.

package/kb/moves/real-world-data.md

@@ -0,0 +1,58 @@
+---
+id: real-world-data
+name: The page knows the world outside
+kind: data
+fits: [local, travel, food, nature, events, sustainability, warm, friendly, crafted]
+avoid: [enterprise-compliance, finance-trust-first, clinical, low-bandwidth, crisis]
+signature: true
+effort: m
+perf: "one server-side fetch, cached 10–30 min; never block render on a third-party API; no client geolocation prompt"
+a11y: "the live detail is plain text in the content; visual changes (sky tint, illustration) are decorative; static under reduced motion"
+pairs_with: [time-of-day-theming, footer-live-status, live-data-ticker]
+deps: "none; a free weather or sunrise API called from the server (check its terms and attribution requirement)"
+---
+
+## What it is
+
+The page reflects a real, current fact about the physical world that matters to the product: the weather at the farm the coffee comes from, tonight's sunset at the venue, the tide at the surf school, the air quality where the studio is. One line of copy and, optionally, a small visual shift tied to it.
+
+## Why it works
+
+- It proves there is a real place and real people behind the screen; it's the opposite of a template.
+- It changes between visits, which gives returning visitors a reason to look again.
+- When it connects to the product's job ("good drying weather at the roastery: today's batch ships Friday"), it becomes information, not a gimmick.
+
+## When to use / when not
+
+Use for local businesses, hospitality, travel, food and drink, outdoor and nature brands, events, sustainability products, and studios with a sense of place.
+
+Not for: products where the world outside is irrelevant (it reads as a gimmick), finance or compliance-heavy pages, crisis contexts, or when the API is flaky. Never ask the visitor for their location for this.
+
+## Recipe
+
+1. **Choose a fact tied to the product and a place you own** (your farm, venue, office), not the visitor's location. One fact. Write the sentence for each state first: sunny, rain, night, unknown.
+2. **Fetch on the server** (Next: a route handler or server component with `fetch(url, { next: { revalidate: 1800 } })`; Vite: an edge function) and cache 10–30 minutes. Respect the API's rate limits and attribution rules; show attribution where required.
+3. **Fallback first.** If the fetch fails or times out (> 800 ms), render the timeless sentence ("Our roastery is in the hills above Huila."). The page never waits on the API.
+4. **Render as text** in the flow: "It's 18 °C and drizzling at the roastery right now." Include a `<time>` for when it was measured.
+5. **Optional visual tie-in**: one CSS custom property set from the data on the server (`--sky: #cfd8dc` for overcast), used by a hero tint or illustration. No canvas weather effects, no particle rain.
+6. **Units and locale**: format with `Intl.NumberFormat` and show both °C/°F only if your audience needs both.
+7. **A11y and motion**: the information is in the sentence; the visual shift is decorative. Under reduced motion there is no animated weather.
+8. **Privacy**: no client geolocation, no IP lookup. The place is yours.
+
+## Pitfalls
+
+- Data from the visitor's location: a permission prompt or an IP lookup for a novelty.
+- Stale data presented as live (cache for hours, still says "right now"). Say "this morning" or show the time.
+- A broken API leaving "undefined °C" in the hero.
+- Weather particle effects that cost CPU and battery.
+- A fact with no link to the product, which reads as a widget.
+
+## How to verify
+
+- Force the fetch to fail: the fallback sentence renders, no layout shift.
+- `palate shoot` at both widths: the line wraps cleanly with the longest state ("Light thunderstorms").
+- The rendered time is within the cache window of the API's timestamp.
+
+## Examples
+
+- No palate example yet. Describe it to the builder with the place, the fact and the four sentences.

package/kb/moves/referral-reward-reveal.md

@@ -0,0 +1,59 @@
+---
+id: referral-reward-reveal
+name: The referral link as the reward
+kind: interaction
+fits: [waitlist, launch, community, consumer, saas, ai, honest, friendly]
+avoid: [enterprise-compliance, government, clinical, finance-trust-first, luxury]
+signature: false
+effort: m
+perf: "the link comes back in the join response; no extra request; copy is local"
+a11y: "the link is real selectable text with an sr-only label; the copy button keeps its size and announces 'Copied'"
+pairs_with: [waitlist-position-live, copy-confirmation, confetti-free-celebration]
+deps: none
+---
+
+## What it is
+
+Right after joining, the visitor gets their own link and one sentence about what it does: "Each designer who joins with your link moves you up." The link is shown, ready to copy, as part of the result rather than buried in a later email.
+
+## Why it works
+
+- The moment after a commitment is when people are most willing to act again; asking then converts far better than asking in an email days later.
+- The reward is concrete and tied to the thing they just chose (their place in line), so sharing feels like helping themselves, not doing marketing.
+- Showing the link (not just a "Share" button) makes it tangible and trustworthy: you can see exactly what you'd send.
+
+## When to use / when not
+
+Use for waitlists and invite-only launches where moving up is real, and for products where users naturally know others who'd want it.
+
+Not for: regulated or enterprise products, anything where referrals could be read as spam incentives, or when you can't enforce fair counting. Never promise a reward the system doesn't deliver.
+
+## Recipe
+
+1. **Fair counting on the server.** A referral counts only if it isn't a self-referral (compare canonical emails, so aliases don't count), doesn't come from the referrer's own IP, and stays under caps (per IP per day, per company domain per referrer). Store `referred_by` and `ref_counted` on the new sign-up; the queue orders by counted referrals.
+2. **Remember the incoming ref.** On page load, read `?ref=CODE`, validate it (`^[0-9A-Za-z]{8,16}$`) and keep it in `localStorage`, so it still counts if the friend joins later or from another page. Wrap storage in try/catch.
+3. **The reveal.** In the result panel, under the position: the one-line promise, then the link as text, not an input (an input zooms phones on focus). Show it without `https://`; if it doesn't fit, truncate the domain and always keep the `?ref=CODE` part visible (two spans: a truncating one and a `shrink-0` one). `select-all` so one click selects it; `title` holds the full URL; an `sr-only` "Your link:" label.
+4. **Copy button** beside it at the same 40 px height (see `copy-confirmation`): it confirms "Copied" for ~1.8 s without changing width.
+5. **Native share where it exists** (optional): on touch devices with `navigator.share`, a "Share" button next to Copy; otherwise just Copy.
+6. **Motion.** The share block arrives with the result panel (same cross-fade). No separate fanfare; under reduced motion everything is a plain fade.
+7. **Say what happens next** in the confirmation email too, with the same link.
+8. **No JS:** the server-rendered result page shows the same link as selectable text.
+
+## Pitfalls
+
+- Rewards that can be gamed with aliases (`you+1@`), so honest users fall behind.
+- Share buttons for six networks: one link and Copy is enough.
+- A long URL that wraps to three lines on a phone and hides the code.
+- Promising "skip the line" when referrals only move you a little; say what it does.
+- Putting the ref code in analytics with personal data.
+
+## How to verify
+
+- Unit tests on the counting rules: self-referral, same IP, alias and cap cases don't count.
+- `palate shoot` at 320/390: the code part of the link is always visible.
+- Copy works on an insecure origin (fallback) and the button never changes width.
+- Visiting with `?ref=` then joining later in the same browser credits the referrer.
+
+## Examples
+
+- palate's own site (`Waitlist.tsx`, `lib/server/waitlist.ts`): after joining, "Each designer who joins with your link moves you up." with the link as selectable mono text and a Copy button; referrals only count when they aren't self-referrals, repeat IPs or aliases.

package/kb/moves/riso-print-texture.md

@@ -0,0 +1,57 @@
+---
+id: riso-print-texture
+name: Riso print texture
+kind: texture
+fits: [playful, crafted, artsy, retro, warm, cultural, events, music, publishing]
+avoid: [finance-trust-first, enterprise-compliance, clinical, serious-news, data-dense-tool]
+signature: true
+effort: m
+perf: "one tiny SVG noise tile (data URI, < 1 KB) per ink, static; mix-blend-mode on a few elements only, never on scrolling full-page layers"
+a11y: "decorative; text keeps 4.5:1 against the paper colour ignoring the grain; misregistration never applied to body text"
+pairs_with: [halftone-dot-imagery, hand-drawn-annotations, generative-brand-pattern, layered-paper-depth]
+deps: none
+---
+
+## What it is
+
+The look of a risograph print on screen: two or three flat spot inks (fluorescent pink, blue, yellow, green) laid on off-white paper, overprinting where they cross, with grainy coverage and a slightly off registration between layers. Shapes, illustrations and headings are built from the inks, never from gradients.
+
+## Why it works
+
+- Spot inks and overprint read as *made*, physically and in a small run, which signals a person and a point of view rather than a template.
+- A limited ink set is a real constraint: it forces a palette with a dominant colour and sharp accents, which the default look never has.
+- Grain and misregistration add warmth and texture at almost no cost, and give flat illustrations depth through overlap instead of shadows.
+
+## When to use / when not
+
+Use for events, zines, music, publishing, cultural institutions, indie tools and launches that want a hand-made, slightly irreverent voice. Strong on posters-as-pages: a festival line-up, an issue launch, a book.
+
+Not for: finance or health products that must look precise and safe, compliance-heavy enterprise, serious news, or dense tools (grain behind data reads as dirt). Don't combine with glossy 3D or glassmorphism: two material languages fight.
+
+## Recipe
+
+1. **Pick the inks.** Two or three, named after real riso colours: e.g. fluorescent pink `#ff48b0`, medium blue `#0078bf`, yellow `#ffe800`. Paper `#f4efe6` (warm off-white). Text in a dark ink, not black: blue `#1b2a6b` or a deep teal. Define them as CSS variables (`--ink-1`, `--ink-2`, `--paper`) and use nothing else for colour.
+2. **Overprint with multiply.** Layer shapes and illustration parts in different inks with `mix-blend-mode: multiply` on the upper layer, so pink over blue makes a purple overlap, as real ink does. Keep blend modes on a handful of elements inside one `isolation: isolate` container.
+3. **Grain the coverage.** One SVG tile with `feTurbulence` (`baseFrequency` ≈ 0.9, `numOctaves` 2) thresholded through `feComponentTransfer` (a steep `discrete` or `table` alpha), used as a `mask-image` on ink shapes, so solid fills break up into speckled coverage at the edges. Write your own filter; keep the tile 160–200px and `stitchTiles="stitch"`.
+4. **Misregister.** Offset one ink layer by 1–3px (`translate(2px, -1px)`) and, on display headings only, render the word twice: the base in ink 1, a copy in ink 2 with `aria-hidden`, multiply, offset 2px. Never on body text.
+5. **Halftone for tones.** Where you need shading, use dots (see `halftone-dot-imagery`) in one ink rather than opacity.
+6. **Tailwind.** Add the inks to `@theme` (`--color-ink-pink` etc.) and a `.riso-grain` component class carrying the mask; React: an `<Ink color="pink" offset={[2,-1]}>` wrapper that sets the blend and offset.
+7. **Fallbacks.** No JS is needed. If `mix-blend-mode` is unsupported, colours still show flat. Nothing moves, so reduced motion is unaffected; if you add a hover that shifts registration, wrap it in `prefers-reduced-motion: no-preference`.
+
+## Pitfalls
+
+- Too many inks: past three it stops looking like riso and starts looking like a theme.
+- Grain on text or behind long copy: it hurts reading. Grain the shapes, keep text crisp on paper.
+- Pure black: riso doesn't have a "black" look; use a dark ink.
+- Blend modes on large fixed or scrolling layers: repaint cost on every scroll frame.
+- Gradients sneaking in from the old palette.
+
+## How to verify
+
+- `palate shoot` both widths: only the declared inks appear (sample colours), overlaps show the multiplied third colour, text contrast passes on paper.
+- Zoom 200% on a shape edge: speckled coverage, not a smooth antialiased edge.
+- Scroll with the performance panel: no large repaint areas from blend layers.
+
+## Examples
+
+- The pattern is common on independent publishers' and festival sites that print in riso; describe it to a builder as "two spot inks, multiply overprint, grainy coverage, 2px misregistration on headings".

package/kb/moves/screenshot-detail-crops.md

@@ -0,0 +1,56 @@
+---
+id: screenshot-detail-crops
+name: Detail crops instead of full screenshots
+kind: imagery
+fits: [crafted, developer, saas, productivity, honest, technical, minimal, premium]
+avoid: [playful-kids, consumer, luxury]
+signature: false
+effort: s
+perf: "small cropped images at 2x (AVIF/WebP), or live HTML fragments; each far lighter than a full screenshot"
+a11y: "each crop has alt text describing the detail and why it matters; text inside crops is also in the caption"
+pairs_with: [product-in-context, hand-drawn-annotations, bento-live-tiles, editorial-grid-pull-quotes]
+deps: none
+---
+
+## What it is
+
+Show the product through tight, magnified crops of its best details (the keyboard shortcut hint, the empty state, the diff view's line numbers, the way a chart labels its last value) at 150–250% scale, each with a short caption. A full-screen screenshot appears at most once.
+
+## Why it works
+
+- Full screenshots shrink text to unreadable and show everything at the same priority. A crop chooses what matters.
+- Magnified details demonstrate craft directly: people trust a product whose small parts are clearly cared for.
+- Crops give a consistent rhythm of images that are easy to lay out on any grid.
+
+## When to use / when not
+
+Use for tools whose quality lives in details: developer tools, editors, design tools, productivity apps. Great for "what's new" pages and feature sections.
+
+Not for consumer products where the emotional whole matters more than parts, or when the UI isn't yet polished (magnification exposes flaws). Not a replacement for showing the product working at least once.
+
+## Recipe
+
+1. **Shoot the real UI** at device pixel ratio 2 or 3 (palate shoot or Playwright `deviceScaleFactor: 2`), in a clean seed state with real content.
+2. **Choose 4–6 details** that each prove one claim. Write the claim first, then find the pixels.
+3. **Crop** each to a consistent aspect (4:3 or 1:1) with the detail roughly on a third, with some context around it. Export at the display size × 2 as AVIF/WebP, 40–120 KB each.
+4. **Frame.** 12–16px radius, 1px hairline border (`rgba(0,0,0,.08)`), on the page background or a very light tint. No shadows stacking, no device chrome.
+5. **Caption.** 14–15px under each crop: the claim in one line ("Every shortcut is shown where you need it").
+6. **Optional:** for live detail, render the fragment as HTML scaled up with `transform: scale(1.75)` on a fixed-size inner box and `transform-origin` set to the detail; this stays crisp at any DPR. Make it inert.
+7. No JS required; images use `loading="lazy"` and explicit `width`/`height`.
+
+## Pitfalls
+
+- Upscaling a 1x screenshot: blurry crops destroy the point.
+- Crops with no caption: people don't know what they're looking at.
+- Inconsistent zoom levels across crops: the set looks accidental.
+- Cropping out every bit of context so it's unrecognisable as the product.
+
+## How to verify
+
+- `palate shoot` at 1440: crops are sharp (no visible resampling at 100%), all one aspect ratio, captions present.
+- `palate details`: alt texts are specific, not "screenshot".
+- Total image weight of the section is below the weight of one full-page screenshot.
+
+## Examples
+
+- No public example cited; widely used on changelogs and feature pages of developer and design tools.

package/kb/moves/scroll-progress-chapters.md

@@ -0,0 +1,57 @@
+---
+id: scroll-progress-chapters
+name: Scroll progress as chapters
+kind: navigation
+fits: [editorial, publishing, media, education, calm, serious, docs, nonprofit]
+avoid: [minimal, playful-kids, ecommerce, daily-tool]
+signature: false
+effort: s
+perf: "CSS scroll-driven progress where supported; otherwise one IntersectionObserver for the active chapter and a passive, rAF-throttled scroll read for the bar"
+a11y: "a real nav of anchor links with aria-current; the progress bar is decorative (aria-hidden); no motion under reduced motion beyond the bar's position"
+pairs_with: [story-led-long-scroll, editorial-grid-pull-quotes, sticky-scroll-story, editorial-drop-cap]
+deps: none
+---
+
+## What it is
+
+A thin progress indicator for a long read that is divided into named chapters: a slim rail (top or side) whose segments are the chapters, filling as you read, with the current chapter's name shown and every chapter one click away. It tells the reader where they are, how much is left and what's coming.
+
+## Why it works
+
+- Long pages lose people when the end is invisible; showing that the essay has five parts and they're in part three makes finishing feel achievable.
+- Named chapters are a table of contents that stays with you: it doubles as navigation and as a preview of the argument.
+- It respects readers who skim: they can jump to the part they care about.
+
+## When to use / when not
+
+Use on long essays, reports, case studies, manifestos, story-led landing pages and long docs guides (more than ~4 screens, at least 3 clear parts).
+
+Not for: short pages (a progress bar on two screens is noise), shops, and minimal sites where any chrome is too much. Don't use a bare generic top progress bar without chapters; the chapters are the point.
+
+## Recipe
+
+1. **Structure.** Each chapter is a `<section id="…" aria-labelledby>` with an `<h2>`. Build the chapter list from the headings at render time (server), so the nav exists without JS.
+2. **Rail.** Desktop: a fixed left rail (≥ 1280px wide viewports) listing chapter names in 13–14px, the current one in full ink, others at ~55% opacity, each with a 2px vertical track segment whose fill grows as you read it. Below that width: a 2px bar under the sticky header, split into segments with 2px gaps, plus the current chapter name in the header ("3 / 5 · The cost of waiting").
+3. **Progress (CSS first).** Where scroll-driven animations exist (Chromium 115+, Safari 26+), each segment fill uses `animation: fill linear both; animation-timeline: view(); animation-range: contain 0% contain 100%` on a `view-timeline` named per section (`view-timeline-name: --ch3` on the section, `timeline-scope` on a common ancestor). `@keyframes fill { from { transform: scaleX(0) } to { transform: scaleX(1) } }` with `transform-origin: left`.
+4. **Fallback (JS).** Feature-test `CSS.supports("animation-timeline: view()")`. Otherwise: passive scroll listener, read once per rAF, compute each section's `(viewportMid − top) / height` clamped 0–1, write `transform: scaleX(p)` per segment.
+5. **Active chapter.** IntersectionObserver with `rootMargin: "-45% 0px -50% 0px"`; the intersecting section sets `aria-current="true"` on its link and updates the header label.
+6. **Jump.** Links are plain `#anchors`; `scroll-margin-top` on sections equals the sticky header height + 16px. Smooth scrolling only under `prefers-reduced-motion: no-preference`.
+7. **Reduced motion / no JS.** The rail and links work; fills just update (no easing needed, they track scroll). Without JS and without scroll timelines, segments stay empty and the links still navigate.
+
+## Pitfalls
+
+- Chapter names that are vague ("Introduction", "More"): the rail becomes useless. Name them like headlines.
+- A fixed rail overlapping text on mid-size screens: only show it when there's a real gutter (≥ 200px).
+- Animating `width` per scroll event: use `transform: scaleX`.
+- Too many chapters (10+): group them, or this becomes a docs sidebar.
+
+## How to verify
+
+- `palate shoot` at 1440 and 390: rail or header bar visible, no overlap with the text column.
+- Scroll through: the segment fill tracks reading position; the current chapter label changes at each heading.
+- Keyboard: Tab to the chapter links, Enter jumps and the heading isn't hidden under the header.
+- JS off: links present and working.
+
+## Examples
+
+- The pattern: a long annual report where a hairline rail on the left lists its five chapters and fills each one as you read it.

package/kb/moves/scroll-scrubbed-product-film.md

@@ -0,0 +1,62 @@
+---
+id: scroll-scrubbed-product-film
+name: Scroll-scrubbed product film
+kind: motion
+fits: [cinematic, hardware, premium, bold, launch, consumer, crafted]
+avoid: [low-bandwidth, data-dense-tool, accessibility-first, daily-tool, docs]
+signature: true
+effort: l
+perf: "one muted H.264 with a keyframe every frame (or a WebP sequence ≤ 90 frames), decoded once; currentTime/drawImage only, throttled to rAF; nothing loads until the section is 1.5 screens away"
+a11y: "decorative film with a text equivalent beside it; reduced motion and no JS show the key frame as a still; never traps scroll"
+pairs_with: [sticky-scroll-story, product-in-context, calm-motion-system, story-led-long-scroll]
+deps: none
+---
+
+## What it is
+
+A short product film whose playhead is the scroll position: as the reader scrolls through a tall pinned section, the object turns, opens, assembles or the screen state advances, frame by frame, and stops when they stop. The reader directs the film, so a three-second shot becomes something they explore.
+
+## Why it works
+
+- Agency: people trust what they control. Scrolling backwards to watch the hinge close again is a moment they choose, and that is what they remember.
+- It turns the one gesture everyone already makes (scroll) into the product demo, with no buttons and no learning tax.
+- A physical object rendered well, under the reader's hand, reads as premium in a way a looping video never does: the pace matches theirs.
+
+## When to use / when not
+
+Use for a launch page of a physical or visually rich product (hardware, a device-free app reveal, a generated artwork), once per page, where the film itself is the argument: "look how it unfolds".
+
+Not for: tools people use daily (they want the facts, fast), docs, pages read on slow connections or old phones (the film is megabytes), or anything where the information inside the film is not also in text. Never two scrubbed films on one page.
+
+## Recipe
+
+1. **Shoot or render for scrubbing.** 2–4 seconds, 24–30 fps, one continuous camera move. Export two ways and pick one:
+   - *Video*: H.264 MP4, every frame a keyframe (`-g 1` in ffmpeg), muted, 1280 wide desktop / 720 wide phone, typically 2–6 MB. Seeking is instant because there's nothing to decode between keyframes.
+   - *Image sequence*: 60–90 WebP frames at 1200px, quality ~70; better on iOS Safari, which can seek MP4s jerkily.
+2. **Section.** A wrapper `height: 300vh` (about 100vh of scroll per second of film) with a child `position: sticky; top: 0; height: 100vh` that holds the `<video>` or a `<canvas>`. Copy for each beat sits beside or over it (see `sticky-scroll-story`).
+3. **Progress.** `p = clamp((scrollY − wrapperTop) / (wrapperHeight − innerHeight), 0, 1)`. Prefer CSS scroll-driven animations for anything purely visual (`animation-timeline: view()`), but the film needs JS: read progress in a passive scroll listener, store it, and apply it once per `requestAnimationFrame`.
+4. **Apply.** Video: `video.currentTime = p * duration`, only if it changed by more than half a frame. Sequence: `ctx.drawImage(frames[Math.round(p * (n − 1))], …)` on a canvas sized to `devicePixelRatio` (cap at 2). Smooth a little: ease the displayed frame toward the target with `k = 1 − exp(−dt / 60ms)` so trackpad jitter doesn't stutter.
+5. **Loading.** Nothing until an IntersectionObserver with `rootMargin: "150% 0px"` fires. Then `preload="auto"` the video (or fetch frames in order: every 8th frame first, then fill in, so early scrubs show something). Show the poster frame until enough has loaded.
+6. **Fallbacks.** The server markup is the *key frame* as an `<img>` with real `alt` and the beat copy as plain text, wrapper at normal height. Only when JS runs, motion is allowed (`prefers-reduced-motion: no-preference`) and the media is ready does the wrapper become 300vh. Reduced motion and no JS keep the still. `prefers-reduced-data` (Chromium only) or `navigator.connection.saveData`: keep the still too.
+7. **Phones.** Shorter wrapper (200vh), smaller asset, and test iOS Safari: if seeking stutters, switch that breakpoint to the image sequence.
+
+React/Tailwind notes: one `useScrubbedFilm(ref, src)` hook owning the observer, listener and rAF; `className="relative h-[300vh]"` and `sticky top-0 h-svh` (use `svh` so mobile toolbars don't jump it).
+
+## Pitfalls
+
+- Default-encoded MP4 (keyframe every 2–10 s): every seek decodes from the last keyframe and the film lurches. Re-encode with all keyframes.
+- Hijacking scroll (wheel listeners, `preventDefault`, smooth-scroll libraries) to "fix" pacing: it breaks trackpads, keyboards and assistive tech. Never.
+- Making the section 600vh+: the reader feels stuck. About 100vh per second of film, max ~3 screens.
+- Information only inside the film (a spec that appears at frame 40): it must also be text.
+- Starting the download at page load: it fights the hero for bandwidth and hurts LCP.
+
+## How to verify
+
+- `palate animate --check`: scroll strip shows the frame advancing with scroll and holding when scroll stops; reduced motion and JS-off strips show the key frame still and the section at normal height; no layout shift when the media arrives.
+- `palate shoot` at 390 and 1440: the sticky frame fills the viewport without cropping the object; copy readable.
+- Network panel: no film bytes before the section is ~1.5 screens away; total under ~6 MB.
+- Scroll backwards fast: no blank frames, no stutter on a trackpad.
+
+## Examples
+
+- Seen on Apple's product pages (https://www.apple.com): devices turn, open or come apart as you scroll through a pinned section, driven frame by frame by the scroll position.

package/kb/moves/self-playing-product-demo.md

@@ -0,0 +1,61 @@
+---
+id: self-playing-product-demo
+name: Self-playing product demo built in code
+kind: hero
+fits: [saas, developer, ai, productivity, b2b, technical, honest, crafted, launch]
+avoid: [heritage, luxury, low-bandwidth, crisis]
+signature: true
+effort: l
+perf: "HTML/CSS in the page (no video bytes); state machine on timers, paused off screen and while hovered; transforms and opacity for movement; one em grid so it scales with one font-size"
+a11y: "an sr-only summary of the whole run plus an aria-live line naming the current step; finished state under reduced motion and without JS; pauses while hovered or focused"
+pairs_with: [scroll-scrubbed-product-film, bento-live-tiles, product-in-context, honest-progress-narration]
+deps: "optional: motion (framer-motion) if the project already uses it, for enter/exit; plain CSS transitions work"
+---
+
+## What it is
+
+The product's main flow, rebuilt as real HTML and played by a small script: a request typed, the plan, the work happening, the result, a fix, a lesson learned. It loops on its own while in view, pauses when the visitor hovers or focuses inside it, and renders its finished state on the server, without JavaScript and under reduced motion. It is not a video: it is crisp at any size, themable, and real text.
+
+## Why it works
+
+- People believe what they see working. A demo that runs the real flow with real content beats every claim on the page.
+- Code-built UI stays sharp, small and consistent with the brand; it can be updated with the product.
+- Looping without controls (no Skip/Replay) keeps it ambient; pausing on hover lets a curious visitor study a frame.
+
+## When to use / when not
+
+Use when the product has a flow you can show in 15–30 seconds and the page's job is to make that flow understood: tools, agents, developer products. Make it the most premium thing on the page, right under the hero.
+
+Not for: products whose value is physical or emotional (use photography), or when you can't keep it truthful (a demo that does things the product can't is a lie).
+
+## Recipe
+
+1. **Write the script as data.** A `DemoState` type with every visible variable (phase, step counters, cursor `{x, y, down} | null`, typed characters), a `START` state (never blank: the request already typed, the app as it is today) and an `END` state (everything done). The server renders `END`.
+2. **One em grid.** Size the stage with a container (`@container`, fixed aspect like 16/10) and set the inner `font-size: calc(100cqw / 40)` so 1em = 1/40 of the width. Position every part, cursor and annotation in em: cursors land exactly on the parts they act on at every width.
+3. **The engine** (`useDemo`): in a layout effect, if reduced motion, mark reduced and stay at `END`; else set `START` before first paint and observe the root with an IntersectionObserver (`rootMargin: "0px 0px -40% 0px"` so it starts once well up the screen). On first visibility start run 1.
+4. **Beats.** An async function walks `[delayMs, patch][]` with `await sleep(ms)` and `setState(prev => ({...prev, ...patch}))`, checking a `dead` flag after each await; typing is a loop of 38 ms per character (160 ms for the first). Every patch sets absolute state, so pausing or remounting never leaves it inconsistent. Keep the whole run 15–25 s.
+5. **Loop politely.** After the end, hold 4–5 s, then wait while the visitor is inside (pointerenter/focusin), it's off screen, or `document.hidden`; then increment the run counter to replay.
+6. **Entrances only once playing.** A context flag `played`: before the first run, components render with no enter animation (`initial={false}`), so the server/no-JS view is complete and static.
+7. **Craft the frames**: a real prompt box with a caret, a "Thinking…" shimmer, tool-call rows with spinners turning to checks, the product page building section by section, a pointer that travels and clicks (scale-down on press), states appearing. Ease-out curves (`cubic-bezier(.23,1,.32,1)`), 180–320 ms for UI changes.
+8. **A11y.** An sr-only paragraph narrating the whole run, an sr-only `aria-live="polite"` line with the current step name, `aria-hidden` on the decorative stage, and a visible note under reduced motion ("Motion is reduced, so this is the finished run").
+9. **CSS keyframes** for carets, shimmers, spinners, under `prefers-reduced-motion: reduce` turned off (spinners slowed instead).
+10. **Prevent scroll jumps:** `overflow-anchor: none` on `html` if the demo changes height while playing.
+
+## Pitfalls
+
+- Starting from blank: the first frame visitors see must already say something.
+- A demo that lies (instant results, features that don't exist): visitors who sign up find out.
+- Skip/Replay buttons and progress bars: they make it a video player; let it loop.
+- Layout that only works at one width: use the em grid, test at 390 px.
+- Running when off screen: wasted CPU and the visitor arrives mid-run. Pause off screen.
+
+## How to verify
+
+- `palate animate --check`: the strip shows the run progressing; no layout shift; reduced motion and JS off show the complete end state.
+- Scroll it in and out: it starts when well in view, pauses off screen, waits while hovered.
+- `palate shoot` at 390: cursors still land on their targets; nothing is clipped.
+- Screen reader: the summary and the current step are announced.
+
+## Examples
+
+- palate's own site: the demo under the hero, one run of palate's flow (request, plan, three subagents build a team page, polish, states, a pin fixed, a rule learned), built in code and looping (`Demo.tsx`, `engine.ts`).

package/kb/moves/shape-continuity-morph.md

@@ -0,0 +1,58 @@
+---
+id: shape-continuity-morph
+name: Shape continuity (the control becomes its result)
+kind: motion
+fits: [crafted, friendly, premium, consumer, finance, productivity, tactile, calm]
+avoid: [data-dense-tool, enterprise-compliance, low-bandwidth]
+signature: true
+effort: m
+perf: "transform/opacity on one or two elements; FLIP measured once per change; no per-frame layout reads"
+a11y: "focus moves to the new surface; the change is announced (role=status or dialog semantics); reduced motion swaps instantly"
+pairs_with: [calm-motion-system, view-transitions-between-pages, confetti-free-celebration, first-win-onboarding]
+deps: "none (View Transitions); motion's layoutId only if the project already uses Motion"
+---
+
+## What it is
+
+The element you act on turns into what it opens or produces, instead of disappearing while something new appears elsewhere: a "Join" button stretches into the email field, a card grows into its detail view, "Continue" reshapes itself into "Confirm", a tray rises from the button that summoned it. One object, continuously.
+
+## Why it works
+
+- Object permanence: people track things that move continuously; a cut makes them search the screen again. Continuity tells them "this is the same thing, further along".
+- It explains cause and effect without words: you can see where the new surface came from and where it will go back to.
+- Done in one or two places, it becomes the product's motion identity; people describe it as "the way it feels".
+
+## When to use / when not
+
+Use for the two or three most important transitions in a flow: start a signup, open a detail, confirm a payment, expand a composer. Great for consumer and fintech flows where calm confidence matters.
+
+Not for: every transition (it gets slow and theatrical), dense admin tools where people do the action 200 times a day (keep those instant), or when the source and target have nothing visually in common (morphing a tiny icon into a full page reads as a zoom, not continuity).
+
+## Recipe
+
+1. **Pick the pair.** Source and target must share something: a shape, a label, a colour, a position. Write it down: "the pill button becomes the pill input; the label slides out, the placeholder slides in".
+2. **Same-document View Transitions (preferred).** Give both states the same `view-transition-name` (only one visible at a time), then wrap the state change: `document.startViewTransition(() => flushSync(() => setOpen(true)))`. Style the group: `::view-transition-group(join) { animation-duration: 280ms; animation-timing-function: cubic-bezier(.23,1,.32,1) }`. Cross-fade the inner text with `::view-transition-old/new(join-label)` at 150 ms. Supported in Chromium and Safari 18+; Firefox 144+ — feature-test `document.startViewTransition` and just set state otherwise.
+3. **FLIP fallback without the API.** Measure source rect, render target, measure target rect, apply the inverse transform (`translate` + `scale`), then transition to none over 240–300 ms. Animate scale on a wrapper and counter-scale content, or cross-fade content so text doesn't stretch.
+4. **Shared text.** When labels share letters ("Continue" → "Confirm"), split them into spans keyed by letter and position, keep shared letters, fade others (120 ms out, 180 ms in, 40 ms offset). Only do this for one hero action.
+5. **Spring, not bounce.** If using a spring: stiffness ~400, damping ~38 (≈ 0 overshoot). Overshoot reads as playful; keep it for playful brands only.
+6. **Focus and semantics.** After the morph, move focus into the new surface (the input, the dialog heading). The reverse morph returns focus to the trigger. Announce changes that aren't focus moves with `role="status"`.
+7. **Reduced motion and no JS.** Under reduce, skip the transition (call the update directly) or cross-fade at 150 ms. Without JS, the control should be a real link or form that works (a `<form>` that posts, an `<a>` to the detail page).
+
+React/Tailwind notes: `flushSync` from `react-dom` inside `startViewTransition` so React commits synchronously; if Motion is already in the project, `layoutId` on both elements does the same with less code, but don't add Motion just for this.
+
+## Pitfalls
+
+- Morphing between shapes with different border radii without animating radius: corners jump. Animate `border-radius` on the group, or keep radii equal.
+- Text stretched during a scale transform: always counter-scale or cross-fade content.
+- Two elements with the same `view-transition-name` visible at once: the transition is skipped with a console error.
+- Durations over 400 ms on a frequent action: it starts to feel slow by the third time.
+
+## How to verify
+
+- `palate animate --check` on the flow: frame strip shows one continuous shape between states (no blank frame, no jump); reduced-motion strip shows an instant or faded change.
+- Keyboard: Enter on the trigger moves focus into the new surface; Escape reverses and returns focus.
+- Click rapidly open/close five times: no stuck intermediate state.
+
+## Examples
+
+- Seen in Family, the Ethereum wallet app (described at https://benji.org/family-values): buttons reshape into the next step and trays rise from the control that opened them, so the whole app feels like one continuous object.