@palate/cli 0.0.0-stage → 0.0.2

package/kb/moves/lightweight-3d-object-hero.md

@@ -0,0 +1,59 @@
+---
+id: lightweight-3d-object-hero
+name: One lightweight 3D object as the hero
+kind: hero
+fits: [hardware, premium, bold, launch, consumer, technical, cinematic, ecommerce]
+avoid: [low-bandwidth, accessibility-first, daily-tool, data-dense-tool, government]
+signature: true
+effort: l
+perf: "glTF/GLB under ~1.5 MB with Draco or meshopt, poster image is the LCP, the 3D loads after idle; render on demand, cap DPR at 2, pause off screen"
+a11y: "canvas aria-hidden with an alt-equivalent caption; drag-to-rotate optional, never required; poster only under reduced motion"
+pairs_with: [scroll-scrubbed-product-film, dark-band-contrast-section, cursor-reactive-light]
+deps: "three (and @react-three/fiber + drei only if the project already uses React and needs more than one scene); justified only when there is a real object to show"
+---
+
+## What it is
+
+The first screen shows one real object (the device, the bottle, the chip, the keyboard) as a lit 3D model that turns slowly and responds to the pointer or a drag. One object, one material story, no scene.
+
+## Why it works
+
+- A physical product in 3D answers "what does it look like from the side, how big, what material" faster than a gallery.
+- Gentle response to the pointer makes the object feel present, which photos can't do.
+- One object on a quiet background reads premium; a whole 3D world reads like a tech demo.
+
+## When to use / when not
+
+Use when the product is a physical thing (hardware, packaging, a wearable) or has a true object metaphor the brand owns, and you have a real model (from CAD or a 3D artist).
+
+Not for software products (a floating abstract blob is stock 3D, a known slop tell), for audiences on slow devices or connections, or for pages whose job is a quick decision. Never generate a fake "3D glass shape" for a SaaS.
+
+## Recipe
+
+1. **Poster first.** Render the model to a still (the exact first frame) as AVIF/WebP. It is the LCP image, the no-JS and reduced-motion state, and the fallback if WebGL fails.
+2. **Model budget.** Decimate to < 100k triangles; bake lighting/AO into textures; KTX2 or WebP textures at 1–2K; compress geometry (Draco or meshopt). Target < 1.5 MB total.
+3. **Load late.** After `requestIdleCallback` (or when the hero is visible and the page is idle), dynamically import `three` and the loader. Never block first paint on it.
+4. **Render on demand.** No continuous loop: render when the pointer moves, during a slow idle turn (0.1 rad/s max), and stop when settled. Pause with IntersectionObserver when off screen and on `visibilitychange`.
+5. **Pointer response.** Map pointer position to a small rotation (±12° yaw, ±6° pitch) with damping (exponential, τ ≈ 150ms). Drag to rotate fully only if the product benefits; don't hijack page scroll on touch (`touch-action: pan-y`).
+6. **Crossfade.** When the first WebGL frame is ready, fade the canvas in over the poster (200ms opacity) so there is no pop. Match camera and lighting to the poster exactly.
+7. **Caps.** `renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`; tone mapping ACES or AgX; one environment map (small HDR or a baked gradient), one key light.
+8. **Reduced motion / no WebGL / Save-Data:** keep the poster, skip loading three entirely.
+
+## Pitfalls
+
+- Loading three.js in the main bundle: a 600 KB tax for a hero.
+- A continuously spinning object: dizzying, and it burns battery.
+- Model doesn't match the poster: a visible jump on swap.
+- Abstract shapes for a software product: reads as AI-generated.
+- Scroll hijack on phones while dragging.
+
+## How to verify
+
+- `palate shoot` with JS off: the poster shows, same crop as the live model.
+- Lighthouse/LCP: the poster is the LCP element; the 3D chunk loads after it.
+- `palate animate --check`: no layout shift on swap; under reduced motion nothing moves and no WebGL context is created.
+- CPU idle when the pointer is still and the hero is off screen.
+
+## Examples
+
+- No public example cited; the pattern is common on consumer hardware product pages that let you turn the device.

package/kb/moves/line-engraving-from-image.md

@@ -0,0 +1,63 @@
+---
+id: line-engraving-from-image
+name: Line engraving made from an image
+kind: imagery
+fits: [crafted, heritage, editorial, calm, nature, artsy, premium, publishing, cultural]
+avoid: [playful-kids, gaming, energetic, low-bandwidth, data-dense-tool]
+signature: false
+effort: m
+perf: "generated offline; 8-colour palette PNG or WebP per size (no runtime cost beyond the image); never let the browser resample it"
+a11y: "decorative unless it carries content (then real alt text); keep text off dense hatching or give it a paper halo"
+pairs_with: [engraving-colour-lens, hero-paints-itself-in, museum-painting-backdrop, one-colour-brand-world]
+deps: "offline only: Python with numpy, scipy and Pillow (not shipped to the browser)"
+---
+
+## What it is
+
+A script that turns a photograph or painting into a one-ink line engraving on paper, like a banknote or an old map: directional hatching whose weight follows the image's tone, lines that bend with the forms, crosshatch in the shadows and fine contour lines. It produces a brand-coloured illustration from any picture you are allowed to use, in minutes.
+
+## Why it works
+
+- Line work signals craft and age; one ink in the brand colour makes any picture belong to the brand.
+- It quiets a busy picture enough to put text on it, while keeping its shapes recognisable.
+- It is a register you can pair with the colour original (a lens, a paint-in), which gives you a story to tell.
+
+## When to use / when not
+
+Use for heritage, editorial or crafted brands, footers and closing bands, chapter openers, or as the "before" in a restore/reveal move. Works best on pictures with a clear horizon, strong silhouettes and a good tonal range.
+
+Not for: playful or kids' brands, tiny thumbnails (hatching turns to mush under ~600 px wide), or pictures you don't have rights to (CC0 or your own only).
+
+## Recipe
+
+Method (palate's `etch.py`, written for this purpose; reimplement it, the steps are what matter):
+
+1. **Prepare.** Load the image, trim any frame edge, resize to the target width (make one file per display size: 1200, 1600, 2400; never scale line art in the browser). Compute luminance `L = 0.2126 R + 0.7152 G + 0.0722 B`. If one hue reads too dark (red clouds), let some of that channel through.
+2. **Tone.** Blur `L` slightly (σ ≈ 1.2 px at 2400 wide; scale every radius by width/2400). Rank-equalise it (each pixel's percentile) so near-black areas spread across the whole range, and mix in local contrast (`(a − blur(a)) / local std` at two radii, ~40 px and ~12 px) so detail lifts out of the darks. `dark = 1 − tone`.
+3. **Leave room for text.** Multiply `dark` by a smoothstep fade over the area where text will sit (e.g. the sky thins out toward the top).
+4. **Flow field.** Lines run roughly horizontal and bend with the forms: the phase of pass 1 is `(y + a·blur(L, ~14 px) + b·noise) / spacing`, with a smoothly blurred noise field so lines wobble like a hand. Spacing ≈ 5 px at 2400 wide.
+5. **Lines with weight.** For a phase field `p` and a weight `w` (fraction of the period that is ink), ink = distance from the line centre `|frac(p) − 0.5| · spacing` compared to `w · spacing / 2`, antialiased over ~0.75 px. Weight follows `dark` (pass 1: up to ~0.58).
+6. **Sub-pixel lines become dashes.** Where a line would be thinner than one pixel (pale sky), draw it at one-pixel weight but broken into dashes by a stretched noise threshold, the way an engraver lets a line run out. Hairlines thinner than a pixel turn to moiré on screen.
+7. **Crosshatch.** Pass 2 at ~38°, bending slightly with the large forms, only where `dark > 0.56`; pass 3 at ~−52°, only in the deepest shadows (`dark > 0.8`). Combine passes with `max`.
+8. **Contours.** A difference of Gaussians (σ 1.0 and 2.6) thresholded on the dark side of edges draws hills, trees and shores; multiply by the text fade.
+9. **One ink, eight levels.** Quantise coverage to 8 levels, mix paper and ink colours (e.g. paper `#F5F8F5`, ink a deep brand green), and save as an 8-colour palette PNG (no dithering); convert to WebP for the web. For a paint-in, write each pass to its own channel of one PNG instead.
+10. **The colour twin.** Save the original cropped and sized exactly like the engraving (and lift very dark areas with a gentle gamma, ~0.8, no hue shift) for any reveal.
+11. **Serve** with plain `<img srcset>` per size (`sizes="100vw"`), `decoding="async"`, lazy if below the fold; in Next use `<img>`, not `next/image`, so the hatching is never resampled.
+
+## Pitfalls
+
+- Uniform straight hatching: it looks like a filter. Lines must bend with the forms and vary in weight.
+- One file scaled to every width: moiré. Generate per size.
+- Grey-on-grey: use a real ink colour and a warm or tinted paper, not pure black on white.
+- Too dense where text sits: fade the hatching there, or the text needs heavy shadows.
+- Using a copyrighted photo: the output is a derivative. CC0 or your own pictures only.
+
+## How to verify
+
+- View at 100% and 200%: no moiré bands, no sub-pixel grey haze in light areas; shapes recognisable from across the room (squint test).
+- `palate shoot` at 1440 and 390: text on the engraving passes contrast; the right size file is chosen at each width.
+- Overlay the colour twin at 50% opacity: edges line up exactly.
+
+## Examples
+
+- palate's own site: the footer (Church's "Twilight in the Wilderness") and the hero paint-in (Constable's "Wivenhoe Park"), both engraved in emerald by palate's own hatching scripts.

package/kb/moves/link-preview-peek.md

@@ -0,0 +1,57 @@
+---
+id: link-preview-peek
+name: Link preview peek
+kind: interaction
+fits: [editorial, publishing, docs, education, media, developer, crafted]
+avoid: [ecommerce, playful-kids, low-bandwidth, minimal]
+signature: false
+effort: m
+perf: "previews from a build-time JSON (title, one line, small image); fetched on first hover intent, cached; no iframes"
+a11y: "supplementary only: the link works normally; preview opens on hover intent or focus, closes on Esc; not announced as a dialog; nothing in it is essential"
+pairs_with: [editorial-grid-pull-quotes, story-led-long-scroll, command-palette-site-nav, scroll-progress-chapters]
+deps: none
+---
+
+## What it is
+
+Hovering (or focusing) an internal link in long-form text shows a small card with where it goes: the page title, its first line and a small image, so the reader can decide whether to follow without losing their place. Like footnotes that come to you.
+
+## Why it works
+
+- Reading is fragile: every click away costs the thread. A peek answers "is this worth leaving for?" in a glance.
+- It makes a body of writing feel connected, a sign of an editorial product with depth rather than a pile of pages.
+- It's a quiet craft detail that regular readers notice and come to rely on.
+
+## When to use / when not
+
+Use in essays, docs, glossaries, changelogs and knowledge bases with many internal links.
+
+Not for: shops, marketing pages with few links, touch-only audiences (it never shows there, which is fine but means little payoff), external links you can't describe reliably, or as a place to hide required information.
+
+## Recipe
+
+1. **Data.** At build time, write `/previews.json`: `{ "/docs/caching": { title, excerpt (≤ 140 chars), image? } }` for internal pages only.
+2. **Intent.** On `pointerenter` of an internal `<a>` inside the article (mouse only), start a 350 ms timer; cancel on `pointerleave`. On `focus` via keyboard (`:focus-visible`), open after 500 ms. Load `previews.json` on the first intent and cache it.
+3. **Card.** One shared, `aria-hidden` card element positioned with `position: fixed`, placed below the link (or above if no room), clamped 8px from the viewport edges; width 320px; radius 12px; 1px border; a soft shadow. Content: 16:9 image (lazy, 320×180), title (15px semibold), excerpt (14px, 2 lines clamped), and the URL path in 12px mono.
+4. **Positioning.** Where CSS Anchor Positioning exists (Chromium 125+), set `anchor-name` on the hovered link and `position-anchor` + `position-try-fallbacks: flip-block` on the card; otherwise compute from `getBoundingClientRect` once on open.
+5. **Motion.** Fade in + 4px rise, 160 ms ease-out; out 100 ms. Moving between links while one is open swaps content without re-animating (feels fast). Under reduced motion: opacity only.
+6. **Close.** Pointer leaves both link and card (allow the pointer to travel onto the card with a 120 ms grace), Esc, scroll, or blur.
+7. **No JS / touch.** Links are just links. Optionally set `title` to nothing (don't rely on native tooltips).
+
+## Pitfalls
+
+- Opening instantly on hover: cards flash as the pointer crosses text. Use the intent delay.
+- iframes or live page fetches: slow, heavy, often blocked.
+- Previews on every link including nav and buttons: noise. Only links inside running text.
+- Card covering the line being read: place it below with an offset, flip only when needed.
+
+## How to verify
+
+- Hover a link for ~400 ms: card appears near it, inside the viewport at 1440 and on a narrow desktop window.
+- Sweep the pointer across a paragraph full of links: no flicker of cards.
+- Keyboard: focus a link, card appears; Esc closes; Tab continues normally.
+- Network: `previews.json` loads on first hover only.
+
+## Examples
+
+- Seen on Wikipedia (https://www.wikipedia.org): hovering a link to another article shows a small card with its lead image and first sentences.

package/kb/moves/live-data-ticker.md

@@ -0,0 +1,61 @@
+---
+id: live-data-ticker
+name: Live data ticker
+kind: data
+fits: [data-rich, technical, developer, finance, ai, saas, energetic, honest]
+avoid: [calm, quiet, luxury, low-bandwidth, accessibility-first]
+signature: false
+effort: m
+perf: "one fetch or SSE stream; one rAF-free update per tick (≥ 2 s apart); digits roll with transform only, tabular figures so nothing reflows"
+a11y: "values in real text; the live region announces at most once a minute, never every tick; pause control; static under reduced motion"
+pairs_with: [inline-sparklines-in-copy, real-world-data, dark-band-contrast-section, footer-live-status]
+deps: none
+---
+
+## What it is
+
+A small strip or panel of real numbers from the product that update while the visitor watches: requests served today, builds running now, the last deploy's duration. Changed digits roll into place; nothing else moves.
+
+## Why it works
+
+- A number that changes in front of you is proof the product is alive and used, which no adjective can claim.
+- Movement in a small area pulls the eye without dominating; it signals "real system" to technical buyers who distrust marketing copy.
+- Specific, odd numbers (12,847 not "10k+") read as measured rather than invented.
+
+## When to use / when not
+
+Use for infrastructure, developer tools, AI and data products, marketplaces, anything whose usage *is* the pitch, and only when the number is genuinely impressive or at least honest and growing.
+
+Not for: calm or luxury brands (a twitching number is noise), pages read by screen-reader-first audiences unless the announcement is throttled, and never when the numbers are small or you would be tempted to inflate them. A fake ticker is worse than none.
+
+## Recipe
+
+1. **Pick 1–3 real metrics** the backend can serve cheaply and that move at a visible rate (at least once every 10–30 s). Cumulative counters ("deploys today") beat rates that wobble. Write each with its unit and window: "2,431 deploys in the last hour".
+2. **Serve them honestly.** A cached endpoint (`/api/stats`, `Cache-Control: s-maxage=5`) or an SSE stream. Return the real value plus a timestamp. Never interpolate fake increments between polls; if you want smoothness, animate only from the last real value to the new real value.
+3. **Server-render the latest value** so no-JS visitors and crawlers see a real number with its "as of" time (`<time datetime>`).
+4. **Digits roll, layout holds.** Render each digit in a fixed-width slot (`font-variant-numeric: tabular-nums`, `display: inline-block; width: 1ch; overflow: hidden; height: 1lh`). A changed digit's column holds 0–9 stacked; set `transform: translateY(-N × 1lh)` with `transition: transform 400ms cubic-bezier(.23,1,.32,1)`. Unchanged digits don't move. Separators (commas) stay static.
+5. **Poll gently.** `setInterval` at 5–15 s, paused when `document.hidden` or the ticker is off screen (IntersectionObserver). Back off to 60 s after errors; on failure keep the last value and show "as of 2 min ago", never zero.
+6. **A11y.** The visible number is plain text in the DOM; the rolling digit stacks are `aria-hidden` with an `sr-only` copy of the real value. Don't put the ticker in an `aria-live` region; if updates matter, a separate polite region summarises once a minute at most. A small Pause button for anything that updates more often than every 5 s (WCAG 2.2.2).
+7. **Reduced motion:** swap the value without rolling (a 150 ms opacity cross-fade at most).
+8. **Small numbers:** if the metric is below what impresses (early stage), show a different honest metric (time saved per build, median latency), or skip the move.
+
+React/Tailwind: one `<Ticker value={n} />` that splits `n.toLocaleString()` into characters, keyed by position from the right so columns stay stable when the number gains a digit.
+
+## Pitfalls
+
+- Inventing increments between polls ("+1 every 300 ms"): it is a lie that technical visitors spot in the network tab.
+- Proportional figures: every change reflows the line. Always tabular-nums.
+- Rolling every digit on every update: visual noise. Only changed columns move.
+- A ticker in the hero that shows "0" during a cold start or outage.
+- Ten metrics at once: nothing reads; one lead number, one or two smaller.
+
+## How to verify
+
+- `palate shoot` with JS off: a real number with its "as of" time is visible.
+- `palate animate --check`: only `transform` changes in the digit columns; no layout shift; static under reduced motion.
+- Network tab: the value on screen always equals a value the API returned.
+- Screen reader: the number is read once; no repeated announcements while it ticks.
+
+## Examples
+
+- The pattern is common on infrastructure and status pages: a small counter of requests or deploys that ticks while you read. Describe it to the builder in these terms rather than copying any one site.

package/kb/moves/made-with-proof.md

@@ -0,0 +1,51 @@
+---
+id: made-with-proof
+name: The "made with" proof
+kind: layout
+fits: [honest, crafted, developer, saas, ai, community, minimal, launch]
+avoid: [enterprise-compliance, finance-trust-first, crisis]
+signature: false
+effort: s
+perf: "one line of text and an optional chip; nothing to load"
+a11y: "plain text; any chip is a real button or link with a clear name"
+pairs_with: [inspect-our-taste, colophon, honest-testimonial-wall]
+deps: none
+---
+
+## What it is
+
+One quiet, specific sentence near the close that says the page itself was made with the product, and how ("This page was designed with palate, from the founder's blind picks, a critique he agreed with, and the rules palate learned from them"), optionally followed by a way to check it (inspect the page, view the source, see the build log).
+
+## Why it works
+
+- The page is the one demo every visitor has already seen in full. Saying the product made it turns the whole visit into proof, retroactively.
+- Specifics ("from his blind picks…") make it believable; a generic "Built with X" badge doesn't.
+- A link to verify it shows confidence.
+
+## When to use / when not
+
+Use when it's true and the product makes things people can see (design, site builders, writing, image, code tools). Put it near the final call to action or in the footer.
+
+Not for: products that didn't make the page (don't stretch it), or regulated pages where a playful claim distracts from trust.
+
+## Recipe
+
+1. Write one sentence: "This page was [made] with [product], [how, in specifics]." 14 px, muted grey, max ~600 px wide, `text-pretty`, centred under the closing section or in the footer.
+2. Add a way to check it directly under: a small text button ("Inspect this page", with a `<kbd>` hint on desktop) that opens an inspector, or a link to the repo, the prompt history, or a write-up.
+3. Mark it for any rationale overlay (`data-taste="made-with"`) so the overlay can explain it too.
+4. Nothing moves; no JS needed except for whatever the chip opens.
+
+## Pitfalls
+
+- A badge with the product logo and "Made with" and nothing else: it's an ad, not proof.
+- Claiming more than is true ("built entirely by AI" when people finished it).
+- Placing it in the hero: it competes with the headline; it lands better as a reveal at the end.
+
+## How to verify
+
+- The sentence names specifics and is true; the verify link works.
+- `palate shoot`: it's visible above the footer at 1440 and 390, in muted type, not competing with the CTA.
+
+## Examples
+
+- palate's own site: "This page was designed with palate, from the founder's blind picks, a critique he agreed with, and the rules palate learned from them," followed by "Inspect this page (P)".

package/kb/moves/magnetic-buttons.md

@@ -0,0 +1,55 @@
+---
+id: magnetic-buttons
+name: Magnetic button (one, sparingly)
+kind: interaction
+fits: [playful, agency, portfolio, bold, tactile, experimental, artsy]
+avoid: [finance-trust-first, enterprise-compliance, accessibility-first, data-dense-tool, daily-tool, government]
+signature: false
+effort: s
+perf: "transform-only on one element; listener attached only while the pointer is within its zone"
+a11y: "mouse-only; the button's hit area and focus ring never move away from where a click lands; off for touch, keyboard and reduced motion"
+pairs_with: [tactile-button, cursor-reactive-light, calm-motion-system]
+deps: none
+---
+
+## What it is
+
+One primary button that leans toward the cursor as it approaches, a few pixels, as if magnetised, and springs back when the cursor leaves. Its label can move a little further than its body for a sense of depth.
+
+## Why it works
+
+- A control that responds before you touch it feels alive and inviting; it says "this is the thing to press".
+- Used once, it becomes a small signature of a studio's hand. Used everywhere, it's a gimmick that makes every target harder to hit.
+
+## When to use / when not
+
+Use **sparingly**: one element per page, the main call to action on an agency, portfolio or playful launch page, mouse only, with a small pull.
+
+Not for: forms, nav links, lists of buttons, finance or compliance-heavy products, accessibility-first products, dense tools, anything people click many times a day. Never on more than one element per page. If you're unsure, don't.
+
+## Recipe
+
+1. **Zone.** The magnet zone is the button's rect expanded by ~40px on each side. Listen for `pointermove` on a wrapper of that size (passive), mouse only (`pointerType === "mouse"` and `(hover: hover) and (pointer: fine)`), and not under reduced motion.
+2. **Pull.** Offset from the button centre: `dx = (x − cx)`, `dy = (y − cy)`. Translate the button by `dx * 0.25, dy * 0.25`, clamped to **±8px**; the label inside by an extra `±3px` in the same direction. Write transforms in a rAF.
+3. **Ease.** While inside: `transition: transform 150ms cubic-bezier(.23,1,.32,1)` (or lerp at τ ≈ 80 ms). On leave: return to 0 over 400 ms with the same ease-out, or a spring (stiffness 300, damping 20 for a tiny overshoot only on playful brands).
+4. **Hit area.** Pull the visual layer, not the element that receives clicks: put the transform on an inner span and keep the `<button>`/`<a>` box static, so the click always lands where the user aimed.
+5. **Press.** On `:active`, scale the inner to 0.97 (100 ms) and drop the pull.
+6. **Fallbacks.** Touch, keyboard, reduced motion and no JS: a normal button with normal hover/focus styles. The magnet adds nothing essential.
+
+## Pitfalls
+
+- Magnetising every button and link: targets drift, misclicks rise, the page feels unstable. One element.
+- Moving the real hit area: clicks land on the gap where the button used to be.
+- Big pulls (20px+): the button looks like it's escaping, which is the opposite of inviting.
+- Leaving the listener on the whole document: pointless work on every move.
+
+## How to verify
+
+- `palate animate --check` with a scripted pointer approach: the button shifts ≤ 8px, returns to rest on leave; no layout shift.
+- Count magnetic elements in the DOM: exactly one.
+- Touch emulation, keyboard Tab and reduced motion: no movement.
+- Click near the edge of the button while it is pulled: the click registers.
+
+## Examples
+
+- The pattern: a design studio's "Start a project" button that leans a few pixels toward the cursor and settles back when it leaves; nothing else on the page does it.

package/kb/moves/marquee-done-right.md

@@ -0,0 +1,58 @@
+---
+id: marquee-done-right
+name: A marquee done right
+kind: motion
+fits: [saas, developer, community, energetic, launch, b2b, ai, friendly]
+avoid: [calm, luxury, accessibility-first, serious-news, heritage]
+signature: false
+effort: s
+perf: "one CSS keyframe on transform of a duplicated list; no JS; ~40 s per loop"
+a11y: "the duplicate list is aria-hidden; pauses on hover and focus-within; under reduced motion it becomes one still, wrapped, centred row"
+pairs_with: [honest-testimonial-wall, live-data-ticker, made-with-proof]
+deps: none
+---
+
+## What it is
+
+A slow horizontal belt of logos or names (stacks you integrate with, customers who said yes, agents you run in), seamless, faded at both edges, at a size you can actually read, that pauses when you point at it and becomes a still row for reduced motion.
+
+## Why it works
+
+- Motion signals "there are many of these" without a wall of logos; the slow drift is ambient, not attention-grabbing.
+- Edge fades make it feel like it continues beyond the page.
+- Done right (readable, pausable, honest), it's a calm proof strip; done wrong, it's the most generic element on the web.
+
+## When to use / when not
+
+Use for a list of 8+ real items where the point is breadth (integrations, frameworks, community projects). Once per page, after the main demo, never as the hero.
+
+Not for: fewer than ~6 items (show a still row), logos you don't have permission or a real relationship to show, calm or luxury brands, or pages already full of motion.
+
+## Recipe
+
+1. Markup: a belt (`overflow-hidden`, max-width of the content, with padding) containing a track (`display:flex; width:max-content`) with the list twice: the first `<ul aria-label="Frameworks">`, the second identical with `aria-hidden` and a `copy` class.
+2. Items: mark 28–32 px tall in the brand's official colour (mask the SVG with `mask-image` and fill with the brand colour, or use the official coloured SVG) plus the name in 16 px medium, padding 28–36 px each side. Readable, not faint texture.
+3. Motion: `@keyframes belt { to { transform: translateX(-50%) } }` on the track, `40–45s linear infinite`. The two copies make −50% a seamless loop.
+4. Edge fade: `mask-image: linear-gradient(to right, transparent, #000 14%, #000 86%, transparent)` on the belt.
+5. Pause: `.belt:hover .track, .belt:focus-within .track { animation-play-state: paused }`.
+6. Reduced motion: no animation, no transform, hide the copy, wrap the first list and centre it (`flex-wrap: wrap; justify-content: center; row-gap: 20px`), drop the mask.
+7. A one-line caption above it in plain words ("Works inside your stack, with the components you already have").
+8. No JS needed; without JS it still runs (CSS) and still respects reduced motion.
+
+## Pitfalls
+
+- Greyed-out, 16 px logos as "texture": nobody can read them.
+- Speed: under 25 s per loop feels frantic; over 60 s looks stuck.
+- Gaps or a jump at the loop point: the two copies must be identical, with the same trailing padding.
+- Several marquees, or marquees in opposite directions: pick one.
+- Claiming customers you don't have.
+
+## How to verify
+
+- `palate animate --check`: belt moves, no jump at the seam; reduced motion shows a still wrapped row; nothing else on the page shifts.
+- Hover: it stops. Screen reader reads the list once.
+- `palate shoot` at 390: marks still ≥ 24 px tall.
+
+## Examples
+
+- palate's own site: the frameworks belt after the demo, official colours at 32 px, 42 s loop, pausing on hover and still under reduced motion (`StackMarquee.tsx`).