@palate/cli 0.0.0-stage → 0.0.2

package/kb/craft/SOURCES.md

@@ -0,0 +1,48 @@
+# Sources to follow
+
+A reading list of the people and sites that were most useful for kb/craft. It lists sources only, for following and citing. Do not scrape their designs, copy their pages, or train on their sites; when an entry in kb/craft cites them, it summarises the idea in our own words and links back.
+
+## Design engineers and designers
+
+- **Rauno Freiberg**: https://rauno.me/craft (essays: Invisible Details of Interaction Design, Novelty, Designing Depth, Contrasting Aesthetics, Crafting the Next.js Website, What will you ship?); course: https://devouringdetails.com; X: https://x.com/raunofreiberg. Best source on interaction metaphors, frequency vs novelty, and motion rhythm on marketing pages.
+- **Emil Kowalski**: https://emilkowal.ski (7 Practical Animation Tips, You Don't Need Animations, Agents with Taste, Building a Toast Component, Developing Taste, Friction as a Feature); course: https://animations.dev; X: https://x.com/emilkowalski. Concrete durations, easing, press states; author of Sonner and Vaul.
+- **Jakub Krehel**: https://jakub.kr/writing (Details That Make Interfaces Feel Better, Less Is More, Understanding Gradients); X: https://x.com/jakubkrehel. Shadow stacks, concentric radii, stagger values; his writing list includes the Interfere site write-up.
+- **Benji Taylor**: https://benji.org (Family Values; Annotating for agents). Motion as product identity; the delight-versus-frequency curve.
+- **Paco Coursey**: https://paco.me/writing. Small implementation details (favicons in dark Safari, theme-switch transitions).
+- **Josh W. Comeau**: https://www.joshwcomeau.com (Designing Beautiful Shadows, spring physics, prefers-reduced-motion, How I Built My Blog). Shadows, springs, accessible motion, interactive explanation.
+- **Anthony Hobday**: https://anthonyhobday.com/sideprojects/saferules/ and https://anthonyhobday.com/sideprojects/visualtechniques/. Numeric "safe rules" and a large catalogue of visual techniques.
+- **Steve Schoger / Refactoring UI**: https://www.refactoringui.com, X: https://x.com/steveschoger. Visual-design tips (summarised in our own words only; the book is paid).
+- **Sara Soueidan**: https://www.sarasoueidan.com/blog/focus-indicators/. The definitive guide to focus indicators.
+- **Bret Victor**: https://worrydream.com/ExplorableExplanations/. Explorable explanations; the basis for interactive demos.
+- **Alex Murrell**: https://www.alexmurrell.co.uk/articles/the-age-of-average. Why everything converges, and why that is the opening.
+- **Detail** (account collecting interface details): https://x.com/detaildotdesign.
+- **Karri Saarinen / Linear**: https://linear.app/now (How we redesigned the Linear UI). Colour systems in LCH, restraint, alignment. (Profile: https://sequoiacap.com/article/linear-spotlight/)
+- **Mariana Castilho**: interview at https://dive-club.beehiiv.com/p/blastoise. We could not find her own published writing; follow her via that profile.
+
+## Team and company writing
+
+- **Vercel Web Interface Guidelines**: https://vercel.com/design/guidelines. The densest single checklist for interaction, forms, content and animation.
+- **Interfere**: https://interfere.com/blog/how-we-built-interferes-new-website. How a product site shows the product in code.
+- **Stripe**: https://stripe.com/blog/connect-front-end-experience. Code-built product animation and performance on a landing page.
+- **Anthropic**: https://claude.com/blog/improving-frontend-design-through-skills. Why models converge on generic UI and how direction counters it.
+- **Sanity**: https://www.sanity.io/blog/the-logo-soup-problem and Dan Paquette https://danpaquette.net/read/automatically-resizing-a-list-of-icons-or-logos-so-theyre-visually-proportional/. Logo wall sizing.
+- **Close**: https://making.close.com/posts/ultimate-guide-to-timestamps. Timestamp rules.
+- **Apple, Designing Fluid Interfaces (WWDC18)**: https://developer.apple.com/videos/play/wwdc2018/803/. Springs, interruptibility, gestures.
+- **Chrome for Developers, scroll-driven animations**: https://developer.chrome.com/docs/css-ui/scroll-driven-animations.
+- **WebKit blog, text-wrap: pretty**: https://webkit.org/blog/16547/better-typography-with-text-wrap-pretty/.
+
+## Research and reference
+
+- **Nielsen Norman Group**: https://www.nngroup.com (animation duration, skeleton screens, empty states, tooltips, error messages, icon usability, response times, scrolljacking, horizontal attention, layer-cake scanning, glassmorphism).
+- **Viget**: https://www.viget.com/articles/a-bone-to-pick-with-skeleton-screens/. The skeleton-screen study that disagrees with conventional wisdom.
+- **Butterick's Practical Typography**: https://practicaltypography.com/summary-of-key-rules.html.
+- **W3C WCAG Understanding docs**: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html.
+- **APCA**: https://github.com/Myndex/apca-introduction (contrast model debated against WCAG 2).
+
+## AI-slop critiques (useful as tell lists; quality varies)
+
+- **avoid-ai-design catalogue**: https://github.com/funboy322/avoid-ai-design. Most complete list, including the second-order "tasteful" defaults.
+- **Mania Design, Spot the Slop**: https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/.
+- **Developers Digest, 16 patterns**: https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it.
+- **925 Studios**: https://www.925studios.co/blog/ai-slop-design-tells.
+- **Adam Wathan on the indigo default**: https://x.com/adamwathan/status/1953510802159219096.

package/kb/craft/creativity.md

@@ -0,0 +1,55 @@
+# Creativity: getting original work instead of the default
+
+How to use: run these before designing (as prompts for direction) and after (as a critique of whether the result has a point of view). Detection here is usually a swap test: replace the logo and product name; if the page could belong to any company, the entry applies.
+Novelty is a budget, not a goal. Most of the screen should be familiar; the entries below are about spending the rest well.
+
+## Why the default happens
+
+- **[C01] Undirected output converges.** Detect: no named direction in the brief (no typeface, palette, reference or tone). Models sample the most common patterns in training data, which Anthropic calls distributional convergence; designers describe slop as AI output nobody directed rather than AI output as such. Fix: before generating, write down a named aesthetic direction, a typeface, a palette source and a layout principle. (Source: https://claude.com/blog/improving-frontend-design-through-skills, https://x.com/designcoursecom/status/2080802781087089047, https://prg.sh/ramblings/Why-Your-AI-Keeps-Building-the-Same-Purple-Gradient-Website)
+- **[C02] Banning defaults moves the default.** Detect: the output avoided purple and Inter but landed on Space Grotesk, cream + terracotta or near-black + lime. Fix: ban lists help but are not enough; vary light/dark, type and aesthetic across generations and track what this project used recently. (Source: https://claude.com/blog/improving-frontend-design-through-skills, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[C03] Sameness is the market, and the opening.** Detect: the page mirrors the category leader's section order and look. Sameness comes from shared frameworks, templates and copying competitors; Alex Murrell's "Age of Average" shows the same convergence in interiors, cars and brands. Fix: treat sameness as the opportunity; decide one place to zag. (Source: https://www.alexmurrell.co.uk/articles/the-age-of-average)
+
+## How strong designers get original work
+
+- **[C04] 90% familiar, 10% unexpected.** Detect: either nothing surprising, or surprise everywhere (custom cursors, novel scroll, odd navigation all at once). Rauno borrows the 60/30/10 colour rule: keep most of the experience familiar and put novelty where it pays. Fix: name the one or two places where this product does something unexpected; keep navigation, forms and controls conventional. (Source: https://rauno.me/craft/novelty)
+- **[C05] Spend novelty where the audience cares and where it is rare.** Detect: novel treatment on a daily task; a forgettable first-run. Onboarding is seen once, so it can carry more; intent sets tolerance (players accept more than people at work); novelty has a learning tax. (Source: https://rauno.me/craft/novelty, https://benji.org/family-values)
+- **[C06] A signature move tied to the brand.** Detect: no element that only this product would have. Good signatures echo something the brand already owns: Interfere pixelates the last word of its headline to echo its logo; Vercel's Ship site uses the full spectrum as a metaphor for "what will you ship"; the Next.js site's switchboard lights spell NEXT on hover. Fix: one signature per page, derived from the product's mark, domain or data, and it must carry meaning. (Source: https://interfere.com/blog/how-we-built-interferes-new-website, https://rauno.me/craft/vercel, https://rauno.me/craft/nextjs)
+- **[C07] Contrasting aesthetics, on purpose.** Detect: a page in a single pure style that feels forgettable. Pairing distinct aesthetics (a bitmap face with a Renaissance painting; retro objects in a minimal room) creates curiosity when it is sparing and crafted; keep one anchor constant while the rest varies (amo's wordmark changes typeface but never word, size, position or colour). Less suited to everyday productivity tools. (Source: https://rauno.me/craft/contrasting-aesthetics)
+- **[C08] Constraints as the engine.** Detect: a brief with no limits produces a median page. The Eameses described design as depending largely on constraints, and the designer's skill as recognising as many as possible. Rauno notes designing in only black and white forces creativity with layers, depth, shadows and spotlights. Fix: impose a real constraint (one colour, one typeface, no cards, the product's own material) and design inside it. (Source: https://www.hermanmiller.com/stories/why-magazine/design-q-and-a-charles-and-ray-eames/, https://x.com/raunofreiberg/status/1579874895022141440)
+- **[C09] References from outside the domain.** Detect: every reference is another SaaS landing page. Viral work becomes everyone's reference; look in old magazines and archives, workshops and factories, adjacent arts. Fix: bring at least one reference from outside software and say what you take from it (a material, a rhythm, a colour relationship). (Source: https://marioalessiani.substack.com/p/we-risk-designing-the-same-things, https://rauno.me/craft/contrasting-aesthetics)
+- **[C10] Articulate why a reference works.** Detect: "make it like Linear" with no stated reason. Collect 3–5 references, write what makes each work, and give that description to the model rather than the brand name; taste grows from asking why you like something. (Source: https://prg.sh/ramblings/Why-Your-AI-Keeps-Building-the-Same-Purple-Gradient-Website, https://emilkowal.ski/ui/developing-taste)
+- **[C11] Explore wide, then converge.** Detect: one direction, polished from the start. Interfere explored dozens of completely different directions in a one-week identity sprint before choosing. Fix: generate several genuinely different directions (different type, colour and layout ideas, not variants of one), compare them, then commit. Building A and B is a form of thinking only if you actually compare and discard. (Source: https://interfere.com/blog/how-we-built-interferes-new-website, https://emilkowal.ski/ui/friction-as-a-feature)
+
+## Typography and colour as identity
+
+- **[C12] Type is the fastest signal of authorship.** Detect: the display face is a default or a currently fashionable free font. Fix: one distinctive face used decisively; pair with high contrast (display + mono, serif + geometric sans); use extreme weight contrast (200 vs 800) and big size jumps (3x) rather than timid steps. **Disagreement:** restraint camps (Hobday: no more than two typefaces; Linear: Inter Display + Inter) get identity from tuning a quiet face rather than a loud one. Both reject the unchosen default. (Source: https://claude.com/blog/improving-frontend-design-through-skills, https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/, https://anthonyhobday.com/sideprojects/saferules/, https://linear.app/now/how-we-redesigned-the-linear-ui)
+- **[C13] Colour from the product, with a dominant hue.** Detect: an evenly spread, timid palette, or colour that signals nothing. Fix: a dominant colour with sharp accents rather than many equal colours; each colour has a function; draw palettes from IDE themes, cultural aesthetics or the product's material. (Source: https://claude.com/blog/improving-frontend-design-through-skills, https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/)
+- **[C14] Build colour systems, not swatches.** Detect: hand-picked hex values that look uneven across hues. Linear generates themes in LCH from three inputs (base, accent, contrast) instead of 98 variables, and reduced chroma for a more neutral, timeless feel; OKLCH/OKLab interpolation keeps gradients vivid. (Source: https://linear.app/now/how-we-redesigned-the-linear-ui, https://jakub.kr/work/gradients)
+
+## Texture, illustration, depth
+
+- **[C15] Atmosphere instead of flat fills.** Detect: solid white or solid near-black sections with nothing in them but cards. Fix: layered gradients, patterns, noise, halftone or dot grids that fit the aesthetic (Interfere's halftone skyline; the Next.js grid built from repeating gradients with a mask, a technique borrowed from Stripe). Pair complex backgrounds with simple foregrounds, never complex on complex. (Source: https://claude.com/blog/improving-frontend-design-through-skills, https://interfere.com/blog/how-we-built-interferes-new-website, https://rauno.me/craft/nextjs, https://anthonyhobday.com/sideprojects/saferules/)
+- **[C16] Illustration built in code, with a meaning.** Detect: raster hero art or stock 3D shapes. Code-built visuals stay sharp, respond, and can animate: Stripe drew a laptop in under 1KB of CSS; Vercel builds marketing visuals as React components. Fix: draw illustrations from the product's own shapes and states, in code. (Source: https://stripe.com/blog/connect-front-end-experience, https://rauno.me/craft/vercel)
+- **[C17] Depth through layering.** Detect: everything on one plane. Fix: blur and fade background layers, dim the backdrop behind overlays, put out-of-focus objects in front of or behind the focal point, tied to the content's meaning. (Source: https://rauno.me/craft/depth)
+- **[C18] A technique catalogue beats the default card.** Detect: every section is the same card on the same background. Hobday's visual-techniques index lists over 200 alternatives (background shapes, stroke treatments, cut-outs, offset borders, tilted elements); pick one or two that fit and repeat them as the page's language. (Source: https://anthonyhobday.com/sideprojects/visualtechniques/)
+- **[C19] Build the effect or cut it.** Detect: stock effect components (beams, meteors, spotlight) used as shipped. Fix: an effect that comes from the product, or none. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+
+## Repetition and rhythm
+
+- **[C20] A device used everywhere stops working.** Detect: the same kicker, number style, card or reveal in every section. Repetition dulls novelty the way a repeated word loses meaning; Vercel's Ship site never put two high-novelty moments back to back. Fix: give each section a different entry point; let one recurring element be the system and everything else vary. (Source: https://rauno.me/craft/novelty, https://rauno.me/craft/vercel, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[C21] Motion as identity.** Detect: motion that could be on any site. Family made continuity its signature: "Continue" morphs into "Confirm" via shared letters, trays rise from the screen that triggered them, tabs slide toward the tapped tab. A single coherent motion idea, carried through, is a brand. (Source: https://benji.org/family-values)
+
+## Words
+
+- **[C22] Concrete words you can picture.** Detect: abstract claims ("a better way to work"). Harry Dry's landing-page order is title, subtitle, visual, social proof, CTA, and his first copy test is whether the reader can visualise it. Fix: name specific numbers, objects and outcomes. (Source: https://x.com/thejustinwelsh/status/1508420178111041550, https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/)
+- **[C23] The domain's own vocabulary.** Detect: generic product words (Items, Records, Manage). Fix: use the words people already use on that platform or in that trade, as Linear does per platform. (Source: https://x.com/detaildotdesign)
+
+## Playfulness and explanation
+
+- **[C24] Whimsy that rewards attention.** Detect: a site with no moments of play at all, or play that blocks the task. Josh Comeau's site bends a rainbow toward the cursor and adds small spring micro-interactions to icons; the play lives in details you discover, never in the path. (Source: https://www.joshwcomeau.com/blog/how-i-built-my-blog-v2/)
+- **[C25] Let people manipulate the idea.** Detect: a concept explained only in prose and static diagrams. Bret Victor's explorable explanations: reactive documents where readers change an assumption and see the conclusion update. Fix: one control that changes an input and shows the effect. (Source: https://worrydream.com/ExplorableExplanations/, https://www.joshwcomeau.com/blog/how-i-built-my-blog-v2/)
+
+## Restraint
+
+- **[C26] Know what not to build.** Detect: features, sections or animations added because they were cheap to generate. As building gets cheaper, judgement about whether to build matters more; simplicity reads as more credible. Fix: for every section ask what is lost if it is removed. (Source: https://jakub.kr/writing/less-is-more, https://emilkowal.ski/ui/friction-as-a-feature)
+- **[C27] Ship static first, add motion after.** Detect: a page whose layout only works mid-animation. The Next.js team shipped a static version first, then layered animation in small follow-ups, and kept the design restrained rather than leaning on gradients or gimmicks. (Source: https://rauno.me/craft/nextjs)

package/kb/craft/details.md

@@ -0,0 +1,75 @@
+# Micro-detail craft
+
+How to use: these are the small parts that separate a finished product from a generated one. Check each entry against the DOM (computed styles, attributes, pseudo-elements) and a 200% zoom of the screenshot; most can be verified mechanically. Values are starting points from named practitioners, not laws; where they disagree it says so.
+
+## Buttons and press feedback
+
+- **[D01] Press state.** Detect: no `:active` style on buttons. A subtle scale-down on press makes the interface feel like it heard you. Fix: `transform: scale(0.97)` (0.97–0.98) on `:active` with a ~150ms transition; animate a child, not the hit area, if hover flickers. (Source: https://x.com/emilkowalski_/status/1952354760637505541, https://emilkowal.ski/ui/7-practical-animation-tips, https://emilkowal.ski/ui/agents-with-taste)
+- **[D02] Loading buttons keep their label.** Detect: label replaced by a spinner, or a spinner that flashes for 50ms. Fix: spinner beside the original label; show it only after ~150–300ms, keep it at least ~300–500ms once shown; disable at submission start (with an idempotency key), not before. (Source: https://vercel.com/design/guidelines)
+- **[D03] Interaction states out-contrast rest.** Detect: hover/active/focus colours lighter or equal in contrast to the resting state. Fix: each interactive state has more contrast than rest. (Source: https://vercel.com/design/guidelines)
+- **[D04] Button proportions.** Detect: tall buttons with tight sides. Fix: horizontal padding about twice the vertical; with an icon, slightly less padding on the icon side so it looks centred. (Source: https://anthonyhobday.com/sideprojects/saferules/, https://jakub.kr/writing/details-that-make-interfaces-feel-better)
+- **[D05] Focus that passes.** Detect: `outline: none` without replacement, single-colour rings that vanish on some backgrounds, dashed 1px rings, rings hidden under a sticky header. Fix: `:focus-visible` with an `outline` (survives forced-colours mode) plus `outline-offset`; at least 3:1 against adjacent colours and an area of a 2px perimeter; on mixed backgrounds a two-tone ring (dark outline + light box-shadow); ring follows the element's radius. (Source: https://www.sarasoueidan.com/blog/focus-indicators/, https://rauno.me/craft/nextjs, https://vercel.com/design/guidelines)
+- **[D06] Hit area bigger than the visual.** Detect: icon buttons whose clickable box equals a 16px glyph. Fix: at least 24px (44px on touch) via padding or a `::before` pseudo-element; label and checkbox share one target with no dead zone. (Source: https://vercel.com/design/guidelines, https://emilkowal.ski/ui/agents-with-taste)
+- **[D07] Cursor on buttons.** Detect: mixed cursors (some buttons pointer, some default). **Disagreement:** browsers, the CSS spec and Tailwind v4 give buttons the default arrow and reserve the hand for links (Adam Silver, Hidde de Vries); many teams and users expect the hand on anything clickable and restore it. Fix: pick one rule per product, apply it to every button and button-role element; links always get the hand. (Source: https://tailwindcss.com/docs/upgrade-guide, https://adamsilver.io/blog/buttons-shouldnt-have-a-hand-cursor/, https://hidde.blog/some-pointers-on-default-cursors/)
+
+## Inputs and forms
+
+- **[D08] Input basics.** Detect: inputs under 16px on mobile (iOS zooms), controls without a `<label>`, placeholder used as label, wrong `type`/`inputmode`, spellcheck on emails or codes. Fix: 16px+ on mobile; a label on every control; placeholders show an example value and end with "…"; correct `type`, `inputmode` and `autocomplete`. (Source: https://vercel.com/design/guidelines)
+- **[D09] Forgiving input.** Detect: typing blocked at a max length, paste disabled, trailing spaces causing errors. Fix: accept input and show feedback; block the submit past a limit, not the keystroke; trim trailing whitespace; allow pasting one-time codes. (Source: https://vercel.com/design/guidelines, https://x.com/detaildotdesign)
+- **[D10] Keyboard submission.** Detect: Enter does nothing in a single-field form; Enter submits a textarea. Fix: Enter submits single-input forms; ⌘/Ctrl+Enter submits textareas. (Source: https://vercel.com/design/guidelines)
+
+## Numbers, dates and text
+
+- **[D11] Tabular numbers where values are compared or change.** Detect: proportional digits in table columns, prices, timers, counters (columns jitter). Fix: `font-variant-numeric: tabular-nums` (or a mono face) in tables and live counters only; note some fonts, Inter included, change numeral shapes when it is on. (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://vercel.com/design/guidelines)
+- **[D12] Number formatting.** Detect: "eight deployments", "$12" next to "$12.50", "10MB", locale-blind separators. Fix: numerals for counts; one decimal rule per context for currency (0 or 2, never both); a non-breaking space between number and unit; format with the user's locale. (Source: https://vercel.com/design/guidelines)
+- **[D13] Timestamps.** Detect: "3 days ago" with no way to see the exact time, or full ISO dates for recent events. Fix: relative for recent items ("17m ago", "Yesterday"), absolute after about 7 days ("Oct 21"); omit the current year; a tooltip with full date, time and time zone on every timestamp; 12/24-hour from the locale. (Source: https://making.close.com/posts/ultimate-guide-to-timestamps, https://vercel.com/design/guidelines)
+- **[D14] Wrapping.** Detect: orphaned last words in headings, short last lines in paragraphs. Fix: `text-wrap: balance` for headings and captions (Chromium balances up to 4 lines), `text-wrap: pretty` for body (Chromium adjusts the last 4 lines). (Source: https://webkit.org/blog/16547/better-typography-with-text-wrap-pretty/, https://jakub.kr/writing/details-that-make-interfaces-feel-better)
+- **[D15] Glyph details.** Detect: `"`, `...`, `--`, broken "⌘ K" across lines. Fix: curly quotes, `…`, real dashes, `&nbsp;` inside glued terms (`10&nbsp;MB`, `⌘&nbsp;K`). (Source: https://vercel.com/design/guidelines, https://practicaltypography.com/summary-of-key-rules.html)
+- **[D16] Size-aware tracking and leading.** Detect: 64px headings at default tracking and 1.5 leading; all-caps labels at 0 tracking. Fix: tighten leading and tracking as text grows, loosen for small text; add 5–12% tracking to all-caps. (Source: https://anthonyhobday.com/sideprojects/saferules/, https://practicaltypography.com/summary-of-key-rules.html)
+- **[D17] Labels as a last resort.** Detect: "Email: x@y.com", "Phone: …" lists where the format already says what it is. Fix: drop labels the data explains; fold the label into the value ("12 left in stock"); demote labels on dashboards, promote them on dense spec sheets. (Source: https://www.refactoringui.com/previews/labels-are-a-last-resort)
+- **[D18] Font smoothing.** Detect: heavy, blurry text on macOS. Fix: `-webkit-font-smoothing: antialiased` at the root for thinner, crisper text (a taste call; apply once, globally). (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better)
+
+## Surfaces: borders, shadows, radii
+
+- **[D19] Shadow-as-border.** Detect: solid 1px grey borders on cards over images or tinted backgrounds. Fix: a layered ring that adapts to any background, e.g. `0 0 0 1px rgba(0,0,0,.06), 0 1px 2px -1px rgba(0,0,0,.06), 0 2px 4px rgba(0,0,0,.04)`; dark mode `0 0 0 1px rgba(255,255,255,.08)`; raise alphas slightly on hover and transition `box-shadow` only. (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://vercel.com/design/guidelines)
+- **[D20] Inset image outline.** Detect: photos and avatars bleeding into same-coloured backgrounds. Fix: `outline: 1px solid rgba(0,0,0,.1); outline-offset: -1px` (white at 10% in dark mode). (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better)
+- **[D21] Believable shadows.** Detect: single grey `0 4px 20px rgba(0,0,0,.25)` everywhere; shadows going in different directions. Fix: one light source for the whole UI; layer 2+ shadows; tint shadows toward the background hue; blur about twice the y-offset; as elevation grows, offsets and blur grow and opacity drops. Don't animate layered shadows. (Source: https://www.joshwcomeau.com/css/designing-shadows/, https://anthonyhobday.com/sideprojects/saferules/, https://vercel.com/design/guidelines)
+- **[D22] Depth in dark mode.** Detect: drop shadows on dark surfaces doing nothing. Fix: express elevation by making closer surfaces lighter, and make 1px borders lighter than both container and background on dark (darker than both on light). **Disagreement:** Hobday says no shadows in dark UIs; Jakub keeps a faint white ring as a border substitute. (Source: https://anthonyhobday.com/sideprojects/saferules/, https://jakub.kr/writing/details-that-make-interfaces-feel-better)
+- **[D23] One depth language.** Detect: some cards bordered, some shadowed, some tinted, with no rule. Fix: choose one depth technique and apply it everywhere. (Source: https://anthonyhobday.com/sideprojects/saferules/)
+- **[D24] Concentric radii.** Detect: computed child `border-radius` ≥ parent radius minus padding. Fix: outer = inner + padding (+ border); not needed for 0 or pill radii. (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://vercel.com/design/guidelines)
+- **[D25] Tinted neutrals and hue consistency.** Detect: pure greys on a blue-tinted UI; borders and shadows neutral on a tinted background. Fix: tint neutrals toward the interface hue (under 5% saturation); tint borders, shadows and text toward the background hue. (Source: https://anthonyhobday.com/sideprojects/saferules/, https://vercel.com/design/guidelines)
+- **[D26] Gradients without mud.** Detect: grey dead zone in the middle of a two-colour gradient; banding on fades to dark. Fix: interpolate `in oklab` (Tailwind 4 default) or `in oklch` (more vivid, may add hues you did not define); avoid CSS mask fades to dark, use background images. (Source: https://jakub.kr/work/gradients, https://vercel.com/design/guidelines)
+
+## Icons and alignment
+
+- **[D27] One icon family.** Detect: mixed stroke widths, filled and outline icons side by side, icons from two libraries. Fix: one set, one stroke weight, sized to its grid (16/20/24); one meaning per icon across the product; visible text labels except for the few universal icons (home, search, print). (Source: https://www.nngroup.com/articles/icon-usability/, https://vercel.com/design/guidelines)
+- **[D28] Icon weight next to text.** Detect: icons visually heavier than the label they sit beside. Fix: lower icon contrast (opacity or a lighter colour) and balance weight, size and spacing in the lockup. (Source: https://anthonyhobday.com/sideprojects/saferules/, https://digitalsynopsis.com/design/useful-ui-ux-design-tips/, https://vercel.com/design/guidelines)
+- **[D29] Optical alignment.** Detect: play triangles, chevrons and round icons centred by bounding box and looking off. Fix: adjust by eye (±1px), fix offsets inside the SVG where possible. (Source: https://vercel.com/design/guidelines, https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://anthonyhobday.com/sideprojects/saferules/)
+- **[D30] Badge placement follows the icon.** Detect: notification dots always top-right regardless of icon shape. Fix: place each badge where the icon's silhouette leaves room. (Source: https://x.com/detaildotdesign)
+- **[D31] Status chips only for real state.** Detect: badges on every row with no changing state behind them; status by colour alone. Fix: chips only for real, changing state, one visual language, always with a text label. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://vercel.com/design/guidelines)
+
+## People and brands
+
+- **[D32] Avatars.** Detect: initials everywhere when photos exist; placeholder generators (pravatar, DiceBear); initials colours that change on reload. Fix: real photo first; fallback chain photo → initials on a background colour hashed from a stable ID (identical input, identical colour); segment initials with `Intl.Segmenter` for non-Latin names; one avatar shape across the product; size by context (small in tables, large where the person is the subject); in overlapping stacks, a ring in the page background colour keeps edges clean, with a "+N" overflow. (Source: https://shopify.dev/docs/api/app-home/polaris-web-components/media/avatar, https://dev.to/joshuaslate/deterministic-react-avatar-fallbacks-5ghb, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://digitalsynopsis.com/design/useful-ui-ux-design-tips/)
+- **[D33] Brand logos: colour or mono.** Detect: a customer wall mixing colour and grey logos; a "Sign in with Google" button with a grey G. Fix: customer and press walls in one uniform treatment (mono is the default so your brand stays loudest; full colour is reasonable when every logo is a household name); never mix. Functional logos that identify something to click (OAuth buttons, integration pickers) keep official colours: Google forbids recolouring or monochroming its G. (Source: https://genesysgrowth.com/blog/designing-customer-logo-walls, https://developers.google.com/identity/branding-guidelines)
+- **[D34] Logo sizing by area, not height.** Detect: all logos the same height (wide wordmarks dominate) or same width (square marks balloon). Fix: width = base × aspect-ratio^0.5 (0 = same width, 1 = same height; ~0.5 is the sweet spot); compensate for ink density (scale solid marks down slightly, thin ones up); crop padding baked into files; align by visual centre. At a 48px base, a square mark is 48px, an 8:1 wordmark ~135×17px and a 15.6:1 wordmark ~190×12px, so on marketing pages a base of 56–64px keeps long wordmarks readable (derived from Sanity's worked examples). (Source: https://www.sanity.io/blog/the-logo-soup-problem, https://danpaquette.net/read/automatically-resizing-a-list-of-icons-or-logos-so-theyre-visually-proportional/)
+- **[D35] Logo contrast floor.** Detect: mono logos rendered with opacity below ~0.45 black on white (or equivalent on dark). WCAG exempts logotypes from text contrast, but not when a logo is a link, and the exemption does not make a faint logo recognisable. Fix: treat 3:1 against the background as the floor (black at ≥ ~42% opacity on white; ~54% for 4.5:1, by WCAG luminance arithmetic); 6–12 logos per row rather than a dense grid; check in both themes. (Source: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html, https://genesysgrowth.com/blog/designing-customer-logo-walls)
+
+## Feedback surfaces
+
+- **[D36] Toasts.** Detect: toasts that vanish while hovered, stack as a tall column, or exit in a different direction than they entered. Fix: ~4s default; pause on hover and when the tab is hidden; swipe to dismiss in the direction they came from; stack with each toast behind scaled down ~0.05 and offset, expand on hover; announce via polite `aria-live`; serious errors belong inline, not only in a toast. (Source: https://emilkowal.ski/ui/building-a-toast-component, https://vercel.com/design/guidelines, https://www.nngroup.com/articles/error-message-guidelines/)
+- **[D37] Tooltips.** Detect: tooltips carrying information needed to finish a task; every tooltip in a toolbar re-delaying; hover-only tooltips. Fix: inline help first; delay the first tooltip in a group, show its neighbours instantly without animation; open on keyboard focus too; never hide essential instructions in one. (Source: https://emilkowal.ski/ui/7-practical-animation-tips, https://vercel.com/design/guidelines, https://www.nngroup.com/articles/tooltip-guidelines/)
+- **[D38] Keyboard shortcuts.** Detect: shortcuts that exist but are never shown, or shown as "Ctrl" on a Mac. Fix: show the shortcut beside its action in menus and tooltips with platform symbols; support non-QWERTY layouts; holding a modifier can reveal number shortcuts in lists. (Source: https://vercel.com/design/guidelines, https://x.com/detaildotdesign)
+- **[D39] Loading indicators matched to wait.** Detect: spinners on sub-second loads; skeletons that do not match the final layout; skeletons for uploads. Fix: under 1s show nothing; full-page loads under 10s get a skeleton matching the final layout exactly; single modules get a spinner; over 10s a progress bar with an estimate. **Disagreement:** Viget's 136-person test found skeletons felt slowest (2.82s perceived vs 2.41s spinner); treat skeletons as a layout-stability tool for familiar screens, not a perceived-speed trick. (Source: https://www.nngroup.com/articles/skeleton-screens/, https://vercel.com/design/guidelines, https://www.viget.com/articles/a-bone-to-pick-with-skeleton-screens/)
+- **[D40] Optimistic UI with undo.** Detect: every action waits on a spinner; destructive actions with a modal confirm. Fix: update immediately, reconcile with the server, roll back with an error or offer undo; confirm or undo for destructive actions. (Source: https://vercel.com/design/guidelines)
+- **[D41] Ellipsis on follow-ups.** Detect: "Rename" opening a dialog with no hint. Fix: menu items that open a follow-up and in-progress labels end with "…" ("Rename…", "Saving…"). (Source: https://vercel.com/design/guidelines)
+
+## Browser chrome and page finish
+
+- **[D42] Favicon and browser colour.** Detect: favicon that disappears or gets a white box on dark Safari tabs; mismatched browser UI colour. Fix: brighten the mark and reduce its padding (Paco's fix moved Linear's favicon from #6E79D6 to #8299FF); set `<meta name="theme-color">` to the page background and `color-scheme: dark` on dark themes. (Source: https://paco.me/writing/safari-favicon-showing-white-background, https://vercel.com/design/guidelines)
+- **[D43] OG image.** Detect: missing `og:image`, or a generic one for every page. Fix: at least 1200×630 (1.91:1), not below 600×315, under 8MB; one short message in a heavy face that survives thumbnail size; page-specific `<title>` that reflects context. (Source: https://developers.facebook.com/docs/sharing/webmasters/images/, https://vercel.com/design/guidelines)
+- **[D44] Scrollbars.** Detect: double scrollbars, scrollbars on elements that never overflow, layout jumping when a scrollbar appears. Fix: render only useful scrollbars (preview with macOS "always show"); `scrollbar-gutter: stable` where content length changes; `overscroll-behavior: contain` in modals and drawers. (Source: https://vercel.com/design/guidelines, https://developer.mozilla.org/en-US/docs/Web/CSS/scrollbar-gutter)
+- **[D45] Theme switching.** Detect: elements cross-fading at different speeds when toggling dark mode. Fix: disable all transitions for the frame of the switch (inject `transition: none !important`, flip the theme, force a style read, remove). (Source: https://paco.me/writing/disable-theme-transitions)
+- **[D46] Selection colour.** Detect: default blue selection clashing with a strongly branded page. Fix (optional): a `::selection` colour from the brand with enough contrast against the selected text. **Disagreement:** some argue overriding selection is cosmetic and risky for accessibility; only do it with a contrast check. (Source: https://classic.yarnpkg.com/en/package/custom-selection)
+- **[D47] Links, URLs and anchors.** Detect: navigation built with `<button>` or `<div onClick>`; tabs and filters lost on refresh; anchored headings hidden under sticky headers. Fix: `<a>` for navigation so ⌘-click works; state in the URL; `scroll-margin-top` on anchored headings. (Source: https://vercel.com/design/guidelines)
+- **[D48] Drag details.** Detect: drags that start on the first pixel (accidental drags), text getting selected mid-drag. Fix: start a drag only after a few pixels of movement; disable text selection and mark the dragged element `inert` while dragging. (Source: https://x.com/raunofreiberg/status/1923056929389019314, https://vercel.com/design/guidelines)

package/kb/craft/landing-demos.md

@@ -0,0 +1,46 @@
+# Landing pages that show the product working
+
+How to use: for product and waitlist pages. Check the first viewport, then scroll once and note every place the product appears: is it a picture of the product, or the product doing something? Detection works from a screenshot sequence plus the DOM (`<img>` vs live HTML, `<video>`, `<canvas>`, animation code).
+Evidence quality varies: practitioner write-ups (Interfere, Vercel, Stripe) describe what they built; conversion numbers come mostly from vendors and are marked as such.
+
+## Show it, don't frame it
+
+- **[L01] Build the product in code, not as screenshots.** Detect: hero and feature visuals are `<img>` screenshots, often inside device or browser frames. Teams known for craft build product visuals as live HTML/CSS/SVG instead: Interfere builds UI graphics in code rather than screenshots; Vercel builds marketing visuals as React components; Stripe animated its Connect onboarding demo entirely in code (~5KB); one survey of server HTML found no `<video>` on the Linear, Vercel, Raycast, Supabase, Cal.com, Stripe or Figma homepages. Code-built UI is crisp at any size, can respond, and can show behaviour. Fix: rebuild the key product moment in HTML from real data. (Source: https://interfere.com/blog/how-we-built-interferes-new-website, https://rauno.me/craft/vercel, https://stripe.com/blog/connect-front-end-experience, https://github.com/AbdelrhmanAh7/FlowLine_Web/issues/96)
+- **[L02] Show only what the moment needs.** Detect: a full-fidelity product clone with every sidebar item and toolbar. Interfere reduces unimportant chrome to skeleton placeholders so each graphic communicates one thing; the raw product adds noise. Fix: keep the real content of the moment, abstract the rest. (Source: https://interfere.com/blog/how-we-built-interferes-new-website)
+- **[L03] No fake browser chrome.** Detect: traffic-light dots, fake URL bars, or a generic panel framed as a window. Fix: a plain rounded window or the product's own chrome (Linear's homepage composition uses no browser chrome). (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://github.com/AbdelrhmanAh7/FlowLine_Web/issues/96)
+- **[L04] Product preview at real size.** Detect: a hero visual shrunk into an unreadable thumbnail or cropped so the key action is cut. Cursor's hero shows a realistic editor window at full size so visitors see the product before clicking; its download CTA adapts its label to the visitor's OS. (Source: https://blog.logrocket.com/ux-design/hero-section-examples-best-practices/)
+- **[L05] Cover-the-headline test.** Detect: hide the H1; if the first viewport no longer says what the product does, the visual is decoration. Harry Dry's order puts a visual third, right after title and subtitle, so the visitor can picture the outcome. (Source: https://x.com/thejustinwelsh/status/1508420178111041550, https://blog.logrocket.com/ux-design/hero-section-examples-best-practices/)
+
+## Demo patterns
+
+- **[L06] Hero timeline that mirrors real product behaviour.** Detect: a static hero for a product whose value is something happening over time. Interfere's hero plays a timeline sequence that mirrors how new events appear in the product, with blur 10px→0, opacity 0→1 and translateY 20%→0 staggered by group, on first visit only. (Source: https://interfere.com/blog/how-we-built-interferes-new-website)
+- **[L07] One feature, one animated explanation.** Detect: a feature section with a heading and paragraph but no demonstration. Emil Kowalski points to Linear's animated explanation of a feature on its marketing page as motion that earns its place. Fix: each feature section gets a small product fragment that performs that feature once. (Source: https://emilkowal.ski/ui/you-dont-need-animations)
+- **[L08] A live, clickable component.** Detect: a component library or UI product shown only as code or images. Sonner's own page lets visitors fire real toasts by type (success, error, promise, action…), position and expand mode: the docs are the demo. Fix: when the product is UI, let visitors trigger it. (Source: https://sonner.emilkowal.ski)
+- **[L09] Reactive demo: change an input, see the output.** Detect: a claim about transformation shown as before/after images. Explorable explanations let the reader change an assumption and see results update; Josh Comeau embeds draggable controls (e.g. container width) to teach by manipulation. Fix: one input the visitor controls and the product's real response beside it. (Source: https://worrydream.com/ExplorableExplanations/, https://www.joshwcomeau.com/blog/how-i-built-my-blog-v2/)
+- **[L10] Diagram for the invisible part.** Detect: infrastructure or engineering value described in prose. Interfere's engineering hero is an animated SVG diagram; Vercel's Ship site sends icons along orbit rings with CSS `offset-path`; Stripe used rotating 3D cubes as building blocks. Fix: animate the flow, not a metaphor unrelated to it. (Source: https://interfere.com/blog/how-we-built-interferes-new-website, https://rauno.me/craft/vercel, https://stripe.com/blog/connect-front-end-experience)
+- **[L11] Video when capture beats rebuilding.** Detect: GIFs, or a 60s autoplay video as the hero. Measured practice: hero loops around 6s (Arc 6.7s; Screen Studio 5.5–6.3s), tile loops 10–20s at 0.3–0.4MB (Resend), long walkthroughs behind a click; posters, `preload="none"`/`metadata`, muted and `playsinline`; Linear uses video in its changelog rather than its homepage. (Source: https://github.com/AbdelrhmanAh7/FlowLine_Web/issues/96, https://vercel.com/design/guidelines)
+- **[L12] Let people control the pace.** Detect: demo videos with no controls. Interfere offers playback speeds from 0.25x to 2x on its demo videos; any loop longer than 5s next to content needs pause/stop. (Source: https://interfere.com/blog/how-we-built-interferes-new-website, https://vercel.com/design/guidelines)
+- **[L13] Ambient interaction is not a demo.** Detect: a hero whose only interactivity is light following the cursor. Raycast's hero light reacts to the pointer; it sets mood but does not show the product. Fix: atmosphere is fine as a layer, but some element on the first screen must show the product doing its job. (Source: https://hero.gallery/hero-gallery/raycast)
+
+## Structure and rhythm
+
+- **[L14] "How it works" in three steps with product, not a text row.** Detect: four or more columns of heading + paragraph; numbered steps with no visual. Readers scan headings and the left side; prose rows read as documentation. Fix: at most three steps, each with a fragment of the product at that step; or show the finished result first and the steps that made it. (Source: https://www.nngroup.com/articles/horizontal-attention-leans-left/, https://www.nngroup.com/articles/layer-cake-pattern-scanning/, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it)
+- **[L15] Scroll-driven product story without hijacking.** Detect: sticky sections that take over the wheel; horizontal scroll driven by vertical. Fix: a sticky claim with the product proof scrolling beside it, or CSS view-timeline reveals; keep native scroll speed; keep important text out of scroll-driven sections. (Source: https://developer.chrome.com/docs/css-ui/scroll-driven-animations, https://www.nngroup.com/articles/scrolljacking-101/)
+- **[L16] Vary how sections open.** Detect: the same eyebrow/kicker, mono number or small-caps label above every H2. Fix: one recurring system element at most; each section starts with what it is about (a product fragment, a plain heading, a number that matters). (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://rauno.me/craft/novelty, https://x.com/steveschoger/status/956229542288543744)
+- **[L17] Alternate loud and quiet motion.** Detect: every section animates for attention, or none does. Vercel's Ship site paired each high-novelty animation with low-novelty micro-motion and never put two loud ones back to back; Interfere kept loops below the hero deliberately restrained. (Source: https://rauno.me/craft/vercel, https://interfere.com/blog/how-we-built-interferes-new-website)
+- **[L18] Fast first paint, enhancement after.** Detect: hero waits on JS or WebGL. Vercel's hero renders five of six layers without client JS; the shader is code-split, fades in after load and is skipped on low-powered devices. Never start the first viewport at `opacity: 0`. (Source: https://rauno.me/craft/vercel, https://dev.to/gillygangopolus/the-scroll-animation-that-was-hiding-our-lcp-element-2edp)
+- **[L19] Cheap to render.** Detect: heavy video or thousands of DOM nodes for a decorative pattern. Stripe's CSS laptop is under 1KB and its animated demo ~5KB; Interfere moved a dot pattern from SVG to canvas; animations start via IntersectionObserver once fully visible. (Source: https://stripe.com/blog/connect-front-end-experience, https://interfere.com/blog/how-we-built-interferes-new-website)
+- **[L20] Reduced motion keeps the story.** Detect: demos that vanish or keep looping under reduced motion. Fix: pause ambient loops gracefully, keep user-triggered interactions, show posters with a play button instead of autoplay video. (Source: https://rauno.me/craft/vercel, https://github.com/AbdelrhmanAh7/FlowLine_Web/issues/96)
+- **[L21] Accessible illustrations.** Detect: decorative HTML demos read aloud node by node. Fix: `aria-hidden` on the inner tree and one descriptive label on the group; copy buttons labelled, with a polite "copied" announcement. (Source: https://rauno.me/craft/nextjs, https://rauno.me/craft/vercel)
+
+## Proof
+
+- **[L22] Logo strip that can be read.** Detect: logos below ~0.45 opacity, wordmarks under ~16px tall, colour mixed with mono, 20+ logos in a grid. Fix: 6–12 real customer logos, one treatment (mono by default; colour if every mark is a household name), area-normalised sizing (see D34), at least 3:1 against the background, placed right under the hero or beside the CTA. (Source: https://genesysgrowth.com/blog/designing-customer-logo-walls, https://www.sanity.io/blog/the-logo-soup-problem, https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
+- **[L23] Logos only work if this buyer recognises them.** Detect: a logo wall of companies the target visitor would not know or care about, and no other proof. Logos act as a fast credibility check right under the hero, but only when the target buyer recognises and respects the companies; one detailed case study can outweigh many short quotes, and proof works best at moments of doubt such as next to the CTA. Fix: pick logos for this audience, link them to case studies, put one specific result beside the CTA. **Disagreement:** SaaS Hero cites an unverified claim that most B2B brands that tested removing their logo bar saw conversions improve; test rather than assume a logo strip helps. (Source: https://www.saashero.net/strategy/landing-page-social-proof-examples/, https://genesysgrowth.com/blog/designing-customer-logo-walls)
+- **[L24] No customers yet: show the work, honestly.** Detect: placeholder logos or invented testimonials on a pre-launch page. Fix: real product output, shipped changes with dates, the founder's own words; fake reviews and testimonials, including AI-generated ones, are illegal in the US since 2024. (Source: https://www.ftc.gov/news-events/news/press-releases/2024/08/federal-trade-commission-announces-final-rule-banning-fake-reviews-testimonials)
+
+## Interactive demos and waitlists: what the numbers say
+
+- **[L25] Interactive demos get clicked when they are short and have a way out.** Navattic's vendor data: top 1% of interactive demos reached ~54% click-through to a CTA (2025, 28k demos); in 2023 most CTA clicks landed around steps 7 and 15, and offering two options at a CTA step (continue the demo, or convert) worked well. Treat as vendor data. (Source: https://navattic.com/report/state-of-the-interactive-product-demo-2025, https://www.navattic.com/report/state-of-the-interactive-product-demo-2023)
+- **[L26] Waitlist page: one action, then a reason to share.** Detect: navigation, multiple CTAs and long forms on a waitlist page. Common advice: an outcome headline, one email field above the fold, real signup numbers only, a referral mechanic on the success page. Robinhood's pre-launch page showed each person's place in line and let referrals move them up, reportedly reaching about a million signups (secondary sources). (Source: https://getlaunchlist.com/blog/waitlist-landing-page-examples-that-convert, https://thegrowthplaybook.substack.com/p/how-robinhood-turned-a-landing-page)
+- **[L27] For designers, the page is the portfolio.** Detect: a design tool's own page with default type, faint logos or broken states. A design-literate audience judges the craft directly: focus rings that follow radius, fluid `clamp()` headings, restrained motion, no gimmicks (the Next.js site's approach). Fix: the waitlist page should demonstrate the product's standard in its own details, and ideally run the product on itself (e.g. critique a sample screen live). (Source: https://rauno.me/craft/nextjs)

package/kb/craft/mistakes.md

@@ -0,0 +1,73 @@
+# Mistakes that make UI look amateur or AI-generated
+
+How to use: run each entry against a screenshot (squint, zoom to 200%) and the DOM (computed styles, class names). Flag an entry only when the detection condition is actually met, and quote the element. Entries marked **Disagreement** have credible designers on both sides: report them as judgement calls, not defects.
+Many tells are fine alone; the "default" look comes from several of them together. Three or more first-order tells (M01–M12) on one page means the page was averaged, not designed.
+
+## First-order AI tells (the 2024–25 default look)
+
+- **[M01] Unchosen purple/indigo gradient.** Violet-to-indigo or blue-to-purple gradients on the hero background, primary button or accents. In the DOM, look for `indigo-500`/`violet-*` classes or tokens named `gradient-start`/`gradient-end`. This is the single most recognised AI tell: Tailwind's creator joked in 2025 that his `bg-indigo-500` demo buttons from five years earlier are why every generated UI is indigo. Fix: derive the palette from something true about the product and name colours by job (primary action, warning, success), not by position in a gradient. (Source: https://x.com/adamwathan/status/1953510802159219096, https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/, https://www.925studios.co/blog/ai-slop-design-tells)
+- **[M02] Gradient-filled headline text.** `background-clip: text` with a gradient on an H1 or a single word. Contrast changes across the word, so some letters fail even when others pass, and it reads as decoration standing in for hierarchy. Fix: solid text; let size, weight and line breaks carry the headline. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it)
+- **[M03] Inter (or system UI) everywhere, by default.** Computed `font-family` is Inter/Roboto/Arial/system on both H1 and body, with no display face and no deliberate weight contrast. Type is the fastest signal of authorship; the issue is the missing decision, not Inter itself. Fix: choose a display face for the brand and a quiet text face; changing the font is about an hour of work and the highest-leverage anti-slop move. **Disagreement:** Linear deliberately uses Inter Display for headings and Inter for text; Inter chosen and tuned is fine. (Source: https://www.925studios.co/blog/ai-slop-design-tells, https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/, https://linear.app/now/how-we-redesigned-the-linear-ui)
+- **[M04] Three (or four) equal icon-topped feature cards.** A row of identically sized rounded cards, soft shadow, a thin line icon in a tinted rounded square on each, a two-word title and a sentence. Equal tiles mean nothing is most important, and the icon-in-chip is the stock Lucide look. Fix: one dominant tile with the rest supporting, or content that refuses a 3-column grid; drop the icon chip or draw marks for this product. (Source: https://www.925studios.co/blog/ai-slop-design-tells, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M05] Emoji used as icons.** Emoji code points in nav items, feature headings, buttons or bullets (rocket, lightning, sparkles). Emoji render differently per OS, cannot take the text colour, and look like placeholders. Fix: one icon set with one stroke weight, or plain text labels. (Source: https://www.ohhwells.com/blog/vibe-coded-website, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it)
+- **[M06] Centred everything.** `text-align: center` on paragraphs longer than two lines and on every section heading. Eye-tracking puts about 80% of fixations on the left half of the screen, and centred multi-line text has a ragged left edge the eye must hunt for. Fix: left-align body copy and most section starts; centre only short lockups (a one-line headline + CTA). (Source: https://www.nngroup.com/articles/horizontal-attention-leans-left/, https://practicaltypography.com/summary-of-key-rules.html)
+- **[M07] Pill badge above the H1.** A small capsule ("New", sparkle emoji, "Introducing…") directly above a centred headline. It is now template furniture. Fix: remove it unless it announces dated, real news, and then link it to that news. (Source: https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M08] Reflexive glassmorphism.** `backdrop-filter: blur()` on nav, cards and pills over a flat or gradient background where nothing is actually behind them. Translucent panels give uneven contrast across busy backgrounds and look like a trend applied without a reason. Fix: use blur only where layering is real (an overlay or nav over scrolling content); use more blur over busy backgrounds; check text contrast against every background the panel can sit on. (Source: https://www.nngroup.com/articles/glassmorphism/, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M09] Generic copy.** Headlines that could belong to any company ("Build faster. Ship smarter.", "The all-in-one platform for…"), tricolon slogans, superlatives (seamless, powerful, cutting-edge) and CTAs like "Get started", "Learn more", "Continue". Fix: say what the product does and for whom in words a founder would say aloud; name the action and its object on buttons ("Save API key", not "Continue"). (Source: https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://vercel.com/design/guidelines)
+- **[M10] Invented proof.** Testimonials with stock or generated faces (pravatar, DiceBear), logo strips of companies that are not customers, round-number stats with no source. Beyond trust, the US FTC rule (in force since Oct 2024) bans fake and AI-generated reviews and testimonials, with penalties up to about $52k per violation. Fix: real proof only; if there is none yet, show honest product facts or shipped work instead. (Source: https://www.ftc.gov/news-events/news/press-releases/2024/08/federal-trade-commission-announces-final-rule-banning-fake-reviews-testimonials, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M11] Stat banner and count-up numbers.** A row of 3–4 huge numbers ("10x", "99.9%", "50k+"), often ticking up on scroll. Unsourced numbers read as filler, and the count-up delays the one thing the visitor wanted to read. Fix: cut unless each number is real, specific and attributed; show the final value immediately. (Source: https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M12] Untouched library defaults and stock effects.** shadcn zinc/slate base, default radius on every component, unstyled Card/Badge; or Aceternity/Magic UI effects as shipped (Spotlight, Background Beams, Border Beam, Meteors, Shimmer Button, Marquee). Fix: theme base colour, radius and type scale; build an effect tied to the product or cut it. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+
+## Second-order tells (the "tasteful" defaults that replaced the first set)
+
+- **[M13] The new default fonts.** Space Grotesk, Instrument Serif, Fraunces or Geist pairings, especially one italic serif word inside an otherwise sans headline. Anthropic's own write-up notes models converge on Space Grotesk even after being told to avoid Inter. Fix: pick a face for this brand's reasons and keep the type system consistent; no single accented word. (Source: https://claude.com/blog/improving-frontend-design-through-skills, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it)
+- **[M14] Accented headline word.** One word set apart by colour, italic, highlight or gradient. It is a template move that tells the reader where to look instead of writing a headline that does it. Fix: let size, weight and the line break carry emphasis; if something must be emphasised, emphasise the meaningful noun through the type system everywhere. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M15] Cream ground + terracotta accent, or near-black + one neon.** Parchment background with clay/rust accent and a high-contrast serif; or a permanent dark page with a single acid-green/lime/vermilion signal and mono labels. Both became the "I avoided purple" default. Fix: derive colour from the subject; go dark only when the product calls for it; give the accent one job. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it)
+- **[M16] Template chrome: the same kicker on every section.** Detect: three or more sections opening with the same small device (uppercase tracked label, mono "01 —", middle-dot meta string, "WORD — fragment") above the H2. Steve Schoger popularised the eyebrow as a way to make a plain heading pattern more interesting, which only works while it is rare; repeated on every section it becomes wallpaper, the same way a word repeated loses meaning. Fix: keep a label only where it adds information; vary how sections open (a number, a product fragment, a plain heading); set labels in the body face, sentence case. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://x.com/steveschoger/status/956229542288543744, https://rauno.me/craft/novelty)
+- **[M17] Decorative 01/02/03 numbering.** Two-digit numbers on cards or features that have no order. Numbers promise a sequence; without one they are ornament. Fix: number only real steps, rankings or an index the page actually navigates by. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it)
+- **[M18] Mono and all-caps where nothing is data.** Monospace on labels, nav and section titles; uppercase headings. Mono should signal machine values (IDs, code, timestamps); caps lower legibility for anything longer than a short label. Fix: sentence case in the body face; reserve mono for real data. **Disagreement:** tracked caps for short labels are a classic, legitimate device (add 5–12% tracking); the problem is using it everywhere. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://practicaltypography.com/summary-of-key-rules.html, https://anthonyhobday.com/sideprojects/visualtechniques/techniques/text/letter-spacing-on-all-capitals.html)
+- **[M19] Fake window chrome and screenshots in frames.** Traffic-light dots or a fake browser bar around a panel; product shown as flat screenshots inside device or browser frames instead of working. The frame says "this is a picture of software" and the screenshot cannot show behaviour. Fix: build the product UI in HTML from real data, strip unimportant chrome to skeletons, and make one thing in it happen (see landing-demos.md). (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://interfere.com/blog/how-we-built-interferes-new-website, https://github.com/AbdelrhmanAh7/FlowLine_Web/issues/96)
+- **[M20] Copied "Linear glow".** Dark hero, blurred animated gradient glow behind a product shot, faint white-10% borders on zinc-950 cards. Fix: borrow the principle (atmosphere, depth) and build your own; separate dark surfaces by more than a faint border. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+
+## Layout and structure
+
+- **[M21] Uniform everything.** Same radius, padding and card height on every surface (e.g. 16px radius and 24px padding everywhere), so nothing leads. Fix: vary size, closeness and weight on purpose so the primary element is bigger or heavier and the rest recedes; vary radius and elevation by role. (Source: https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M22] Many-column "how it works" text row.** Detect: four or more columns in one row, each a heading plus 25+ words of prose, with no product visual. It reads as documentation: attention falls off sharply to the right, and readers scan headings rather than paragraphs. Fix: at most three steps, each paired with a small working product fragment; or show the end result first and the two or three moves that produced it; headings that make sense on their own. (Source: https://www.nngroup.com/articles/horizontal-attention-leans-left/, https://www.nngroup.com/articles/layer-cake-pattern-scanning/, https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it)
+- **[M23] Cards inside cards.** Boxes nested two or three deep, each with border and radius. Fix: one level of containment; use space, alignment and type for the rest. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M24] Coloured stripe on card edges.** A 2–4px coloured left or top border on every card. Fix: express status or category with weight, position, background or a real label. (Source: https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[M25] Off-scale spacing and inverted padding.** Gaps like 10px, 18px, 22px next to each other; a container whose inner padding is larger than the space around it. Fix: a mathematical scale (multiples of 4/8); outer padding equal to or larger than inner padding; measure gaps between the high-contrast edges you actually see, not bounding boxes. (Source: https://anthonyhobday.com/sideprojects/saferules/)
+- **[M26] Elements that align with nothing.** Header, toolbar and content start at different x positions; icons centred geometrically but visibly off. Fix: every element aligns to a grid, baseline, edge or optical centre; nudge by ±1px where perception beats geometry. (Source: https://vercel.com/design/guidelines, https://anthonyhobday.com/sideprojects/saferules/)
+- **[M27] Everything visible at once.** Every table, panel and control on screen regardless of the task. Fix: progressive disclosure: show each control when the person needs it. (Source: https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/)
+- **[M28] Two hard edges touching.** A section background change directly against a card edge or a divider line. Fix: never stack two hard divides; drop one. (Source: https://anthonyhobday.com/sideprojects/saferules/)
+
+## Type, colour and contrast
+
+- **[M29] Flat or mis-set hierarchy.** Headings differ from body only by size; large headings keep body leading (1.5) and default tracking. Fix: use size, weight and colour as separate levers; tighten leading and tracking as size grows, loosen for small text; de-emphasise secondary text rather than shouting the primary. (Source: https://anthonyhobday.com/sideprojects/saferules/, https://digitalsynopsis.com/design/useful-ui-ux-design-tips/, https://www.refactoringui.com/previews/labels-are-a-last-resort)
+- **[M30] Line length out of range.** Body text lines over ~90 or under ~45 characters. Fix: aim for 60–75 characters (`max-width: 65ch` is a good default). (Source: https://practicaltypography.com/summary-of-key-rules.html, https://anthonyhobday.com/sideprojects/saferules/, https://emilkowal.ski/ui/agents-with-taste)
+- **[M31] Orphans and ragged headings.** A single word alone on a heading's last line; very uneven multi-line headings. Fix: `text-wrap: balance` on headings, `text-wrap: pretty` on paragraphs. (Source: https://vercel.com/design/guidelines, https://webkit.org/blog/16547/better-typography-with-text-wrap-pretty/)
+- **[M32] Typewriter punctuation.** Straight quotes, three periods instead of an ellipsis, double hyphens for dashes. Fix: curly quotes, the `…` character, proper dashes. (Source: https://vercel.com/design/guidelines, https://practicaltypography.com/summary-of-key-rules.html)
+- **[M33] Low-contrast body text, especially on dark.** Mid-grey body copy on near-black that fails 4.5:1. Fix: check every text colour; raise body text contrast; muted text still needs to pass. **Disagreement:** Vercel prefers APCA over WCAG 2 ratios because WCAG 2 misjudges dark mode, but WCAG 2.2 AA is still the legal standard; check both. (Source: https://www.developersdigest.tech/blog/ai-design-slop-and-how-to-spot-it, https://vercel.com/design/guidelines, https://github.com/Myndex/apca-introduction)
+- **[M34] Pure grey on colour, pure black on white.** Neutral grey text on a tinted background looks dirty; #000 on #fff and #fff on #000 look harsh. Fix: tint greys toward the background hue; use near-black and near-white; saturate neutrals with under 5% of the interface hue, all warm or all cool. (Source: https://digitalsynopsis.com/design/useful-ui-ux-design-tips/, https://anthonyhobday.com/sideprojects/saferules/, https://vercel.com/design/guidelines)
+- **[M35] Non-concentric nested radii.** A rounded child inside a rounded parent where the child's radius equals or exceeds the parent's, so the gap between curves pinches at the corners. Fix: inner radius = outer radius − gap (padding + border), e.g. 24px outer with 8px padding gives 16px inner; skip the rule for 0 or fully round shapes. (Source: https://vercel.com/design/guidelines, https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://anthonyhobday.com/sideprojects/saferules/)
+- **[M36] Large radius and soft shadow on everything.** `rounded-2xl shadow-lg` on every surface, or a grey border plus a diffuse shadow on each card. Fix: reserve strong shadows for floating elements; let some surfaces be flat; one depth technique used consistently. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://anthonyhobday.com/sideprojects/saferules/)
+
+## States, feedback and forms
+
+- **[M37] Only the happy path is designed.** No hover/focus/active/disabled styles, no empty, loading or error states. Fix: design every state; empty and error states each take under an hour. (Source: https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/, https://vercel.com/design/guidelines)
+- **[M38] Blank or lying empty states.** An empty container with no message, or "No records" shown while data is still loading. Fix: status message only after loading finishes, one line on what will appear here, and a direct action to fill it. (Source: https://www.nngroup.com/articles/empty-state-interface-design/)
+- **[M39] Generic, distant or colour-only errors.** "An error occurred" in a toast at the top, red border with no text, input cleared after failure. Fix: message next to the field in plain words with the fix, icon plus text (not colour alone), input preserved, focus moved to the first error on submit. (Source: https://www.nngroup.com/articles/error-message-guidelines/, https://vercel.com/design/guidelines)
+- **[M40] Focus removed or left to the browser.** `outline: none` with nothing in its place, or reliance on browser defaults, which measured as low as 1.4:1 against some backgrounds. Fix: see D05. (Source: https://www.sarasoueidan.com/blog/focus-indicators/)
+- **[M41] Tiny hit targets.** Icon buttons with a 16px clickable area; checkbox and label that do not share a target. Fix: at least 24px (44px on touch), expanded with padding or a pseudo-element rather than a bigger icon. (Source: https://vercel.com/design/guidelines, https://emilkowal.ski/ui/agents-with-taste)
+- **[M42] Hostile forms.** Submit disabled until valid, typing blocked at a character limit, paste blocked in password/OTP fields. Fix: let people submit to see validation, block submit (not typing) past a limit, never block paste. (Source: https://vercel.com/design/guidelines, https://x.com/detaildotdesign)
+
+## Motion and loading
+
+- **[M43] No motion at all on a marketing page.** Nothing moves: no press feedback, no product behaviour, no explanation of how a feature works. A static page cannot show cause and effect, and pages with nothing moving read as unfinished. Fix: put motion where it explains (a feature demonstrated in a short loop, a state change in the hero) and on primary controls; not everywhere. (Source: https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/, https://emilkowal.ski/ui/you-dont-need-animations)
+- **[M44] The same fade-up on every section.** Every block rises 20px and fades in on scroll with the same timing. Identical motion is a tell and signals no motion language. Fix: one or two deliberate moments; vary by intent; let most content simply be there. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/)
+- **[M45] Above-the-fold content hidden until JavaScript runs.** Hero heading starts at `opacity: 0` waiting for an IntersectionObserver. One team measured a 6–7s mobile LCP with a 72ms server response because of this. Fix: never animate the first viewport in from invisible; reveal only below the fold. (Source: https://dev.to/gillygangopolus/the-scroll-animation-that-was-hiding-our-lcp-element-2edp)
+
+## Brand and finish
+
+- **[M46] A logo cloud nobody can read.** Detect: customer logos at low opacity (black at 40% on white is about 2.8:1; 30% is about 2.1:1, by WCAG luminance arithmetic), wordmarks under ~16px tall, or colour and grey logos mixed in one row. The strip exists to be recognised in a glance; faint, tiny marks fail that job. Fix: see D28–D30 for when to use colour vs mono, area-normalised sizing and a 3:1 floor. (Source: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html, https://genesysgrowth.com/blog/designing-customer-logo-walls, https://www.sanity.io/blog/the-logo-soup-problem)
+- **[M47] Stock or generic imagery.** Team-around-a-laptop photos, glossy 3D blobs, faceless flat figures with long limbs. Fix: real product UI, real photos of the work, or illustration with a point of view. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://www.ohhwells.com/blog/vibe-coded-website)
+- **[M48] Missing finish-line details.** Default favicon, default `<title>`, no page-specific meta or OG image, missing alt text. Fix: favicon that survives dark tabs, accurate titles per page, a 1200×630 OG image (see D41–D42). (Source: https://www.ohhwells.com/blog/vibe-coded-website, https://vercel.com/design/guidelines)

package/kb/craft/motion.md

@@ -0,0 +1,53 @@
+# Motion
+
+How to use: for each animated element, ask the entries in order: should it move at all (A01–A04), how long and on what curve (A05–A12), how it enters and leaves (A13–A20), and what happens with reduced motion (A29–A32). In the DOM, check `transition`, `animation`, `@keyframes`, Motion/Framer props and `prefers-reduced-motion` blocks; on a page, record the first 2 seconds and scroll once.
+Product UI and marketing pages differ: tools favour fast or absent motion for frequent actions; marketing pages may run longer when the motion explains something.
+
+## Whether to animate
+
+- **[A01] Motion needs a job.** Detect: animation that neither shows cause and effect, keeps place, gives feedback, nor adds a deliberate moment of delight. Fix: cut it. Motion should clarify a change or confirm an action. (Source: https://vercel.com/design/guidelines, https://emilkowal.ski/ui/you-dont-need-animations)
+- **[A02] Frequency decides.** Detect: open/close animation on command menus, context menus, keyboard-driven highlights, hover effects on things used many times a day. A 300ms menu opened 200 times a day costs about six hours a year of waiting. Fix: no animation for high-frequency and keyboard-initiated actions (Raycast opens instantly; macOS context menus appear without animation and only fade out). Reserve motion for rare moments. (Source: https://rauno.me/craft/interaction-design, https://emilkowal.ski/ui/you-dont-need-animations, https://jakub.kr/writing/less-is-more)
+- **[A03] Delight scales inversely with frequency.** Detect: big celebratory motion on a daily action, or none on a once-ever milestone. Fix: subtle touches on frequent features, bigger moments on rare ones (Family: confetti after a wallet backup; commas shifting as you type an amount). (Source: https://benji.org/family-values, https://rauno.me/craft/novelty)
+- **[A04] A marketing page with zero motion.** Detect: a product page where nothing moves, including no demonstration of a feature. Static pages cannot show how something works; Emil cites Linear's animated explanation of a feature as motion that earns its place. Fix: animate the explanation (a feature working in a short loop, a state change in the product hero) and primary controls; keep the rest still. (Source: https://emilkowal.ski/ui/you-dont-need-animations, https://www.mania.design/blog/spot-the-slop-a-ui-designers-guide-to-fixing-ai-defaults/)
+
+## Duration and easing
+
+- **[A05] Durations by size.** Detect: UI transitions at 400–600ms. Fix: micro-interactions 100–150ms; tooltips, dropdowns 150–250ms; modals and drawers 200–300ms; stay under 300ms in product UI; up to ~400ms only for large movements across big screens; 500ms+ feels like a drag. Bigger elements and longer distances get longer durations. (Source: https://emilkowal.ski/ui/agents-with-taste, https://www.nngroup.com/articles/animation-duration/)
+- **[A06] Exits faster than entrances.** Detect: identical enter and exit durations on dialogs and popovers. Fix: exits about 20% faster (e.g. 300ms in, 200–250ms out). (Source: https://emilkowal.ski/ui/agents-with-taste, https://www.nngroup.com/articles/animation-duration/)
+- **[A07] Easing by situation.** Detect: `linear` on UI movement, `ease-in` on entrances. Fix: ease-out for entering/exiting; ease-in-out for things moving on screen; plain `ease` for hover colour; linear only for constant motion (spinners, marquees). **Disagreement:** NN/g suggests ease-in for exits; Emil uses ease-out for both, because ease-in starts slowly and feels laggy. Prefer ease-out in product UI. (Source: https://emilkowal.ski/ui/agents-with-taste, https://emilkowal.ski/ui/7-practical-animation-tips, https://www.nngroup.com/articles/animation-duration/)
+- **[A08] Custom curves over keywords.** Detect: only `ease`/`ease-in-out` keywords. Built-ins are weak; strong custom ease-outs feel snappier. Example from Jakub's enter keyframes: `cubic-bezier(0.25, 0.46, 0.45, 0.94)`. Stripe likewise tuned custom curves for its Connect page. (Source: https://emilkowal.ski/ui/7-practical-animation-tips, https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://stripe.com/blog/connect-front-end-experience)
+- **[A09] Springs for movement, not for colour.** Detect: springs on opacity/colour; bouncy springs on dialogs. Fix: springs for position, scale, drag and gesture release; start critically damped (no overshoot) and add bounce only when the gesture carried momentum in that direction (Apple used 100% damping for tapping open Now Playing, ~80% for swiping it away). In Motion, default `bounce` is 0.25: set it to 0 for product UI. **Disagreement:** Emil replaced a spring with an ease-out on Linear's dialog because the spring felt abrupt; and bounce/elastic easing on marketing pages is flagged as an AI tell. (Source: https://developer.apple.com/videos/play/wwdc2018/803/, https://www.joshwcomeau.com/animation/a-friendly-introduction-to-spring-physics/, https://motion.dev/docs/react-transitions, https://x.com/emilkowalski/status/2102798004281635184, https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[A10] Coupled elements share timing.** Detect: dialog and its overlay animating on different durations. Fix: match durations of elements that belong together. (Source: https://x.com/emilkowalski/status/2102798004281635184)
+- **[A11] One motion language.** Detect: many unrelated hovers and bounces with different curves and durations. Fix: define a small easing and duration scale and use only it. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[A12] Spinner speed.** Detect: a slow, lazy spinner. A faster spin makes the same wait feel shorter. (Source: https://emilkowal.ski/ui/you-dont-need-animations)
+
+## Entering, leaving, moving
+
+- **[A13] Never from scale(0).** Detect: popovers/modals scaling from 0. Fix: start from 0.9–0.97 with opacity 0, so the element keeps its shape. (Source: https://emilkowal.ski/ui/7-practical-animation-tips, https://emilkowal.ski/ui/agents-with-taste)
+- **[A14] Origin-aware.** Detect: dropdowns growing from their centre. Fix: `transform-origin` at the trigger (Radix and Base UI expose a CSS variable for it); motion starts where it physically comes from. (Source: https://emilkowal.ski/ui/7-practical-animation-tips, https://vercel.com/design/guidelines)
+- **[A15] Spatial consistency.** Detect: a panel that enters from the right and leaves downward; tabs that slide the same way regardless of direction. Fix: enter and exit along the same path; tab content slides toward the tapped tab; things open from their source (Dynamic Island apps slide out of the island). (Source: https://rauno.me/craft/interaction-design, https://developer.apple.com/videos/play/wwdc2018/803/, https://benji.org/family-values)
+- **[A16] Blur bridges a crossfade.** Detect: two states visibly swapping as separate objects. Fix: ~2px `filter: blur()` during the transition; for icon swaps animate opacity, scale and blur together. (Source: https://emilkowal.ski/ui/7-practical-animation-tips, https://jakub.kr/writing/details-that-make-interfaces-feel-better)
+- **[A17] Exits quieter than entrances.** Detect: elements leaving with as much travel as they arrived. Fix: let opacity and a small blur (~4px) do the exit with partial travel (e.g. `-70%` instead of the full width), so exits do not compete with what is entering. (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better)
+- **[A18] Staggering.** Detect: a whole block appearing at once, or every word appearing one by one. Fix: stagger groups (title, description, buttons ~100ms apart; words ~80ms) from `translateY(8px)`, `blur(8px)`, opacity 0. **Disagreement:** Interfere tried word-by-word and found it robotic, animating testimonial words in groups of three instead; Rauno notes staggering siblings adds depth without slowing the UI. (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://interfere.com/blog/how-we-built-interferes-new-website, https://rauno.me/craft/depth)
+- **[A19] Interruptible by default.** Detect: keyframe animations on hover/toggle that must finish before reversing. Fix: CSS transitions (or springs) for interactions so they retarget mid-flight; keyframes only for one-shot staged sequences; user input can cancel animation. (Source: https://jakub.kr/writing/details-that-make-interfaces-feel-better, https://vercel.com/design/guidelines, https://developer.apple.com/videos/play/wwdc2018/803/)
+- **[A20] Gestures.** Detect: swipes that only act on release; drags that stop dead at boundaries; flicks that snap to the nearest point. Fix: respond immediately and track 1:1; lightweight actions may commit mid-gesture, destructive ones only on release; rubber-band past edges; project momentum to pick the target. (Source: https://rauno.me/craft/interaction-design, https://developer.apple.com/videos/play/wwdc2018/803/)
+
+## Page-level motion
+
+- **[A21] Entrances never hide content.** Detect: above-the-fold elements at `opacity: 0` until JS runs; nothing visible on a no-JS or slow load. Fix: the first viewport renders fully without animation; animate from a visible state or reveal only below the fold. One team traced a 6–7s mobile LCP to this. (Source: https://dev.to/gillygangopolus/the-scroll-animation-that-was-hiding-our-lcp-element-2edp)
+- **[A22] Not the same reveal everywhere.** Detect: identical fade-up on every section (AOS, `whileInView` with one preset). Fix: one or two high-impact moments, the rest still. **Disagreement:** Anthropic's frontend guidance recommends one orchestrated page load with staggered reveals; critics flag uniform section reveals as a tell. Both agree on one considered moment over scattered effects. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md, https://claude.com/blog/improving-frontend-design-through-skills)
+- **[A23] Special moments play once.** Detect: hero intro replaying on every visit or every in-app navigation. Fix: play the intro on first visit only (Interfere's hero timeline); don't replay a staggered load on client navigation. (Source: https://interfere.com/blog/how-we-built-interferes-new-website, https://rauno.me/craft/novelty)
+- **[A24] Novelty rhythm.** Detect: two attention-grabbing animations in consecutive sections. Fix: alternate high-novelty and low-novelty motion; cut animations that feel pompous or break rhythm (Vercel's Ship site). (Source: https://rauno.me/craft/vercel)
+- **[A25] Scroll-linked motion done well.** Detect: scroll listeners on the main thread; parallax on everything. Fix: CSS scroll-driven animations (`animation-timeline: view()` with `animation-range: entry …`), which can run off the main thread; use for progress indicators, image reveals, sticky stacking. (Source: https://developer.chrome.com/docs/css-ui/scroll-driven-animations)
+- **[A26] No scrolljacking.** Detect: scroll speed or direction altered; horizontal sections driven by vertical scroll. Fix: keep native scroll. If unavoidable: short, vertical, below the fold, no important text inside, sticky nav to escape, not on mobile. Parallax and scrolljacking can cause dizziness and nausea. (Source: https://www.nngroup.com/articles/scrolljacking-101/, https://www.nngroup.com/articles/animation-duration/)
+- **[A27] Numbers don't count up.** Detect: stats ticking from 0 on scroll. Fix: show the real value; animate numbers only when the value genuinely changes. (Source: https://github.com/funboy322/avoid-ai-design/blob/main/references/ai-tells-catalog.md)
+- **[A28] Hover delays.** Detect: hover previews that flash as the pointer crosses a list. Fix: slight delay before hover-triggered previews; instant response for confirmations. (Source: https://www.nngroup.com/articles/animation-duration/)
+
+## Accessibility and performance
+
+- **[A29] Reduced motion, done right.** Detect: no `prefers-reduced-motion` handling, or a global `* { transition-duration: 0.01ms !important }`. Fix: write motion inside `@media (prefers-reduced-motion: no-preference)`; keep fades, drop movement; in JS default to reduced until the query is read; don't zero durations globally (it can make JS animations faster and worse). (Source: https://www.joshwcomeau.com/react/prefers-reduced-motion/, https://vercel.com/design/guidelines)
+- **[A30] Pause loops, keep interactions.** Detect: ambient loops that keep running under reduced motion, or that stop abruptly mid-frame. Fix: pause ambient loops with `animation-play-state` so they freeze gracefully; user-initiated interactions can stay. Any motion over 5s next to content needs pause/stop/hide controls. (Source: https://rauno.me/craft/vercel, https://vercel.com/design/guidelines)
+- **[A31] Compositor-only properties.** Detect: transitions on `width`, `height`, `top`, `left`, `box-shadow`, or `transition: all`. Fix: animate `transform` and `opacity`; fake glows with a pseudo-element whose opacity changes; list exact properties. (Source: https://vercel.com/design/guidelines, https://rauno.me/craft/nextjs)
+- **[A32] Text and SVG jitter.** Detect: text shimmering or shifting during scale animations; SVG transforms off-centre in Safari. Fix: animate a wrapper, not the text; `will-change: transform` or `translateZ(0)` if artifacts persist; transform SVG `<g>` wrappers with `transform-box: fill-box; transform-origin: center`. (Source: https://vercel.com/design/guidelines, https://emilkowal.ski/ui/agents-with-taste)
+- **[A33] Video, not GIF.** Detect: GIF demos. Fix: `<video autoplay muted loop playsinline>` with a poster, a still alternative and a reduced-motion gate. (Source: https://vercel.com/design/guidelines)
+- **[A34] Start on view, once.** Detect: animations that run off-screen or restart every time they scroll in. Fix: IntersectionObserver (Stripe used threshold 1, fire once) and stop work when not visible. (Source: https://stripe.com/blog/connect-front-end-experience)