import type { SeedId } from "./index"; /** * Motion Keyword Library — the named, copy-pasteable motion vocabulary. * * This is the SINGLE SOURCE OF TRUTH shared by two surfaces: * 1. the `/motion` gallery (live demo + Copy button per keyword) * 2. the `/ss-motion` skill (keyword → code lookup for vibe coding) * * The 5 seeds (spring/silk/snap/float/pulse) define a *personality*. * These keywords define a *distinctive move* — a flip, a curtain wipe, * a morph — so "make the toggle flip" maps to exactly one recipe and * every page in the repo gets the same motion. That keyword↔code * contract is the thing a plain UI-template gallery can't offer. * * Each entry is pure data (safe to import from a Server Component). * The live demo JSX lives in the gallery page, keyed by `key`. */ export type MotionCategory = | "flair" | "toggle" | "reveal" | "press" | "attention" | "list"; export interface MotionKeyword { /** Unique handle — what you type when vibe coding. e.g. "toggle-flip". */ key: string; /** Short human label for the gallery card. */ label: string; category: MotionCategory; /** One-line description of the move. */ vibe: string; /** Closest personality seed, for consistency guidance. */ seed: SeedId; /** Copy-pasteable, runnable framer-motion snippet. */ snippet: string; } export const MOTION_CATEGORIES: { id: MotionCategory; label: string; blurb: string }[] = [ { id: "flair", label: "Flair", blurb: "Showy, cursor-aware, scroll-stopping moves." }, { id: "toggle", label: "Toggle", blurb: "One control, many ways to switch state." }, { id: "reveal", label: "Reveal", blurb: "How an element arrives on screen." }, { id: "press", label: "Press", blurb: "Tactile feedback on tap/click." }, { id: "attention", label: "Attention", blurb: "Looping or one-shot focus pulls." }, { id: "list", label: "List", blurb: "Choreography across many items." }, ]; /** * Motion by use-case — a LIGHT rule, not a mandate. Maps a common UI moment to * the seed or keyword that fits, with the one-line reason. Powers the "which * motion when" cheat on /motion and the recommend mode in /ss-motion. * * Two anti-rules override everything below: * 1. ONE seed per product — pick a personality and keep it; mixing reads as sloppy. * 2. NEVER delay content the user came for — don't animate a balance, a search * result, or a price into view. Motion is for affordance, not for the payload. */ export interface MotionUseCase { /** the UI moment */ useCase: string; /** recommended seed id or keyword handle */ recommend: string; /** one-line why */ why: string; } export const MOTION_BY_USECASE: MotionUseCase[] = [ { useCase: "Primary button / CTA press", recommend: "spring · press", why: "Tactile, confident feedback — the press should feel like it 'gives'." }, { useCase: "Modal / dialog / bottom sheet enter", recommend: "silk · entrance", why: "Smooth and composed; never bounce serious or destructive content in." }, { useCase: "Dropdown / popover / menu", recommend: "snap · entrance", why: "Instant and precise — frequent UI shouldn't make you wait." }, { useCase: "Toast / inline notification", recommend: "spring · entrance", why: "A small friendly arrival that catches the eye without blocking." }, { useCase: "List / feed items appearing", recommend: "stagger-cascade", why: "Choreograph many items so the eye follows the order, gently." }, { useCase: "Feature / marketing card hover", recommend: "tilt-3d", why: "Depth and flair are welcome on content-light marketing surfaces." }, { useCase: "Dashboard / data card hover", recommend: "snap · hover", why: "A subtle lift only — restraint keeps a dense data UI calm." }, { useCase: "Like / favorite / reaction", recommend: "like-burst", why: "A celebratory one-shot; reward the tap." }, { useCase: "Live / online / recording dot", recommend: "pulse-beat", why: "A looping heartbeat signals 'alive' without stealing focus." }, { useCase: "Loading / skeleton", recommend: "shimmer", why: "Calm, directional progress — communicates work without anxiety." }, { useCase: "Success / confirmation", recommend: "pop-in", why: "A positive little arrival that says 'done'." }, { useCase: "Toggle / tab / segment switch", recommend: "toggle-flip", why: "A distinctive, recognizable switch tied to one handle." }, { useCase: "Page / route transition", recommend: "silk · entrance", why: "Smooth and minimal; get out of the way fast." }, { useCase: "Number / balance / KPI / price reveal", recommend: "none", why: "Don't animate the payload — the user came to read it instantly." }, ]; export const MOTION_LIBRARY: MotionKeyword[] = [ // ── Flair (showy, cursor/scroll-aware) ─────────────────── { key: "tilt-3d", label: "3D tilt", category: "flair", vibe: "Card tilts in 3D toward the cursor — depth on hover", seed: "silk", snippet: `import { motion, useMotionValue, useSpring, useTransform } from "framer-motion"; const x = useMotionValue(0); const y = useMotionValue(0); const rotateX = useSpring(useTransform(y, [-0.5, 0.5], [12, -12]), { stiffness: 250, damping: 20 }); const rotateY = useSpring(useTransform(x, [-0.5, 0.5], [-12, 12]), { stiffness: 250, damping: 20 }); { const r = e.currentTarget.getBoundingClientRect(); x.set((e.clientX - r.left) / r.width - 0.5); y.set((e.clientY - r.top) / r.height - 0.5); }} onPointerLeave={() => { x.set(0); y.set(0); }} style={{ rotateX, rotateY, transformPerspective: 800 }} />`, }, { key: "magnetic", label: "Magnetic", category: "flair", vibe: "Button drifts toward the cursor, springs back on leave", seed: "spring", snippet: `import { motion, useSpring } from "framer-motion"; const x = useSpring(0, { stiffness: 300, damping: 20 }); const y = useSpring(0, { stiffness: 300, damping: 20 }); { const r = e.currentTarget.getBoundingClientRect(); x.set((e.clientX - r.left - r.width / 2) * 0.4); y.set((e.clientY - r.top - r.height / 2) * 0.4); }} onPointerLeave={() => { x.set(0); y.set(0); }} style={{ x, y }} > Hover me `, }, { key: "glow-pulse", label: "Glow pulse", category: "flair", vibe: "Breathing neon glow — draws the eye to a hot CTA", seed: "pulse", snippet: ``, }, { key: "gradient-sweep", label: "Gradient sweep", category: "flair", vibe: "Animated gradient flows through text or a surface", seed: "silk", snippet: ` Gradient `, }, { key: "blob-morph", label: "Blob morph", category: "flair", vibe: "Organic shape endlessly morphs — living background blob", seed: "float", snippet: ``, }, { key: "spotlight", label: "Spotlight", category: "flair", vibe: "Radial light follows the cursor across a card", seed: "silk", snippet: `import { motion, useMotionValue, useMotionTemplate } from "framer-motion"; const mx = useMotionValue(50); const my = useMotionValue(50); const bg = useMotionTemplate\`radial-gradient(160px circle at \${mx}% \${my}%, rgba(255,255,255,0.25), transparent 60%)\`; { const r = e.currentTarget.getBoundingClientRect(); mx.set(((e.clientX - r.left) / r.width) * 100); my.set(((e.clientY - r.top) / r.height) * 100); }} style={{ backgroundImage: bg }} />`, }, { key: "text-scramble", label: "Scramble", category: "flair", vibe: "Letters decode into place — hacker/terminal reveal", seed: "snap", snippet: `const CHARS = "!<>-_\\\\/[]{}—=+*^?#"; const [text, setText] = useState("StyleSeed"); function scramble(target: string) { let frame = 0; const id = setInterval(() => { setText( target .split("") .map((c, i) => (i < frame / 3 ? c : CHARS[Math.floor(Math.random() * CHARS.length)])) .join(""), ); if (frame++ > target.length * 3) clearInterval(id); }, 30); } `, }, { key: "confetti-pop", label: "Confetti", category: "flair", vibe: "Particle burst on success — celebrate the click", seed: "spring", snippet: `const COLORS = ["#FF6B6B", "#FFD93D", "#6C5CE7", "#4ECDC4"]; const [bits, setBits] = useState([]); `, }, // ── Toggle ─────────────────────────────────────────────── { key: "toggle-flip", label: "Flip", category: "toggle", vibe: "3D Y-axis card flip between two faces", seed: "spring", snippet: `const [on, setOn] = useState(false); setOn((o) => !o)} animate={{ rotateY: on ? 180 : 0 }} transition={{ type: "spring", stiffness: 260, damping: 22 }} style={{ transformStyle: "preserve-3d", perspective: 800 }} />`, }, { key: "toggle-slide", label: "Slide stack", category: "toggle", vibe: "Old value slides out, new slides in from the side", seed: "snap", snippet: ` {value} `, }, { key: "toggle-morph", label: "Morph", category: "toggle", vibe: "Shape morphs — pill ⇄ circle, width + radius", seed: "silk", snippet: `const [on, setOn] = useState(false); setOn((o) => !o)} animate={{ borderRadius: on ? 999 : 16, width: on ? 56 : 160 }} transition={{ type: "spring", stiffness: 300, damping: 26 }} />`, }, { key: "toggle-curtain", label: "Curtain", category: "toggle", vibe: "Top→bottom clip-path wipe reveals the panel", seed: "silk", snippet: `const [open, setOpen] = useState(false); `, }, // ── Reveal ─────────────────────────────────────────────── { key: "reveal-blur", label: "Blur in", category: "reveal", vibe: "Focus-pulls into place from a soft blur", seed: "float", snippet: ``, }, { key: "reveal-rise", label: "Text rise", category: "reveal", vibe: "Masked clip-path rise — text climbs into view", seed: "silk", snippet: ``, }, { key: "reveal-unfold", label: "Unfold", category: "reveal", vibe: "scaleY from the top edge, like an accordion", seed: "spring", snippet: ``, }, { key: "pop-in", label: "Pop in", category: "reveal", vibe: "Spring overshoot from zero — bouncy arrival", seed: "spring", snippet: ``, }, // ── Press ──────────────────────────────────────────────── { key: "press-squish", label: "Squish", category: "press", vibe: "Scale-down + tiny skew — jelly press", seed: "spring", snippet: ``, }, { key: "tap-ripple", label: "Ripple", category: "press", vibe: "Material-style radial ripple from the tap point", seed: "snap", snippet: `const [ripples, setRipples] = useState<{ id: number; x: number; y: number }[]>([]); function onTap(e: React.PointerEvent) { const r = e.currentTarget.getBoundingClientRect(); setRipples((rs) => [...rs, { id: performance.now(), x: e.clientX - r.left, y: e.clientY - r.top }]); } `, }, // ── Attention ──────────────────────────────────────────── { key: "pulse-beat", label: "Heartbeat", category: "attention", vibe: "Looping scale pulse — alive, rhythmic", seed: "pulse", snippet: ``, }, { key: "wiggle", label: "Wiggle", category: "attention", vibe: "Quick horizontal shake — error / wrong input", seed: "snap", snippet: ``, }, { key: "shimmer", label: "Shimmer", category: "attention", vibe: "Skeleton loading sweep across a surface", seed: "silk", snippet: ``, }, // ── List ───────────────────────────────────────────────── { key: "stagger-cascade", label: "Cascade", category: "list", vibe: "Children fade-up one after another", seed: "silk", snippet: ` {items.map((item) => ( {item.label} ))} `, }, ]; /** Keyword → entry, for the /ss-motion skill and Copy lookups. */ export const MOTION_BY_KEY: Record = Object.fromEntries( MOTION_LIBRARY.map((m) => [m.key, m]), );