@palate/cli 0.0.0-stage → 0.0.2

package/kb/moves/hero-paints-itself-in.md

@@ -0,0 +1,65 @@
+---
+id: hero-paints-itself-in
+name: The hero paints itself in
+kind: hero
+fits: [calm, crafted, heritage, nature, artsy, premium, editorial, cinematic, launch]
+avoid: [data-dense-tool, finance-trust-first, enterprise-compliance, low-bandwidth, daily-tool, playful-kids]
+signature: true
+effort: l
+perf: "inline script, no framework wait; one small 3-channel PNG (the engraving) fetched with high priority; canvas drawImage per frame for ~2.3 s, then the canvas is freed; the finished image stays the LCP element underneath"
+a11y: "decorative canvas (aria-hidden); runs once per session; skipped under reduced motion, without JS, on anchor links and on slow loads; headline stays real text throughout"
+pairs_with: [line-engraving-from-image, museum-painting-backdrop, canvas-grain, engraving-colour-lens]
+deps: none
+---
+
+## What it is
+
+On the first view in a session the hero starts as blank paper; an engraving of the hero picture is drawn onto it like a pen at work (contours, then the long hatch, then crosshatch in the shadows), and a broad brush then wipes the engraving away to the painting in full colour underneath. About 2.3 seconds, once per session, never in the way of reading.
+
+## Why it works
+
+- It shows *making*, not a fade. People read pen strokes and a brush as human craft, so the page feels authored rather than generated.
+- It enacts the product's story in one gesture: line art becomes the finished, coloured thing ("the last 20%"). A hero animation that carries the brand's idea is remembered; one that is only decoration is skipped.
+- It is short and runs once: the visitor sees it, it pays off, and on every later view the page is simply the finished painting.
+
+## When to use / when not
+
+Use when the hero is a picture (a CC0 painting, a commissioned illustration, your own photograph), the brand is calm or crafted, and the product's idea is about finishing, restoring, revealing or bringing to life. It needs a picture with strong shapes (horizon, trees, figures) so the engraving reads.
+
+Not for: dashboards and tools people open daily (never animate the entry to a daily tool), trust-first finance or compliance pages, pages whose hero must show the product UI at once, or audiences on slow connections (the move stands down there anyway, so it would be wasted effort).
+
+## Recipe
+
+1. **Assets.** Engrave the hero picture with `line-engraving-from-image`, cropped to the part the hero shows at desktop and at phone width (two files). Pack the three passes into one small PNG: red channel = contours, green = the long hatch, blue = the crosshatch. One ink colour is applied at runtime. Keep each file well under 100 KB.
+2. **Markup.** The hero panel holds, in order: the finished image (`next/image` with `fill`, `priority`, `object-cover`, a known `object-position`), a paper div (`.hero-draft`, `display:none` by default, `position:absolute; inset:0`), a canvas (`.hero-paint`, `display:none`, `aria-hidden`, `suppressHydrationWarning`), the grain, the readability wash, and the content. Without the script nothing extra shows: the hero is the finished painting.
+3. **Run it from an inline script placed just before the hero**, not from a React effect, so it starts with the first paint and never waits for hydration. Build it as a self-contained function and inline `(${fn.toString()})(${JSON.stringify(config)})`. Change the page only through a constructed stylesheet (`new CSSStyleSheet()` + `document.adoptedStyleSheets`) and the canvas pixels, so hydration sees exactly the server's markup.
+4. **Stand down** (return early) when: reduced motion is on; `adoptedStyleSheets` is unsupported; the URL has a hash other than `#top` (the visitor is going somewhere else) or a comparison switch; `sessionStorage` already has the key (repeat view; set it on the first run); the engraving hasn't decoded within 300 ms of the first paint.
+5. **Paper and ink.** The constructed sheet shows the paper, hides the dark wash, and turns the white headline into ink (dark green, with a paper-coloured `text-shadow` halo of 2/6/14 px so hatching never runs through letters, as on an engraved map). CSS transitions on colour and text-shadow (160 ms) make the later flip smooth.
+6. **Size the canvas** to the visible part of the hero only (`min(panelHeight, innerHeight − top)`) at `devicePixelRatio` capped at 2. Place the engraving with the image's own cover math (`scale = max(W/iw, H/ih)`, offset by `object-position`) so every line lands on the painting.
+7. **The pen.** Unpack each channel into its own ink-on-transparent canvas. Split each pass into horizontal bands (12–16 px) and reveal each band left-to-right (or right-to-left) over 180–420 ms with an ease-out, the bands starting at staggered times: contours scattered from 0 ms, the long hatch top-to-bottom from 140 ms, the crosshatch from 520 ms. Draw only the newly revealed slice each frame with `drawImage` (source rect → dest rect). Lines *grow across the page* instead of fading in. Total ≈ 1.2 s.
+8. **Hold** ~200 ms, and until the finished image has loaded (`img.complete && naturalWidth`): the brush must have something to reveal.
+9. **The brush.** Switch the canvas to `globalCompositeOperation = "destination-out"` and drop the paper (the painting now sits under the canvas). Paint 5–10 broad strokes, one per row, alternating direction, each a slightly sloped cubic Bézier from just off one edge to just off the other, staggered over ~820 ms and 420 ms each. Each stroke is ~22 bristles: parallel offset lines with random width, alpha (some "dry" at 40%), and start/end trimmed toward the edges, so it erases like a real brush rather than a clean wipe. Use a seeded PRNG so every visitor sees the same strokes.
+10. **Flip and finish.** ~420 ms into the brush (once it has passed the headline), clear the sheet: the wash fades in and the ink turns back to white, together. When all strokes are done, fade the canvas out over 320 ms, then `display:none`, zero its size, and remove the sheet.
+11. **Fail safe.** Wrap every frame in try/catch; on any error, hide the canvas and drop the sheet: the visitor gets the finished painting.
+
+## Pitfalls
+
+- Running it from React: it starts after hydration, the visitor sees the finished painting first, then paper. It must be an inline script before the hero.
+- Hiding the LCP image or delaying it: keep the real image loading underneath with `priority`; only cover it.
+- Engraving and painting misaligned: always compute placement from the same cover math as `object-fit: cover`.
+- White headline on paper: it vanishes. Swap to ink with a halo while the paper shows.
+- Playing it on every view, or on in-page anchor jumps: once per session, never when the visitor is heading elsewhere.
+- A brush that wipes in one clean rectangle: it reads as a loading effect. Bristles, slope, dry streaks.
+- Fading lines in by opacity: it reads as a transition, not drawing.
+
+## How to verify
+
+- `palate animate --check` on a fresh session: frames show paper → lines growing → brush strokes → full painting by ~2.5 s; no layout shift; the headline is readable at every frame.
+- Reload in the same session: the finished painting, no animation. Reduced motion and JS off: the finished painting.
+- Throttle to Slow 3G: it stands down (no long paper wait).
+- `palate shoot` at 1440 and 390: both crops of the engraving line up with the painting (check mid-animation frames at the horizon).
+- LCP element is still the hero image.
+
+## Examples
+
+- palate's own site: the hero, Constable's "Wivenhoe Park, Essex" (CC0, National Gallery of Art), engraved in emerald on paper and brushed into colour on the first view of a session (`paint.ts`, `hero-paint.css`, `HeroArt.tsx`).

package/kb/moves/honest-progress-narration.md

@@ -0,0 +1,58 @@
+---
+id: honest-progress-narration
+name: Progress that narrates what's really happening
+kind: sound-free-feedback
+fits: [ai, developer, technical, saas, productivity, honest, trustworthy, calm]
+avoid: [luxury, fashion, playful-kids]
+signature: false
+effort: m
+perf: "progress comes from real events (SSE or polling ≥ 1 s); a single shimmer on the active line; nothing animates once done"
+a11y: "a polite live region announces each step change (not every percent); a real progressbar only when the percentage is real; cancel is reachable by keyboard"
+pairs_with: [self-playing-product-demo, first-win-onboarding, confetti-free-celebration]
+deps: none
+---
+
+## What it is
+
+During a wait longer than about two seconds (an AI generation, an import, a build), the UI lists the real steps as they happen: "Reading 214 files… Found 3 routes… Writing the team page (2 of 3)…", each step ticking to a check when done, with an honest estimate and a way to cancel.
+
+## Why it works
+
+- People tolerate waits they understand. Named steps make time feel shorter and the system feel competent.
+- Specific counts ("214 files") prove real work is happening, where a spinner proves nothing.
+- Seeing earlier steps complete builds trust that the current one will too.
+
+## When to use / when not
+
+Use for any operation of 2–60 s with distinguishable stages: AI agents and generation, imports, deploys, exports, analysis.
+
+Not for: sub-second actions (a spinner flash is worse than nothing; show the result) or truly opaque waits where you have no real stages; then use an honest indeterminate indicator with elapsed time, not invented steps.
+
+## Recipe
+
+1. **Emit real events.** The backend reports step changes (`{ step: "read", detail: "214 files" }`) over SSE or a polled status endpoint. Never script fake steps on a timer to look busy.
+2. **Render a short list**, max 5–6 visible: done steps with a check and their result in muted text, the active step with a subtle text shimmer (a moving gradient clipped to text, ~1.3 s loop), upcoming steps hidden or very faint. Collapse older steps into "4 steps done" when the list grows.
+3. **Counts and estimates.** Use real numbers in the detail. Show a percentage bar only when you know the total; otherwise "about 20 s left" from historical medians, updated, and "taking longer than usual" past 2× the median.
+4. **Floors and ceilings.** Hold each visible step at least ~300 ms so fast steps don't flash; never hold the final result back to look thorough.
+5. **Cancel and recover.** A Cancel button for anything over ~5 s. On failure, keep the steps that finished, mark the failed one, say what happened and offer Retry from that step.
+6. **A11y.** A polite `aria-live` region announces step changes ("Writing the team page"), not percentages. A real `role="progressbar"` with `aria-valuenow` only when it's real.
+7. **Reduced motion:** no shimmer (plain text colour); spinners slow to ~2.4 s per turn or become static.
+8. **No JS:** the server renders the current status with a meta refresh or a "Refresh status" link.
+
+## Pitfalls
+
+- Fake steps on a timer ("Reticulating splines…"): users notice when the same steps play for every job.
+- Progress bars that sit at 99%.
+- Logging every internal event: a wall of text that nobody reads.
+- Losing finished work on failure.
+- Shimmering everything at once.
+
+## How to verify
+
+- `palate states` (loading, error, slow): every state renders; the error keeps completed steps and offers retry.
+- Network log: each step on screen corresponds to an event from the backend.
+- Screen reader: announces each step once; cancel is reachable.
+
+## Examples
+
+- palate's own site: the live demo's agent rail shows a "Thinking…" shimmer, then palate's plan, then subagents and polish as named steps that tick to done (`Demo.tsx`); it's a scripted demo of the real flow, and the real product reports its real steps.

package/kb/moves/honest-testimonial-wall.md

@@ -0,0 +1,57 @@
+---
+id: honest-testimonial-wall
+name: A testimonial wall without fake people
+kind: layout
+fits: [honest, trustworthy, community, saas, developer, b2b, consumer, waitlist]
+avoid: [crisis, clinical]
+signature: false
+effort: m
+perf: "avatars small (48–64px), lazy, WebP; embeds rendered as static HTML, not third-party widget scripts"
+a11y: "each quote is a blockquote with cite (name, role, link); avatars have empty alt when the name is beside them; no auto-scrolling carousel"
+pairs_with: [made-with-proof, editorial-grid-pull-quotes, waitlist-position-live, marquee-done-right]
+deps: none
+---
+
+## What it is
+
+A wall of what real people actually said about the product: their words, their names, their faces or initials, and a link to where they said it (a post, a review, a GitHub issue). Every entry is verifiable; nothing is invented or polished into marketing copy. When there are no users yet, the section shows something honest instead.
+
+## Why it works
+
+- Visitors have learned that testimonial sections are often fake: stock faces, perfect sentences, first names only. Verifiable quotes beat that suspicion; the link is the proof.
+- Real words carry details marketing copy can't ("it caught the empty state I forgot"), and details persuade.
+- Honesty about being early ("Be one of the first") earns more trust than borrowed praise.
+
+## When to use / when not
+
+Use once you have real, attributable praise from people who agreed to be quoted, or public posts you may link to.
+
+Not for: invented quotes, AI-written "customer" lines, stock or generated faces, quotes from employees or friends presented as customers. Not in crisis or clinical contexts where personal stories need special care and consent processes.
+
+## Recipe
+
+1. **Collect with consent.** Ask each person: may we quote these words, with your name, role, photo, and a link? Keep the record (date, channel, what they agreed to). Public posts: quote briefly, link to the source, and still prefer asking.
+2. **Keep their words.** Trim for length with an ellipsis, never rewrite. Fix nothing but obvious typos. Keep the casual tone; it's what makes it believable.
+3. **Entry anatomy.** Quote (16–17px), then name, role and company (14px), avatar (their own photo or initials on a neutral tint; never a stock or generated face), and the source as a small link with its platform label ("on X, 12 Oct", "GitHub issue #214"). Markup: `<figure><blockquote cite="url">…</blockquote><figcaption>…</figcaption></figure>`.
+4. **Layout.** A masonry-like wall with CSS columns (`columns: 3 320px; column-gap: 16px`, `break-inside: avoid`) so quotes of different lengths pack naturally; one or two of the strongest set larger at the top. Phones: one column, the best 6 first with "Show more".
+5. **Variety.** Mix sources (posts, reviews, issues, emails with permission) and roles; include one mildly critical-but-positive quote, it raises trust.
+6. **Before you have any.** Don't fake it. Show instead: what you're testing and who it's for, a real count you can stand behind ("214 designers on the waitlist", see `waitlist-position-live`), the founder's own note with name and face, or the product's own proof (`made-with-proof`).
+7. **No motion needed.** If you use a slow marquee of quotes (see `marquee-done-right`), it pauses on hover/focus and is static under reduced motion; never an auto-advancing carousel. Works without JS.
+
+## Pitfalls
+
+- First names only, no links: reads fake even when real.
+- Avatars from stock or generators, or company logos you aren't allowed to show.
+- Quotes with numbers you can't back ("10x faster") presented as fact.
+- Embedding third-party widget scripts for each post: slow and tracks visitors. Render static.
+- Leaving quotes up after someone asks to be removed.
+
+## How to verify
+
+- Every entry has a name, role and a working source link or a recorded consent; no avatar fails a reverse-image "is this stock" check.
+- `palate shoot`: the wall packs without big gaps at 1440 and is one column at 390.
+- Accessibility tree: blockquote + figcaption per entry; no live auto-rotation.
+
+## Examples
+
+- palate's own site has no customer wall yet; it shows the founder's own blind picks and the rules learned from them as proof instead, and says the page was designed with palate. That's the honest version for a product in private preview.

package/kb/moves/inline-sparklines-in-copy.md

@@ -0,0 +1,57 @@
+---
+id: inline-sparklines-in-copy
+name: Sparklines inside the sentence
+kind: data
+fits: [data-rich, editorial, technical, scientific, finance, media, publishing, quiet, honest]
+avoid: [playful-kids, luxury, fashion, low-bandwidth]
+signature: false
+effort: s
+perf: "inline SVG, under 1 KB each, server-rendered; no chart library"
+a11y: "the sentence states the number in words; the sparkline is aria-hidden or carries a one-line title; never colour-only"
+pairs_with: [live-data-ticker, editorial-grid-pull-quotes, story-led-long-scroll]
+deps: none
+---
+
+## What it is
+
+A word-sized line chart set inline in running text, right after the number it explains: "Build times fell to 41 s ▁▂▃▂▁▁ over six weeks." The chart is as tall as the x-height and shares the text colour.
+
+## Why it works
+
+- It joins the claim and the evidence in one glance; the reader never leaves the sentence to look at a chart elsewhere.
+- Small multiples of shape (up, down, spiky, steady) are read pre-attentively; you see the trend before you read the number.
+- It signals a data-literate brand without a dashboard screenshot.
+
+## When to use / when not
+
+Use in editorial copy, changelogs, case studies, reports, finance and science products, and on any landing page that makes a quantitative claim.
+
+Not for: brands whose voice is emotional rather than evidential, kids' products, or claims you can't back with a real series. One or two per section; not every number needs a line.
+
+## Recipe
+
+1. **Real series only**: 8–40 points from your own data (weekly medians, daily counts). Store the series with the copy (JSON or a CMS field), not hard-coded paths.
+2. **Render as inline SVG** on the server: `viewBox="0 0 W H"` with `W = points × 4`, `H = 10`; set `width="3.2em" height="1em"` (or 0.9em), `style="vertical-align: -0.12em"`, `preserveAspectRatio="none"`, one `<polyline fill="none" stroke="currentColor" stroke-width="1.25" vector-effect="non-scaling-stroke">`. Normalise min–max to the box with 1 unit of padding.
+3. **Mark the end point**: a 2-unit circle at the last value, in the brand colour, so the eye lands on "now". Optionally a faint dot at the start.
+4. **Keep the number in the text.** The sentence must be complete without the chart: "fell from 2 min to 41 s". The SVG is `aria-hidden="true"`, or has `role="img"` and `<title>Build time, last 6 weeks: falling</title>` if the text doesn't state the trend.
+5. **Hover (optional, fine pointers only):** a tooltip with the exact range and dates. Never required to understand.
+6. **No animation by default.** If you draw it in, use `stroke-dashoffset` over 600 ms once when it enters view, skipped under reduced motion; no-JS shows it drawn.
+7. **Tailwind:** a `<Spark points={[...]} />` component that outputs the SVG; `text-current` so it follows link and dark-mode colours.
+
+## Pitfalls
+
+- Sparklines without a stated number: decorative squiggles that mislead.
+- Different y-scales side by side without saying so: readers compare shapes that aren't comparable.
+- Too tall: anything above 1.1em breaks the line height and pushes lines apart.
+- Thin 0.5px strokes that vanish at 100% zoom on non-retina screens.
+- Using it for 3 data points; that's not a trend.
+
+## How to verify
+
+- `palate shoot` at both widths: sparklines sit on the baseline, line height unchanged (compare paragraph height with and without).
+- The text alone (screen reader, copy-paste) states every claim.
+- Each series traces to a real data source in the repo.
+
+## Examples
+
+- The idea and the name come from Edward Tufte, who popularised word-sized charts as "sparklines" in his book Beautiful Evidence (2006). Use the idea; draw your own.

package/kb/moves/inspect-our-taste.md

@@ -0,0 +1,58 @@
+---
+id: inspect-our-taste
+name: Inspect our taste (the design rationale overlay)
+kind: easter-egg
+fits: [crafted, developer, honest, technical, saas, ai, community, editorial]
+avoid: [playful-kids, finance-trust-first, enterprise-compliance, serious-news, crisis]
+signature: true
+effort: m
+perf: "the inspector is a dynamic import loaded on first open; one rAF loop writing transforms and sizes only while open"
+a11y: "opens by key (P) or a visible chip; follows keyboard focus too; the card is role=status aria-live=polite; Esc and a Close button; never steals typing in fields"
+pairs_with: [made-with-proof, console-easter-egg, colophon, self-playing-product-demo]
+deps: none
+---
+
+## What it is
+
+A hidden overlay that lets a visitor hover (or Tab to, or tap) any part of the page and see why it looks the way it does: a box names the element (component, tag, text, width × height) and a dark card gives the decision behind it and the rule it follows, quoted from the team's design rules. Where no rule speaks to an element, it shows what was measured (type size/line-height/weight/colour, fill, radius, padding). Press P, or click a quiet "Inspect this page" chip.
+
+## Why it works
+
+- It turns the site into evidence. Claiming "we have taste" is cheap; showing the rule behind each decision is proof.
+- Designers and developers love to inspect; meeting that habit with something better than DevTools is a delight that gets shared.
+- For a design or developer tool, it demonstrates the product itself (here, palate's own pointing overlay).
+
+## When to use / when not
+
+Use for design tools, developer tools, agencies, studios and any brand whose claim is craft or rigour, when you actually have written decisions to show. Keep it opt-in and discoverable (a chip near "made with", a console hint).
+
+Not for: pages without a real design rationale (invented rules are worse than none), regulated or trust-first pages, or kids' products.
+
+## Recipe
+
+1. **The map.** A typed list of notes, most specific first: `{ sel, comp, title, rules: [{ id, text }], from, note? }`, where `sel` is a CSS selector (prefer `data-taste="…"` attributes you add to the page), `rules` quote real rules verbatim with their ids, and `from` says where the rule came from ("from a critique finding he agreed with, Oct 18"). Build one combined selector string from all of them.
+2. **Lookup.** For an element under the pointer, `el.closest(COMBINED)`; then the first note whose `sel` it matches. No match: show measured values from `getComputedStyle` (font size/line-height, weight, colour as hex, background if not transparent, radius, padding).
+3. **Trigger.** A tiny always-loaded root listens for `keydown` P (ignore with modifier keys, repeats, or when the target is an input, textarea, select or contenteditable) and a custom window event from the chip. On first open, `import("./Inspect")` and render it in a portal.
+4. **While open.** Capture-phase listeners on window: `pointermove` (mouse only) picks the element; `click` freezes the card on an element (click again to unfreeze) and is swallowed with `preventDefault` + `stopPropagation` so links don't navigate; `focusin` picks the focused element so keyboard users can Tab through; `pointerdown` is stopped so the page's own widgets stay quiet; Esc closes. Ignore events inside the overlay itself.
+5. **Follow.** One rAF loop: read `getBoundingClientRect()` of the picked element and write only `transform`, `width`, `height` to a fixed box (1.5 px brand border, 7% brand tint, the element's own border radius) and position the card above it (or below if no room, clamped 8 px from the edges). Update the W × H text only when it changes.
+6. **The card.** Dark, compact, 12–14 px: a head line (component in bold, tag in mono brand-tint, truncated text, dimensions right-aligned with tabular numbers), then the title as one short sentence, the rules with their id pills, an optional note, and the source in faint type. `role="status" aria-live="polite"`.
+7. **A pill** at the bottom centre says "Inspecting <brand>'s taste · Esc to close" with a Close button; it enters with a 200 ms rise (none under reduced motion).
+8. **No JS:** the chip does nothing harmful (it's a button); nothing else exists. Reduced motion: no box easing.
+
+## Pitfalls
+
+- Rules written for the overlay rather than the real rules: visitors can tell. Quote real ones with dates.
+- Letting clicks through: a visitor inspecting the signup button submits a form.
+- Hijacking P while someone types in the waitlist field.
+- Laying the box out with top/left per frame on a heavy page: transforms only.
+- No keyboard path: focus must drive it too.
+
+## How to verify
+
+- Press P: the pill appears; hover the hero headline, the primary button, a credit: each shows its note; an unannotated paragraph shows measured values.
+- Tab through the page with it open: the box follows focus. Click a link: it freezes instead of navigating. Esc closes.
+- Type "p" in an input: nothing opens. `palate animate --check`: page unaffected while closed; bundle shows the inspector as a separate chunk.
+
+## Examples
+
+- palate's own site: press P (or "Inspect this page" by the made-with line) to see each piece's rule from the founder's taste profile (`Inspect.tsx`, `taste-map.ts`, `InspectTrigger.tsx`).

package/kb/moves/interactive-pricing-calculator.md

@@ -0,0 +1,59 @@
+---
+id: interactive-pricing-calculator
+name: Pricing you can calculate
+kind: data
+fits: [saas, b2b, developer, ai, trustworthy, honest, technical, productivity]
+avoid: [luxury, fashion, playful-kids, enterprise-compliance]
+signature: false
+effort: m
+perf: "pure client-side arithmetic; no requests per input; server renders the default scenario"
+a11y: "native range and number inputs with visible labels; the total is in an aria-live polite region, debounced 400 ms; works by keyboard"
+pairs_with: [explorable-control, animated-comparison-table, honest-testimonial-wall]
+deps: none
+---
+
+## What it is
+
+On the pricing page, one or two sliders for the quantities that drive cost (seats, requests per month, GB stored) and a total that updates as you move them, with the arithmetic shown underneath: "12 seats × $14 + 3M requests × $0.20 / 1k = $768 / month".
+
+## Why it works
+
+- Usage pricing in a table makes people do maths and fear surprises; a calculator does it for them and removes the fear.
+- Seeing the formula builds trust: nothing hidden, no "contact us" for a number that is computable.
+- Moving a slider is the cheapest form of commitment; the visitor has already pictured their own usage.
+
+## When to use / when not
+
+Use when price depends on 1–3 continuous inputs: API products, infrastructure, AI credits, per-seat SaaS with volume discounts.
+
+Not for: flat plans (a calculator adds nothing), luxury or fashion (price isn't the story), or enterprise deals that genuinely require negotiation; and never if the real invoice can differ from what it shows.
+
+## Recipe
+
+1. **One source of truth.** Put the price model in a single typed module (`pricing.ts`: unit prices, tiers, included quota, discounts) used by the calculator, the pricing table and, ideally, billing. The calculator must never drift from billing.
+2. **Inputs.** A native `<input type="range">` paired with a `<input type="number">` for exact values, both labelled. Use a log scale for quantities spanning orders of magnitude (1k → 100M requests): map slider 0–100 to `10^(min + t·(max−min))` and snap to friendly values (1, 2, 5 × 10ⁿ).
+3. **Defaults** = the most common real customer (median, not the smallest). Server-render that scenario so no-JS visitors see a concrete total and its breakdown.
+4. **The total.** Big, `tabular-nums`, changes instantly (no count-up animation: it looks like a slot machine). Under it, the formula in small text with each term. Show "included: first 100k requests free" as a struck-through term so the visitor sees the saving.
+5. **Tier boundaries.** When a quantity crosses into a cheaper tier, say so in one line ("Volume price from 10M: $0.15 / 1k") and highlight the term for 600 ms (background tint, skipped under reduced motion).
+6. **Recommend a plan.** Below the total, the plan that fits this usage with its button; switching inputs updates it.
+7. **A11y.** The total lives in `aria-live="polite"` text, updated after 400 ms of no input so a screen reader isn't flooded. Keyboard: arrow keys move the slider in sensible steps (`step` matching the snapping).
+8. **Share the scenario** (optional): write inputs to the URL query (`?seats=12&req=3e6`) with `history.replaceState`, so a buyer can send it to finance. Only numbers in the URL, never personal data.
+
+## Pitfalls
+
+- Totals that exclude tax, minimums or overage the real bill has.
+- A slider with no exact input: people with a known number can't enter it.
+- Linear sliders over huge ranges: all the useful values are crammed into the first 2%.
+- Count-up animations on the price: feels manipulative.
+- "Contact sales" replacing the number above a threshold without saying the threshold.
+
+## How to verify
+
+- Unit test: for a list of scenarios, calculator total equals the billing module's total.
+- `palate shoot` with JS off: default scenario with a total and the formula.
+- `palate states`: zero usage, maximum usage, and a tier boundary all render without overflow at 390 px.
+- Keyboard only: reach and change every input; the total is announced once after you stop.
+
+## Examples
+
+- Usage-based infrastructure and API products commonly publish calculators beside their price tables; the honest version shows the formula, not just the total.

package/kb/moves/isometric-illustration-system.md

@@ -0,0 +1,56 @@
+---
+id: isometric-illustration-system
+name: Isometric illustration system
+kind: imagery
+fits: [technical, developer, b2b, saas, enterprise, crafted, hardware, friendly]
+avoid: [luxury, fashion, editorial, heritage, playful-kids]
+signature: false
+effort: l
+perf: "inline or static SVG, a shared symbol sheet; small (< 20 KB per scene); any motion via CSS transforms on groups"
+a11y: "scenes are decorative (aria-hidden) unless they explain something, then a figure caption carries the explanation"
+pairs_with: [code-drawn-diagram, technical-drawing-lines, one-colour-brand-world]
+deps: none
+---
+
+## What it is
+
+A small kit of isometric shapes (blocks, servers, cards, pipes, people as simple columns) drawn on one 30° grid in a strict palette, assembled into scenes that explain how the product's parts fit: data flowing from A to B, layers of a stack, a workflow.
+
+## Why it works
+
+- Isometric drawing shows structure and depth without perspective distortion, so it's ideal for systems that are hard to photograph (infrastructure, APIs, pipelines).
+- A consistent kit makes every new diagram look part of one world.
+- It reads as engineered and precise, which suits technical buyers.
+
+## When to use / when not
+
+Use for infrastructure, developer platforms, B2B systems, hardware ecosystems: products whose value is an architecture.
+
+Not for brands whose voice is editorial, luxurious or human-first, not for consumer emotion, and not as generic "isometric office people" decoration (a dated stock look). If you can't commit to a kit of at least ~12 consistent parts, use simple flat diagrams instead.
+
+## Recipe
+
+1. **Grid.** True isometric: x-axis at 30° and 150°, vertical axis straight. Unit = 16px along each axis. Build in an SVG editor or in code with a helper `iso(x, y, z) => [ (x − y) * cos30 * u, (x + y) * sin30 * u − z * u ]`.
+2. **Palette.** Three tones per material (top light, left mid, right dark) from 2–3 brand hues + neutrals. Fixed light direction for every object (top-left).
+3. **Kit.** Draw primitives as `<symbol>`s: block, slab, cylinder, card stack, pipe straight/corner, arrow, person column, screen. Strokes either none or one consistent 1px darker edge.
+4. **Scenes.** Compose scenes from `<use href="#block">` with transforms; label parts with HTML text positioned over the SVG (not SVG text with rotated skew; it hurts legibility).
+5. **Motion (optional).** One idea per scene: packets moving along a pipe (`offset-path` or translate along an iso axis, 2–4s linear loop) or layers lifting apart on hover (translateY −8px, 240ms). Pause off screen; static under reduced motion.
+6. **Responsive.** Scenes scale with `viewBox`; labels shrink to a numbered legend under ~480px.
+7. No JS required for static scenes.
+
+## Pitfalls
+
+- Mixing isometric with perspective or dimetric drawings: the world breaks.
+- Inconsistent light direction between objects.
+- Labels skewed onto faces: hard to read.
+- Decorative people with no role: stock clip-art feel.
+
+## How to verify
+
+- `palate shoot`: all scenes share palette and light direction; labels ≥12px and readable at 390.
+- `palate animate --check`: motion paused off screen, none under reduced motion.
+- SVG weights small; scenes crisp at 2x.
+
+## Examples
+
+- No public example cited; widely used by infrastructure and developer-platform companies for architecture explainers.

package/kb/moves/kinetic-variable-type.md

@@ -0,0 +1,57 @@
+---
+id: kinetic-variable-type
+name: Kinetic variable type
+kind: type
+fits: [bold, playful, energetic, artsy, music, fashion, events, experimental, launch]
+avoid: [calm, finance-trust-first, clinical, accessibility-first, low-bandwidth, daily-tool]
+signature: true
+effort: m
+perf: "one variable font file (subset, woff2, ~30–60 KB); animate font-variation-settings on a few words only; no per-letter layout thrash"
+a11y: "the headline stays one real text node for readers; per-letter spans aria-hidden with an sr-only copy; stops under reduced motion"
+pairs_with: [one-colour-brand-world, dark-band-contrast-section, generative-brand-pattern]
+deps: none
+---
+
+## What it is
+
+A headline set in a variable font whose axes (weight, width, slant, or a custom axis) move: on load the word settles from wide to condensed, on hover letters swell near the pointer, or on scroll the weight tracks progress. The type itself is the animation; there is no illustration.
+
+## Why it works
+
+- Type is the most brand-specific thing on the page; making it move puts the identity in motion instead of borrowing generic effects.
+- Variable axes interpolate smoothly, so the motion reads as material (stretching, breathing) rather than as a slideshow.
+- It costs one font file instead of video or 3D.
+
+## When to use / when not
+
+Use for loud, expressive brands: music, events, fashion, studios, launches, festivals, type foundries. Works best on one short line (1–4 words) at display size.
+
+Not for calm or trust-first products, for body text, or for daily tools. Avoid where the audience includes many people with vestibular sensitivity (health, public services). If the brand font has no variable version, don't fake it with scale transforms.
+
+## Recipe
+
+1. **Font.** Choose a variable font with an axis worth moving (wght 100–900, wdth 75–125, or a custom axis). Self-host one woff2, subset to the characters in the headline plus basic Latin, `font-display: swap`, preload it.
+2. **Static first.** Set the headline at its final, resting axes in CSS (`font-variation-settings: "wght" 800, "wdth" 85`). This is what no-JS and reduced motion get.
+3. **Load settle (CSS only).** A keyframe from wide/light to the resting values, 900–1200ms, `cubic-bezier(0.22, 1, 0.36, 1)`, inside `@media (prefers-reduced-motion: no-preference)`. Stagger words by 60–80ms, not letters (letter staggers read as a template effect).
+4. **Pointer swell (optional, desktop).** Split the line into letter spans in JS after hydration; keep the original text node in an `sr-only` span and mark the letters `aria-hidden`. On `pointermove` (throttled with rAF), set a CSS variable per letter from its distance to the pointer: `--w: clamp(300, 900 − d * 2.2, 900)` and use `font-variation-settings: "wght" var(--w)`. Only for `(hover: hover) and (pointer: fine)`. Reset smoothly on leave with a 300ms transition.
+5. **Reserve width.** Width-changing axes reflow the line. Either animate only weight on a letter-spaced line, or wrap the headline in a box with fixed width and `white-space: nowrap`, and test that the widest state fits at 320px.
+6. **Scroll-linked (optional).** With CSS scroll-driven animations (`animation-timeline: view()`), map weight to the section's progress; fall back to the static state where unsupported (`@supports`).
+
+## Pitfalls
+
+- Animating every letter, everywhere: noisy and slow. One line, one moment.
+- Width axis reflowing surrounding layout: causes CLS. Contain it.
+- Per-letter spans read letter by letter by screen readers: always keep an sr-only copy.
+- Loading two static weights and tweening between them: not variable, it jumps.
+- Leaving the effect running forever: it should settle.
+
+## How to verify
+
+- `palate shoot` with JS off and reduced motion: the headline shows at its resting axes, fully legible.
+- `palate animate --check`: frame strip shows the settle finishing in ≤1.2s; no layout shift in neighbouring elements.
+- At 320px wide the widest axis state doesn't overflow.
+- Accessibility tree: the headline is one readable string.
+
+## Examples
+
+- No public example cited; the pattern is common on type foundry specimen pages and music festival sites, where a variable display face is the whole identity.

package/kb/moves/konami-secret.md

@@ -0,0 +1,59 @@
+---
+id: konami-secret
+name: A secret key sequence
+kind: easter-egg
+fits: [playful, developer, gaming, community, retro, technical, energetic, crafted]
+avoid: [enterprise-compliance, clinical, finance-trust-first, crisis, government, serious-news]
+signature: false
+effort: s
+perf: "one keydown listener with a tiny buffer; the payload is lazy-loaded with dynamic import on first trigger"
+a11y: "ignored while typing in fields and with modifiers; the effect is dismissible with Esc; reduced motion gets a still version; never needed for any task"
+pairs_with: [console-easter-egg, tiny-game-easter-egg, inspect-our-taste]
+deps: none
+---
+
+## What it is
+
+A hidden keyboard sequence (the classic up-up-down-down-left-right-left-right-B-A, or a short word tied to the brand) that unlocks something delightful: an alternate theme, a hidden mode, a message from the team, a tiny game.
+
+## Why it works
+
+- Secrets reward the curious and give fans something to share ("try typing… on their site"), which spreads by word of mouth.
+- It signals that real people with a sense of humour made this, especially to developers and gamers who know the reference.
+- Because it is opt-in and invisible, it costs nothing to everyone else.
+
+## When to use / when not
+
+Use for developer tools, games, creative studios, community products and brands with a playful voice. A brand word (the product name typed anywhere) is often better than the classic code: more on-brand and less expected.
+
+Not for: regulated, clinical, financial or government contexts, crisis pages, or anywhere a surprise could alarm someone. It must never be the only route to a feature.
+
+## Recipe
+
+1. **Pick the sequence and the payload.** Payload ideas, in order of value: something that shows the craft (a design-mode overlay, the grid revealed), an alternate theme that persists for the session, a short note from the makers, a tiny game. Keep it on-brand.
+2. **Listener.** One `keydown` on `window`. Ignore when `e.target` is an input, textarea, select or contenteditable, when `e.repeat`, or with Ctrl/Meta/Alt. Normalise `e.key` (lowercase letters; `ArrowUp` etc. as-is). Keep a ring buffer of the last N keys; compare with the sequence; reset after 1.5 s idle.
+3. **Lazy payload.** On match, `import("./Secret")` so the code costs nothing until used. In React, keep the trigger in a small client component mounted once in the layout.
+4. **Feedback.** Make the unlock unmistakable but brief (a 400 ms transition into the new mode), and show a tiny pill: "Secret mode. Esc to leave." Esc and a Close button restore everything.
+5. **Persistence.** Session only (`sessionStorage` in try/catch), never permanent; a reload or Esc returns to normal.
+6. **Hint, lightly.** A console message, a line in the colophon or a "?" in the footer; never a visible "find the secret" banner.
+7. **Touch.** Offer an equivalent (e.g. tapping the logo 7 times) if the payload is worth it; otherwise accept it's desktop-only.
+8. **Reduced motion:** the payload appears without animation; any game pauses its motion or offers a static version.
+
+## Pitfalls
+
+- Triggering while someone types in a form (a search for "bab…").
+- Payloads that break layout, cover content without a way out, or persist forever.
+- Loud audio on trigger.
+- Shipping a heavy payload in the main bundle.
+- Overusing pop-culture references that don't fit the brand.
+
+## How to verify
+
+- Typing the sequence inside a text field does nothing; outside, it triggers once.
+- Esc restores the page exactly; reload restores defaults.
+- Bundle analysis: the payload is a separate chunk.
+- `palate animate --check` with reduced motion: no motion from the payload.
+
+## Examples
+
+- The classic sequence comes from 1980s video games and has been hidden in many websites since; use the idea with a payload that is yours.

package/kb/moves/layered-paper-depth.md

@@ -0,0 +1,56 @@
+---
+id: layered-paper-depth
+name: Layered paper depth
+kind: texture
+fits: [crafted, playful, warm, friendly, education, nonprofit, consumer, artsy]
+avoid: [technical, data-dense-tool, enterprise-compliance, minimal, serious-news]
+signature: true
+effort: m
+perf: "3–5 SVG or CSS layers with static shadows; optional parallax moves transforms only, capped at 3 layers"
+a11y: "decorative layers aria-hidden; content sits on the top sheet with full contrast; parallax off under reduced motion"
+pairs_with: [riso-print-texture, hand-drawn-annotations, story-led-long-scroll, canvas-grain]
+deps: none
+---
+
+## What it is
+
+A scene or section built from stacked cut-paper sheets: flat shapes in a few related colours, each sheet casting a short soft shadow on the one beneath, with a faint fibre texture. Hills, waves, a skyline or the product's own icon shapes, cut out and layered, frame the content.
+
+## Why it works
+
+- Physical depth from shadows alone feels handmade and touchable, which reads warm and human without stock illustration.
+- Each layer is a flat colour, so the palette stays disciplined; depth comes from order, not from gradients.
+- A little parallax between sheets adds life that the eye reads as depth, not as "animation".
+
+## When to use / when not
+
+Use for friendly consumer products, education, nonprofits, children's books for adults, travel and seasonal campaigns, onboarding illustrations.
+
+Not for: technical, precision-led brands, data tools, compliance-heavy pages, serious news. Avoid if the rest of the page uses glass or 3D renders.
+
+## Recipe
+
+1. **Draw the sheets.** 3–5 layers as SVG paths (or `clip-path: path()` on divs), back to front, each one flat colour stepping in lightness: e.g. from `oklch(0.92 0.04 150)` at the back to `oklch(0.55 0.09 150)` in front. Same hue family plus one accent sheet.
+2. **Shadows that describe a cut edge.** Each sheet: `filter: drop-shadow(0 2px 2px rgb(0 0 0 / .12)) drop-shadow(0 8px 12px rgb(0 0 0 / .08))`. Same light direction for all. Keep shadow offsets small; paper is thin.
+3. **Fibre.** Overlay one SVG `feTurbulence` tile (`baseFrequency` ~1.2, 1 octave) at 6–10% opacity with `mix-blend-mode: multiply` on the whole scene, once (not per layer).
+4. **Content on top.** The headline and actions sit on the frontmost sheet or above the scene on plain paper; never across layer edges.
+5. **Optional parallax.** On scroll, translate the back two layers by 2–6% of scroll distance in a `requestAnimationFrame` driven by one passive scroll listener (or CSS `animation-timeline: view()` where supported, with a static fallback). Max 3 moving layers; `will-change: transform` only on those.
+6. **React/Tailwind.** One `<PaperScene>` component with layers as an array of `{ d, fill, depth }`; Tailwind `drop-shadow-*` with arbitrary values.
+7. **Fallbacks.** Static by default; parallax only under `prefers-reduced-motion: no-preference` and only with JS. On phones, reduce to 3 layers and drop parallax.
+
+## Pitfalls
+
+- Long, dark shadows: it turns into a 2010 web-2.0 card stack. Short and soft.
+- Inconsistent light direction between layers.
+- Too many colours: 4 tones of one hue plus an accent is enough.
+- Shapes with no meaning; cut the product's own shapes, a place, or a story element.
+
+## How to verify
+
+- `palate shoot`: the shadows all fall the same way; text never crosses a layer edge; contrast passes.
+- `palate animate --check`: only transforms change on scroll; reduced motion shows the static scene.
+- Phone width: the scene still reads with fewer layers and doesn't push the headline below the fold.
+
+## Examples
+
+- A common technique in illustrated editorial and children's-book-style marketing; no specific site cited.