@palate/cli 0.0.0-stage → 0.0.2

package/kb/moves/engraving-colour-lens.md

@@ -0,0 +1,64 @@
+---
+id: engraving-colour-lens
+name: Engraving with a colour lens
+kind: footer
+fits: [calm, crafted, editorial, heritage, nature, artsy, premium, quiet]
+avoid: [playful-kids, finance-trust-first, energetic, gaming, data-dense-tool, low-bandwidth]
+signature: true
+effort: m
+perf: "two images (engraving + colour), lazy with an early IntersectionObserver kick; transform-only per frame, rAF stops when settled"
+a11y: "decorative (aria-hidden); pointer-only; the lens rests on the best spot for touch, keyboard and reduced motion"
+pairs_with: [line-engraving-from-image, museum-painting-backdrop, canvas-grain, hero-paints-itself-in]
+deps: none
+---
+
+## What it is
+
+A picture shown as a one-ink line engraving on paper, with one soft round lens that reveals the same picture in full colour. The lens rests on the most luminous spot of the picture; with a mouse it follows the cursor and glides home when the cursor leaves. palate uses it as its footer: Church's sunset, engraved in emerald, with the colour restored under the lens.
+
+## Why it works
+
+- Two registers of the same image (line and colour) make people compare, and comparison holds attention longer than a single image.
+- The lens is a metaphor you can carry: "we restore what's missing", "see the real thing", "the last 20%". A move that says the product's idea without words is worth more than decoration.
+- One ink keeps the section calm enough for text to sit on it; the colour is a reward, not a wall of saturation.
+- It rewards reaching the end of the page, which almost nobody designs for.
+
+## When to use / when not
+
+Use when the brand is calm, crafted or editorial, there is a strong picture you are allowed to use (a CC0 painting, your own photo or illustration), and the product has a "reveal / restore / clarify" story. Best in a footer or closing band, where the pointer naturally wanders.
+
+Not for: playful or kids' brands (it reads as serious), finance pages that must lead with trust signals, dense app UI, or audiences on slow connections (it costs two large images). Never use it on a picture you don't have rights to.
+
+## Recipe
+
+1. **Make the two images, pixel-aligned.** Engrave the picture (see `line-engraving-from-image`) and export the colour version cropped and sized *exactly* like the engraving (same crop, same dimensions), so a pixel in one is the same pixel in the other. Export 3 widths of each (1200, 1600, 2400) as WebP. Hatching must be generated per size: resampling line art produces moiré.
+2. **Inline a tiny placeholder.** A 48px-wide copy of the engraving as a base64 WebP background on the art box, so the land shows as a soft tinted shape at once and the lines sharpen in.
+3. **Structure.** A panel (`position: relative; isolation: isolate; overflow: hidden`) holds the content and, behind it (`z-index: -1`, `aria-hidden`, `pointer-events: none`), an art box with a fixed aspect ratio that is a size container (`container-type: size`). Inside the art box: the engraving `<img>` (`object-fit: cover`), then the lens.
+4. **The lens is two layers.** An outer disc (`--r: clamp(56px, 8.5cqw, 124px)`, `border-radius: 50%`, `overflow: hidden`, soft edge with `mask-image: radial-gradient(closest-side, #000 88%, transparent)`), and inside it a layer the size of the whole art box (`100cqw × 100cqh`) holding the colour image. Move the outer disc by `translate(x − r, y − r)` and the inner layer by the opposite `translate(r − x, r − y)`, so the colour stays pinned to the engraving. Both `will-change: transform`.
+5. **Rest position in CSS.** Put the resting point (e.g. the sunset at 47% × 65.5%) in container units on both layers, so with no JavaScript, on touch and under reduced motion, the lens already sits in the right place and survives resizes.
+6. **Follow in JS, mouse only.** Listen to `pointermove` on the panel (passive). Ignore unless `e.pointerType === "mouse"`, `(hover: hover) and (pointer: fine)` matches and reduced motion is off. Ease the lens toward the target with a frame-rate-independent exponential (`k = 1 − exp(−dt / τ)`, τ ≈ 85 ms while following, ≈ 240 ms gliding home). Keep it out of the text area (clamp `y` below a marker element such as `[data-etch-top]`). On `pointerleave`, target the rest point; when it arrives, clear the inline transforms and stop the rAF loop so CSS owns it again.
+7. **Late images.** With JS, mark the art box `data-js`; fade the engraving in on its `load`, and show the lens only once *both* images have loaded (never an empty disc). Kick loading early with an IntersectionObserver `rootMargin: "2400px 0px"` that flips `loading="lazy"` to `eager`.
+8. **Grain.** Put `canvas-grain` inside the lens, pinned with the colour, so the paint reads as paint on canvas.
+9. **Credit** the painting in small type in the footer's bottom bar.
+
+React/Tailwind notes: plain `<img>` with `srcSet` (not `next/image`: it would resample the hatching); Tailwind's `@container` on the panel and `[container-type:size]` on the art box.
+
+## Pitfalls
+
+- Colour and engraving cropped differently: the lens shows a shifted picture and the illusion breaks. Generate both from one script.
+- Moving the lens with `left/top` or a clip-path circle: layout or paint every frame. Use transforms only.
+- A lens that sits over the headline or links: text becomes unreadable. Clamp it to the picture area below the text.
+- A dark picture under the lens (night land) shows a black disc; lift the colour image slightly (gamma ~0.8, no hue shift).
+- Following on touch: fingers cover the lens; leave it at rest.
+- Too many lenses, or a lens that also zooms: one disc, 1:1.
+
+## How to verify
+
+- `palate shoot` (both widths, JS off too): the engraving shows, the lens sits on the rest point, the footer text is readable over the paper.
+- `palate animate --check`: no layout shift; only `transform` changes on the two lens layers; under reduced motion nothing moves.
+- Hover the footer: the lens follows within ~100 ms and glides home on leave; the colour stays exactly aligned with the lines at the lens edge.
+- Network throttled: no empty disc; the placeholder shape shows first.
+
+## Examples
+
+- palate's own site: the footer, Church's "Twilight in the Wilderness" (CC0, Cleveland Museum of Art) engraved in emerald, with a colour lens that rests on the sunset (`EtchLens.tsx`, `etch-lens.css`).

package/kb/moves/explorable-control.md

@@ -0,0 +1,57 @@
+---
+id: explorable-control
+name: One control that explains the idea
+kind: interaction
+fits: [education, scientific, data-rich, technical, editorial, developer, finance, honest]
+avoid: [luxury, fashion, minimal]
+signature: true
+effort: m
+perf: "pure functions recomputed on input; SVG or DOM output; no canvas library; debounce nothing under 1 ms of work"
+a11y: "native inputs (range, number, select) with labels and visible values; results in text, not only in the drawing; output region aria-live=polite"
+pairs_with: [inline-sparklines-in-copy, interactive-pricing-calculator, before-after-slider, code-drawn-diagram]
+deps: none
+---
+
+## What it is
+
+Instead of explaining the product's core idea in prose, give the reader one control (a slider, a toggle, a draggable number) that changes an assumption, and show the consequence update instantly beside it: drag "team size" and watch the hours saved; toggle "with caching" and watch the request waterfall shrink; scrub "noise" and see the model's guess degrade.
+
+## Why it works
+
+- People believe what they discover. Changing an input and seeing the effect builds an intuition no sentence can.
+- It's the reactive-document idea: the reader is invited to argue with the claim and finds it holds.
+- One control is the right dose: enough to engage, not a dashboard to learn.
+
+## When to use / when not
+
+Use when the product's value depends on a relationship (more X → less Y), especially for technical, scientific, financial or educational products, in the section that would otherwise be "how it works" text.
+
+Not for: brands sold on mood (fashion, luxury), ideas that don't vary with an input, or numbers you can't defend (a slider over fake maths is worse than no slider).
+
+## Recipe
+
+1. **Find the one variable.** Write the sentence: "As ___ goes up, ___ goes down, because ___." The first blank is the control; the second is the output. Pick sensible bounds and a default that tells the story (not the extreme).
+2. **Model.** A pure function `f(input) → { value, parts }` with the real formula, documented in a code comment and in a footnote on the page ("Assumes 22 working days; source: …").
+3. **Control.** A labelled native `<input type="range">` with the current value printed beside it in tabular numerals (`font-variant-numeric: tabular-nums`) and units ("12 people"). Optionally, the number is inline in a sentence and draggable ("With **12** people…"): implement as a range input styled as underlined text with `cursor: ew-resize`, still a real input.
+4. **Output.** The consequence as a big number plus one small drawing (an SVG bar, a timeline, a waterfall) that rescales with the value. Animate changes with a 150–200 ms ease-out on transform (bars scale, numbers update immediately; don't tween numbers on every input event, it lags).
+5. **Words update too.** A sentence below restates the result ("That's about 3 working weeks a year.") in an `aria-live="polite"` region, updated on `change` (not every `input`) so screen readers aren't flooded.
+6. **No JS.** The server renders the default value's result (number, drawing and sentence). The control is disabled or hidden without JS; the page still makes its point.
+7. **Reduced motion.** Drop the transitions; values snap.
+
+## Pitfalls
+
+- Several sliders: it becomes a calculator nobody plays with. One control (two at most).
+- An output that barely changes across the range: it proves the opposite of the claim. Pick a variable with a visible effect.
+- Hidden assumptions: show them in small type; credibility is the whole point.
+- Tweened counters on every drag event: they lag behind the thumb and feel broken.
+
+## How to verify
+
+- `palate shoot` with JS off: the default result is visible and makes sense.
+- Drag through the full range: output never overflows, wraps or shows NaN/negative values; extremes are labelled.
+- Keyboard: arrows change the value; the live sentence is announced on release.
+- `palate states`: minimum, maximum and default all render cleanly at 390px.
+
+## Examples
+
+- Seen on Bret Victor's "Explorable Explanations" (https://worrydream.com/ExplorableExplanations/): essays where you drag a number in the text and the conclusions recompute in place.

package/kb/moves/feature-films-on-painted-stages.md

@@ -0,0 +1,58 @@
+---
+id: feature-films-on-painted-stages
+name: Feature rows with films on painted stages
+kind: layout
+fits: [saas, crafted, calm, developer, ai, productivity, premium, honest, artsy]
+avoid: [low-bandwidth, data-dense-tool, playful-kids, finance-trust-first]
+signature: false
+effort: m
+perf: "muted looping MP4 per feature, preload=metadata, played only while ≥35% visible; poster JPEG; painting images sized to ~58vw"
+a11y: "each video has an aria-label describing what it shows; under reduced motion it doesn't autoplay and shows the poster with native controls; feature copy is real text"
+pairs_with: [museum-painting-backdrop, canvas-grain, self-playing-product-demo, bento-live-tiles]
+deps: none
+---
+
+## What it is
+
+One feature per row, alternating sides: on one side, the feature in words (a title, one line, three short points with checks); on the other, the feature itself as a short film (or a live code-built piece) inside a white window that sits on a CC0 painting with canvas grain, the painting credited underneath. Each film plays muted on a loop while on screen.
+
+## Why it works
+
+- Each row is one claim plus its proof, side by side; the visitor never has to trust a sentence without seeing it happen.
+- The painted stage gives each feature its own mood and makes the product window feel framed and precious, instead of another screenshot on grey.
+- Alternation creates rhythm on a long page without inventing new layouts for each feature.
+
+## When to use / when not
+
+Use for 3–6 features of a software product, each with a 6–15 s film of the real feature working (a screen recording edited tight, or a Remotion-style render). Works with `museum-painting-backdrop` for calm, crafted brands; swap the paintings for soft pastel stages in other brands.
+
+Not for: more than ~6 features (use a bento), features with nothing visual to show, or audiences on metered connections (keep films very small or use posters).
+
+## Recipe
+
+1. **Row.** `<article>` as a grid: one column on phones; at `md` two columns `5fr 7fr` (copy | stage), flipped to `7fr 5fr` on alternate rows with `order`. Gap 56–80 px; rows 80–112 px apart. `items-center`.
+2. **Copy.** Title 26–32 px, regular weight, tight tracking, `text-balance`; one line of 16–17 px body at ≤ 460 px wide; 3 points, 15 px, each with a small brand-coloured check. Copy column must carry weight beside the stage (no tall empty gap).
+3. **Stage.** A `<figure>`: a rounded (20 px) container with padding 16/32/40 px (phone/tablet/desktop), `relative isolate overflow-hidden`, the painting as a `fill` image with `-z-10 object-cover`, the grain, then the window. Set a CSS variable `--shade` (the painting's deep tone at ~32%) for shadows.
+4. **Window.** White, 12 px radius, `overflow-hidden`, shadow stack `0 0 0 1px shade/8%, 0 2px 4px shade/12%, 0 24px 48px -16px shade/45%`.
+5. **Film.** `<video muted loop playsInline preload="metadata" poster=… aria-label=…>` at `aspect-video`, `object-cover`. In an effect: if reduced motion, set `controls = true` and stop; else an IntersectionObserver at `threshold: 0.35` plays when visible (`play().catch(() => v.controls = true)`) and pauses when not.
+6. **Credit** under the stage as `<figcaption>`, 12 px grey: artist, title, year, museum.
+7. **Films.** 1280–1600 px wide, H.264 MP4, no audio track, 6–15 s, ~1–2.5 MB each; poster = a frame that already shows the result. Show the real feature with real content.
+8. **No JS:** the poster shows (native `poster`), copy is all there.
+
+## Pitfalls
+
+- Films with tiny text: crop and zoom into the part that matters, render at 2×.
+- Autoplay with sound or without `playsInline`: iOS opens fullscreen.
+- Every stage the same painting, or paintings that fight each other: choose a family.
+- A static screenshot in the window: it loses to the film; if there's no film yet, a live code-built piece.
+- Copy column much shorter than the stage: add the points, or narrow the stage.
+
+## How to verify
+
+- `palate shoot` at 1440 and 390: rows alternate on desktop, stack on phone with the copy first; credits visible.
+- `palate animate --check`: videos play only in view; reduced motion shows posters with controls; no layout shift when videos load (aspect ratio reserved).
+- Network panel: films load metadata only until in view.
+
+## Examples
+
+- palate's own site: "Fix it in place", "Critique", "Sized to the change", "Never the same twice", "Your references come first", each in a window on a credited CC0 painting (`page.tsx` `Feature`, `FeatureVideo.tsx`).

package/kb/moves/first-win-onboarding.md

@@ -0,0 +1,59 @@
+---
+id: first-win-onboarding
+name: The first-win moment in onboarding
+kind: interaction
+fits: [saas, productivity, ai, developer, friendly, consumer, education, honest]
+avoid: [enterprise-compliance, luxury, crisis]
+signature: true
+effort: m
+perf: "no extra assets; the win is the product's real output; one small celebration animation, transform/opacity"
+a11y: "progress and the win announced in text (role=status); every step keyboard reachable; nothing time-limited; skippable"
+pairs_with: [confetti-free-celebration, honest-progress-narration, shape-continuity-morph, self-playing-product-demo]
+deps: none
+---
+
+## What it is
+
+Onboarding designed backwards from one moment: the first time the new user gets a real result from the product (their first deploy URL, their first generated design, their first reconciled invoice). Everything before it is cut to the minimum, sample data or a ready-made starting point is offered, and the moment itself is staged: the result appears in place, named, with the one next step.
+
+## Why it works
+
+- People decide whether to keep a product in the first session, and they decide on value felt, not features toured. A real result is felt value.
+- Effort before reward is the biggest drop-off; removing setup steps until after the win (accounts, teams, settings) raises completion.
+- Staging matters: a result that arrives quietly in a list is easy to miss; one that arrives with its name and a "share it" or "use it" action becomes the memory of the product.
+
+## When to use / when not
+
+Use for any product with signup → setup → value, especially self-serve SaaS, AI tools and developer platforms.
+
+Not for: enterprise flows where admins must configure compliance first (stage the win for them later, at the end-user's first use), or luxury and crisis contexts where celebration is out of place.
+
+## Recipe
+
+1. **Name the win.** One sentence: "The user's first ___ appears and they can ___ it." Measure the steps to it today; aim for ≤ 3 actions and under 2 minutes.
+2. **Defer everything else.** Team invites, profile, billing, preferences: after the win. Ask only for what the first result needs.
+3. **Offer a head start.** Sample data, a template, or "Try it on our example" as a first-class option next to "Use my own".
+4. **Narrate the wait.** If the work takes more than ~1 s, show what is happening in real steps (see `honest-progress-narration`), not a spinner.
+5. **Stage the arrival.** The result appears where the user's attention already is (the form morphs into the result, see `shape-continuity-morph`), with: what it is in plain words ("Your first page is live"), the real artefact (URL, preview, file), one primary next action ("Open it", "Share it") and one secondary ("Make another"). Mark it once with a small celebration (see `confetti-free-celebration`), never a modal that blocks it.
+6. **Then, the checklist.** Only after the win, show a short checklist (3–4 items) of what unlocks more, with the first already ticked ("Created your first page ✓").
+7. **Accessibility.** Announce progress and the result in a `role="status"` region; move focus to the result heading; every step works by keyboard; nothing auto-advances on a timer.
+8. **No JS / failures.** Server-rendered steps work as plain forms. Plan the failure path as carefully as the win: if the first attempt fails, say what happened and offer the example data path in one click.
+9. **Reduced motion.** The result appears without movement; the celebration becomes a static check and the words.
+
+## Pitfalls
+
+- Product tours of the UI before any value: people click "Next" without reading.
+- A "win" that isn't real (a fake demo result presented as theirs).
+- Celebrating with a modal over the result they just made.
+- Asking for team, role and company size before the first result.
+
+## How to verify
+
+- Count actions from signup to the first result: ≤ 3; time it on a fresh account: under 2 minutes.
+- `palate states` on the onboarding route: loading (narrated), success (result visible, focus on it), error (what happened + example-data path), long names.
+- `palate animate --check`: the arrival animation under 400 ms; reduced-motion strip static.
+- Screen reader: the result is announced.
+
+## Examples
+
+- The pattern: a hosting product where the first screen after signup offers "deploy our example", streams the real build steps, and ends on the user's live URL with "Open" and "Share" as the only actions.

package/kb/moves/footer-live-status.md

@@ -0,0 +1,56 @@
+---
+id: footer-live-status
+name: A footer that is alive (status, time, now)
+kind: footer
+fits: [developer, honest, technical, saas, agency, portfolio, community, local]
+avoid: [luxury, heritage, crisis, low-bandwidth]
+signature: false
+effort: s
+perf: "one small fetch (cached 60 s) or none; the clock updates once a minute; nothing runs when the footer is off screen"
+a11y: "status in text, not colour alone; no aria-live on the clock (it would chatter); time in a <time> element"
+pairs_with: [real-world-data, footer-rewards-the-end, colophon, live-data-ticker]
+deps: none
+---
+
+## What it is
+
+The footer's bottom bar carries one or two small live facts instead of a static copyright line: "All systems normal" with a green dot linked to the status page, the studio's local time ("09:41 in Lisbon"), the last deploy ("Updated 3 hours ago"), or what the team is shipping this week.
+
+## Why it works
+
+- A live fact proves there are people and systems behind the site right now; it's honest social proof without testimonials.
+- It rewards reaching the bottom with something true and current.
+- Status in the footer is where technical buyers look for it.
+
+## When to use / when not
+
+Use for developer platforms and SaaS with a real status page, small studios and portfolios (local time humanises them), open-source projects (latest release).
+
+Not for luxury or heritage brands where "live" breaks the timeless tone, crisis or emergency sites, or when the data source is unreliable (a stale "Updated 47 days ago" hurts).
+
+## Recipe
+
+1. **Pick at most two facts** that are true and cheap: status (from your status provider's public JSON), local time of the team, latest release tag, last deploy time.
+2. **Server-render a value** at build or request time (ISR/revalidate 60s), so no-JS shows a recent truth. Phrase it so a slightly stale value is still true ("Updated today").
+3. **Client refresh** only when the footer is visible (IntersectionObserver): fetch status once, then every 60s while visible; update the clock once a minute aligned to the minute boundary (`setTimeout` to the next :00, then `setInterval(60000)`).
+4. **Status dot.** 8px dot + text ("All systems normal", "Degraded: API"), colours from the system (green/amber/red tokens), text always present. Optional calm pulse (2s, opacity 1→0.5) only when not normal, and none under reduced motion.
+5. **Time.** `Intl.DateTimeFormat(undefined, { hour: "2-digit", minute: "2-digit", timeZone: "Europe/Lisbon" })` in `<time datetime>`; add the visitor-relative note if useful ("2 h ahead of you").
+6. **Failure.** If the fetch fails, fall back to the server value or hide the item; never show "Error" in a footer.
+
+## Pitfalls
+
+- A status dot that's always green because it isn't wired to anything: a lie.
+- Second-by-second clocks: distracting, and they trigger hydration mismatches.
+- Aria-live on a clock: screen readers announce it every minute.
+- Hydration mismatch from rendering local time on the server: render the time zone's time on both, or render after mount.
+
+## How to verify
+
+- `palate shoot` with JS off: the bar shows a sensible server value.
+- Network blocked: no "Error" text; the item falls back or hides.
+- Status text matches the status page; the link goes there.
+- No console hydration warnings.
+
+## Examples
+
+- No public example cited; status lines in footers are common on developer platforms, and local-time lines on studio sites.

package/kb/moves/footer-rewards-the-end.md

@@ -0,0 +1,58 @@
+---
+id: footer-rewards-the-end
+name: A footer that rewards reaching the end
+kind: footer
+fits: [crafted, playful, artsy, editorial, community, portfolio, agency, warm]
+avoid: [enterprise-compliance, data-dense-tool, government, clinical]
+signature: true
+effort: m
+perf: "the reward loads lazily when the footer nears the viewport; one IntersectionObserver; nothing runs above the fold"
+a11y: "links stay a normal, readable footer; the reward is decorative or has a text equivalent; static under reduced motion; no scroll-jacking"
+pairs_with: [engraving-colour-lens, colophon, console-easter-egg, made-with-proof]
+deps: none
+---
+
+## What it is
+
+The bottom of the page holds something worth scrolling for: a small reveal, a personal note, a hidden interaction, a last piece of the page's visual story. Most footers are a link dump; this one is the page's closing scene, with the links still there and easy to use.
+
+## Why it works
+
+- The end of a page is a moment of attention almost nobody designs; a reward there is a pleasant surprise (peak-end: people remember the peak and the end).
+- It gives curious visitors a reason to scroll the whole page, past sections they'd skim.
+- A closing moment that echoes the hero (the same painting, the same character, the same idea resolved) makes the page feel authored from start to finish.
+
+## When to use / when not
+
+Use on marketing sites, portfolios, studios, editorial pages and community products, where people browse rather than hunt.
+
+Not for: dense product UIs, docs where the footer is navigation, compliance-heavy sites, or pages so long nobody reaches the end (fix the page first).
+
+## Recipe
+
+1. **Close the page's story.** Choose a reward that resolves something from the top: the hero's picture in another register (see `engraving-colour-lens`), the illustrated character arriving home, the sunset of a page that opened at dawn, the team's note signed by hand.
+2. **Keep the footer working.** Links in a clear grid, legible over the reward (contrast ≥ 4.5:1), with the reward behind or below them. The reward never covers or moves the links.
+3. **Trigger by arrival, not scroll position.** An IntersectionObserver on the footer (`rootMargin: "0px 0px -20% 0px"`) starts the reveal once; a `rootMargin` of a few screens kicks off lazy image loading early.
+4. **Small interactions only.** Pointer-follow (desktop, fine pointer), a hover detail, a click that reveals a note. No scroll-jacking, no forced animation that delays the links.
+5. **Text equivalent.** If the reward carries meaning (a note, a message), it's real text; purely visual rewards are `aria-hidden`.
+6. **Reduced motion and no JS:** the reward shows in its final state.
+7. **Light on weight.** Budget ≤ 200 KB for the reward assets, lazy; preload nothing for it.
+8. **A last line in your voice** (a colophon line, a sign-off) helps it feel finished.
+
+## Pitfalls
+
+- An infinite-scroll page where the footer is never reached.
+- Rewards that make the footer's links hard to read or click.
+- A giant wordmark as the only idea (now a cliché).
+- Heavy video or 3D that loads for everyone at page start.
+- Animations that replay every time the footer passes in and out of view.
+
+## How to verify
+
+- `palate shoot` at both widths: footer links readable and tappable (≥ 44 px targets on phones); the reward visible in its final state with JS off.
+- `palate animate --check`: no layout shift; reduced motion static.
+- Network: the reward's assets load only as the footer approaches.
+
+## Examples
+
+- palate's own site: the footer is Church's sunset engraved in emerald with a colour lens that rests on the horizon and follows the cursor, the page's closing scene after a hero that paints the same kind of picture into colour (`Footer.tsx`, `EtchLens.tsx`).

package/kb/moves/generative-brand-pattern.md

@@ -0,0 +1,55 @@
+---
+id: generative-brand-pattern
+name: Generative pattern seeded by the brand
+kind: texture
+fits: [technical, developer, crafted, experimental, bold, ai, artsy, community]
+avoid: [heritage, luxury, clinical, finance-trust-first]
+signature: true
+effort: m
+perf: "generated once (build time or first render) to SVG; deterministic from a seed; no per-frame work"
+a11y: "decorative (aria-hidden); never behind body text without a solid surface; static under reduced motion"
+pairs_with: [one-colour-brand-world, halftone-dot-imagery, kinetic-variable-type, technical-drawing-lines]
+deps: none
+---
+
+## What it is
+
+A pattern (grid of shapes, flow lines, stripes, tiles) generated by a small deterministic function seeded from a string: the brand name for the main pattern, and each user's, project's or post's name for its own variant. Same input, same pattern, forever. Covers, avatars, OG images and section backgrounds all come from it.
+
+## Why it works
+
+- Every generated piece is unique yet clearly part of one family, which is exactly what a brand system needs at scale.
+- Seeding from names gives each object an identity at zero design cost (a blog post's cover, a workspace's avatar).
+- It can't be copied from a stock library, so it reads as authored.
+
+## When to use / when not
+
+Use for developer platforms, AI products, communities, publications with many items needing covers, and any product where users create many named things.
+
+Not for heritage or luxury brands that need hand-made assets, medical contexts, or where the pattern would sit behind dense text.
+
+## Recipe
+
+1. **Seed → numbers.** Hash the string to a 32-bit integer (FNV-1a or cyrb53, a few lines you write yourself) and feed a small PRNG (mulberry32) so outputs are deterministic across server and client.
+2. **Design the grammar first, then randomise within it.** E.g. an 8×8 grid; each cell picks one of 4 shapes (quarter circle in one of 4 rotations, full square, empty, diagonal) with weights; colours from a fixed 3–4 colour brand palette; mirror horizontally for symmetry if it should feel like a mark.
+3. **Render to SVG** in a component `<BrandPattern seed="palate" size={..} />`: rects/paths only, `shape-rendering: crispEdges` for grids. Generate on the server (or at build time to a file for OG images) so it's in the HTML and needs no JS.
+4. **Constrain.** Keep contrast low when used as background (≤ 8–12% opacity of ink over the surface), full strength only for covers and avatars. Always put text on a solid surface, not on the pattern.
+5. **Optional motion.** On hover of a card, re-roll one cell or rotate shapes 90° with a 200ms transform. None under reduced motion.
+6. **Test the edge cases**: very short and very long seeds, non-Latin characters (hash the UTF-8 bytes), identical-looking names.
+
+## Pitfalls
+
+- Using `Math.random()`: server and client disagree (hydration mismatch) and patterns change on reload.
+- Too much freedom in the grammar: outputs look like noise, not a family.
+- Patterns behind body copy.
+- Colours outside the brand palette.
+
+## How to verify
+
+- Render the same seed twice (server and client): identical SVG markup.
+- `palate shoot`: patterns behind content are low contrast; text sits on solid surfaces.
+- A contact sheet of 20 seeds looks like one family with clear variety.
+
+## Examples
+
+- Seen on GitHub (https://github.com): accounts without a photo get an "identicon", a symmetric pixel pattern generated from the account, so every default avatar differs but belongs to one style.

package/kb/moves/gentle-error-nudge.md

@@ -0,0 +1,59 @@
+---
+id: gentle-error-nudge
+name: An error that nudges, not shouts
+kind: sound-free-feedback
+fits: [calm, friendly, crafted, saas, productivity, consumer, minimal, honest]
+avoid: [playful-kids, gaming]
+signature: false
+effort: s
+perf: "one short transform keyframe (≤ 300 ms) on the field; no layout change, error text space reserved"
+a11y: "aria-invalid plus aria-describedby to the message; focus returns to the field; the message says what to do; the shake is skipped under reduced motion"
+pairs_with: [tactile-button, honest-progress-narration, copy-confirmation]
+deps: none
+---
+
+## What it is
+
+When a field is wrong, it moves sideways a few pixels twice (like a head shaking "not quite"), its border takes the error colour, focus returns to it, and one line below says exactly what to fix: "Enter a full email address, like you@studio.com."
+
+## Why it works
+
+- A small horizontal shake is a physical "no" people read instantly, even out of the corner of the eye, without needing red everywhere.
+- Returning focus to the field removes a step: the user can type the fix immediately.
+- A specific, example-led message turns blame into instruction.
+
+## When to use / when not
+
+Use for short forms (sign-up, sign-in, coupon, invite code), and for submit attempts with an invalid field.
+
+Not for: errors that aren't the user's (network, server): those need a calm message near the button and no shake, the fields untouched. Not for validation on every keystroke. Kids' and game contexts can go bigger; this is the restrained version.
+
+## Recipe
+
+1. **Classify the error.** Field errors (format, missing, taken) get the nudge on that field. System errors (offline, 500, rate limit) get a message by the submit button that says what happened and what to do ("Couldn't reach us. Check your connection and try again."), and the fields keep their values and look.
+2. **The nudge.** A keyframe on the field wrapper: `translateX` 0 → −4 px → 4 px → −2 px → 0 over 260 ms, `ease-out`. Trigger it by toggling a class (remove, force reflow with `void el.offsetWidth`, add) so repeated submits shake again.
+3. **State.** Border to the error colour (contrast ≥ 3:1 against the background), `aria-invalid="true"`, message linked with `aria-describedby`. An icon beside the message so colour isn't the only signal.
+4. **Reserve space** for one line of error text (`min-height`) or animate the message's height with `grid-template-rows: 0fr → 1fr` (200 ms) so the page below doesn't jump.
+5. **Focus.** Move focus to the first invalid field. Don't steal focus for system errors.
+6. **Clear on fix.** Remove the error when the value becomes valid (on input), not on blur, so the user sees it resolve.
+7. **Reduced motion:** no shake; the border, icon and message carry it.
+8. **No JS:** the server validates and re-renders the form with the same message and `aria-invalid`.
+9. **Messages:** write them with an example of a valid value; never "Invalid input".
+
+## Pitfalls
+
+- Shaking the whole form, or shaking for server errors that aren't the user's fault.
+- Big amplitudes (> 8 px) or long durations: comic, not gentle.
+- Clearing what the user typed on error.
+- Red text alone with no icon, or messages that appear far from the field.
+- Validating on every keystroke from the first character.
+
+## How to verify
+
+- `palate states` (forms failing, pressed twice, offline): each error says what happened and what to do; fields keep their values.
+- `palate animate --check`: the nudge is transform-only, under 300 ms, absent under reduced motion; no layout shift below the field.
+- Keyboard: after a failed submit, focus is on the invalid field; screen reader reads the message.
+
+## Examples
+
+- palate's own site (`Waitlist.tsx`): a bad email refocuses the field with "Enter a full email address, like you@studio.com."; network and rate-limit failures leave the fields alone and say what to do instead.

package/kb/moves/halftone-dot-imagery.md

@@ -0,0 +1,55 @@
+---
+id: halftone-dot-imagery
+name: Halftone and dot-matrix imagery
+kind: imagery
+fits: [retro, bold, editorial, technical, artsy, media, music, experimental]
+avoid: [luxury, clinical, finance-trust-first, accessibility-first]
+signature: true
+effort: m
+perf: "pre-rendered at build time (PNG/WebP, 1–2 colours compress well) or one CSS mask; a canvas version renders once, not per frame"
+a11y: "images keep real alt text; halftone never applied to text or UI; any reveal animation static under reduced motion"
+pairs_with: [duotone-photography, riso-print-texture, one-colour-brand-world, generative-brand-pattern]
+deps: "none for CSS/canvas; at build time a short Python (Pillow + numpy) or sharp script is fine"
+---
+
+## What it is
+
+Photos, portraits or product shots converted into a grid of dots whose size follows the image's tone, printed in one brand colour on paper or on a dark ground. The same dot grid can carry a LED/dot-matrix display for numbers or short words.
+
+## Why it works
+
+- Halftone is the visual language of print and early screens: it turns any photo, even an ordinary one, into a consistent, brand-coloured image.
+- It unifies mixed sources (team photos, product shots, stock you own) into one system.
+- Dots read from far as an image and from close as a pattern, which rewards looking.
+
+## When to use / when not
+
+Use when you have uneven photography to unify, for media, music, events, editorial and developer brands with a retro or industrial voice, and for portraits of real people (team, authors, customers).
+
+Not for luxury or beauty products where texture and colour fidelity matter, health/clinical contexts, or product UI screenshots (dots destroy legibility).
+
+## Recipe
+
+1. **Build-time conversion (preferred).** For each image: convert to luminance, optionally boost contrast (levels 5–95%), then on a grid of cell size `S` (6–10px at display size) draw a circle per cell with radius `r = (S/2) * sqrt(darkness) * 1.1` (the sqrt keeps area proportional to tone). Rotate the grid 45° for the classic look or keep 0° for a dot-matrix look. Render at 2× display size in one ink colour on a transparent or paper background; save PNG/WebP (two colours compress very well).
+2. **CSS-only alternative.** On a greyscale image, layer `background: radial-gradient(circle, #000 35%, transparent 36%) 0 0 / 8px 8px` as a mask with `mask-mode: luminance` combined with a contrast filter; this is approximate (equal dots), so use it for texture, not portraits.
+3. **Canvas (live).** If the image must respond (e.g. dots grow near the pointer), draw once to canvas, cache dot radii in a Float32Array, and only redraw on pointer move inside the image, with rAF; stop when idle. Mouse only; no animation under reduced motion.
+4. **Colour.** One ink (brand colour or near-black) on paper, or paper-coloured dots on a dark band. Two colours max (see duotone).
+5. **Dot-matrix numerals.** For a counter or status, draw digits from a 5×7 cell font as dots (`<svg>` circles generated from a bitmap), lit dots in ink, unlit at 10% opacity.
+6. Keep `alt` text and `width`/`height` on every image; no-JS sees the pre-rendered file.
+
+## Pitfalls
+
+- Cells too small: at 1x screens it moirés into grey. Test at 1x and 2x.
+- Halftoning UI screenshots or text: unreadable.
+- Applying it to a few images only: the system needs consistency across all imagery of a type.
+- Animating every dot every frame: costly and noisy.
+
+## How to verify
+
+- `palate shoot` at 1440 and 390: no moiré banding at either DPR; faces still recognisable at phone width.
+- File weights small (< 100 KB for a portrait).
+- JS off: images present; reduced motion: no live dot animation.
+
+## Examples
+
+- No public example cited; a long-standing print technique, recently common on developer-tool and music sites with an industrial voice.

package/kb/moves/hand-drawn-annotations.md

@@ -0,0 +1,55 @@
+---
+id: hand-drawn-annotations
+name: Hand-drawn annotations on real UI
+kind: imagery
+fits: [friendly, warm, crafted, education, productivity, saas, honest, playful]
+avoid: [luxury, enterprise-compliance, serious-news, clinical]
+signature: false
+effort: s
+perf: "inline SVG paths (< 2 KB each); draw-on with stroke-dashoffset, CSS only"
+a11y: "annotation text is real text (not baked into SVG paths), linked to what it points at; draw animation skipped under reduced motion"
+pairs_with: [screenshot-detail-crops, product-in-context, pointer-highlight-word, explorable-control]
+deps: none
+---
+
+## What it is
+
+Loose, pen-like arrows, circles and underlines drawn over real product UI, with a short handwritten-feeling note: "this updates live", "drag me". Like a designer marking up a print-out for you.
+
+## Why it works
+
+- It directs attention to the one detail that matters inside a busy screenshot.
+- The human mark softens a technical product and makes it feel explained by a person.
+- Contrast between precise UI and loose strokes makes both read better.
+
+## When to use / when not
+
+Use on onboarding, feature explainers, docs landings, education, and friendly SaaS. Excellent for pointing at the single interactive control on a page.
+
+Not for luxury, compliance-heavy enterprise, news, or medical contexts. Don't annotate everything: two or three marks per page.
+
+## Recipe
+
+1. **Draw the marks** as SVG paths yourself (a tablet, or hand-tweak a bezier): an arrow 60–120px long with a slight wobble and an open arrowhead, a loose ellipse that doesn't quite close, a quick underline. Stroke 2–2.5px, `stroke-linecap: round`, in the brand colour or a pen blue. No fill.
+2. **Notes as real text.** Use a readable hand-like face sparingly (or the brand font in italic) at 15–17px. Avoid Comic-style fonts. The note is HTML positioned next to the arrow, so it's selectable, translatable and read by screen readers.
+3. **Position** relative to the UI with absolute positioning in a container that scales with the UI (em or container units), so arrows stay on target at every width. On phones, either reposition or replace arrows with numbered callouts below.
+4. **Draw on.** When in view (IntersectionObserver, once), animate `stroke-dashoffset` from path length to 0 over 500–700ms, `cubic-bezier(0.65, 0, 0.35, 1)`, the note fading in 100ms after. Set `pathLength="1"` on the path so the CSS uses 1 as the length.
+5. **Fallback.** Without JS or with reduced motion, marks are simply drawn (dashoffset 0).
+6. **Link meaning.** If the note describes a control, give that control `aria-describedby` pointing at the note.
+
+## Pitfalls
+
+- Perfect geometric circles: they look like UI, not a pen. Wobble a little.
+- Notes baked into the image: unreadable to search, translation and screen readers.
+- Arrows that miss their target on phone widths.
+- Annotating obvious things ("this is a button").
+
+## How to verify
+
+- `palate shoot` at 1440 and 390: every arrow's tip lands on its target; notes don't overlap UI text.
+- `palate animate --check`: draw-on completes < 800ms, no layout shift; reduced motion shows the drawn state.
+- Accessibility tree: notes present as text.
+
+## Examples
+
+- No public example cited; the technique is common on friendly SaaS onboarding and education sites.