wizz-method 1.3.2 → 1.4.0

package/src/skills-lib/animate/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: animate
+description: Animation patterns and best practices for Next.js/React applications. Use this skill when implementing animations, transitions, hover effects, page transitions, modals, or any motion in React components. Based on Emil Kowalski's "Animations on the Web" course.
+---
+
+# Next.js Animations
+
+## Overview
+
+This skill provides comprehensive guidance for implementing smooth, performant, and accessible animations in Next.js and React applications. It covers CSS animations, Framer Motion, easing principles, and accessibility considerations.
+
+## Quick Reference
+
+### Easing Cheat Sheet
+
+| Animation Type | Easing | Duration |
+|----------------|--------|----------|
+| Element entering | `ease-out` | 200-300ms |
+| Element moving on screen | `ease-in-out` | 200-300ms |
+| Element exiting | `ease-in` | 150-200ms |
+| Hover effects | `ease` | 150ms |
+| Opacity only | `linear` | varies |
+
+### CSS Custom Properties (Recommended)
+
+```css
+:root {
+  --ease-out-quint: cubic-bezier(.23, 1, .32, 1);
+  --ease-in-out-cubic: cubic-bezier(.645, .045, .355, 1);
+  --ease-out-cubic: cubic-bezier(.33, 1, .68, 1);
+}
+```
+
+## Common Animation Patterns
+
+### 1. Hover Lift Effect
+
+```css
+.card {
+  transition: transform 200ms var(--ease-out-quint),
+              box-shadow 200ms var(--ease-out-quint);
+}
+.card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15);
+}
+```
+
+### 2. Button Press
+
+```css
+.button {
+  transition: transform 100ms ease-out;
+}
+.button:active {
+  transform: scale(0.97);
+}
+```
+
+### 3. Fade In on Mount (Framer Motion)
+
+```tsx
+<motion.div
+  initial={{ opacity: 0, y: 20 }}
+  animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.3, ease: [.23, 1, .32, 1] }}
+>
+  Content
+</motion.div>
+```
+
+### 4. Modal with Exit Animation
+
+```tsx
+<AnimatePresence>
+  {isOpen && (
+    <motion.div
+      initial={{ opacity: 0, scale: 0.95 }}
+      animate={{ opacity: 1, scale: 1 }}
+      exit={{ opacity: 0, scale: 0.95 }}
+      transition={{ duration: 0.2, ease: "easeOut" }}
+    >
+      {children}
+    </motion.div>
+  )}
+</AnimatePresence>
+```
+
+### 5. Tab Indicator (Shared Layout)
+
+```tsx
+{tabs.map(tab => (
+  <button key={tab} onClick={() => setActive(tab)} className="relative px-4 py-2">
+    {tab}
+    {active === tab && (
+      <motion.div
+        layoutId="tab-indicator"
+        className="absolute inset-0 bg-blue-500 rounded -z-10"
+        transition={{ type: "spring", stiffness: 400, damping: 30 }}
+      />
+    )}
+  </button>
+))}
+```
+
+### 6. Staggered List Animation
+
+```tsx
+const container = {
+  hidden: { opacity: 0 },
+  visible: {
+    opacity: 1,
+    transition: { staggerChildren: 0.1 }
+  }
+}
+
+const item = {
+  hidden: { opacity: 0, y: 20 },
+  visible: { opacity: 1, y: 0 }
+}
+
+<motion.ul variants={container} initial="hidden" animate="visible">
+  {items.map(i => <motion.li key={i} variants={item}>{i}</motion.li>)}
+</motion.ul>
+```
+
+## Golden Rules
+
+1. **Exits faster than enters**: Exit animations should be ~75% of enter duration
+2. **Only animate transform and opacity**: These are GPU-accelerated
+3. **200-300ms is the sweet spot**: Most animations should be in this range
+4. **Always respect prefers-reduced-motion**: See accessibility section in references
+5. **Use springs for interruptible animations**: Better UX when users interrupt
+
+## Examples
+
+Complete working examples from the course are in the `examples/` directory:
+
+| Example | Description | Key Techniques |
+|---------|-------------|----------------|
+| `card-hover.tsx` | Slide-up description on hover | CSS transitions, transform, opacity |
+| `toast-stacking.tsx` | Animated toast notifications | CSS custom properties, data-* triggers |
+| `text-reveal.tsx` | Staggered letter animation | @keyframes, animation-delay, calc() |
+| `shared-layout.tsx` | Element position/size morph | Framer Motion layoutId |
+| `animate-height.tsx` | Smooth height changes | useMeasure, animate height |
+| `multi-step-flow.tsx` | Directional step wizard | AnimatePresence, custom variants |
+| `feedback-popover.tsx` | Button-to-popover expansion | Nested layoutId, form states |
+| `app-store-card.tsx` | iOS-style card expansion | Multiple layoutId elements |
+
+To use an example, read it with: `Read examples/<name>.tsx`
+
+## References
+
+For detailed documentation, read the reference files:
+
+- `references/easing-and-timing.md` - Easing functions, timing guidelines, spring configuration
+- `references/css-animations.md` - Transforms, transitions, keyframes, clip-path
+- `references/framer-motion.md` - Motion components, AnimatePresence, variants, layout animations, hooks
+- `references/performance-accessibility.md` - 60fps optimization, prefers-reduced-motion, accessibility
+
+## When to Use What
+
+| Scenario | Recommended Approach |
+|----------|---------------------|
+| Simple hover effects | CSS transitions |
+| Enter/exit animations | Framer Motion + AnimatePresence |
+| Layout changes | Framer Motion `layout` prop |
+| Shared element transitions | Framer Motion `layoutId` |
+| Scroll-linked animations | Framer Motion `useScroll` |
+| Complex orchestrated animations | Framer Motion variants |
+| Drag interactions | Framer Motion drag gestures |
+| Performance-critical | CSS-only with transforms |
+
+## Dependencies
+
+For Framer Motion examples, install:
+```bash
+pnpm add framer-motion react-use-measure usehooks-ts
+```

package/src/skills-lib/animate/examples/animate-height.tsx

@@ -0,0 +1,75 @@
+/**
+ * Animate Height
+ *
+ * Smoothly animate height changes when content expands/collapses.
+ * Uses react-use-measure to get the actual content height.
+ *
+ * Key techniques:
+ * - useMeasure hook to get dynamic content dimensions
+ * - Animate height property (normally discouraged, but acceptable here)
+ * - Inner wrapper ref for measuring, outer wrapper for animating
+ * - Works for any dynamic content changes
+ *
+ * Note: Install react-use-measure: pnpm add react-use-measure
+ */
+"use client";
+
+import { motion } from "framer-motion";
+import { useState } from "react";
+import useMeasure from "react-use-measure";
+
+// styles.css
+const styles = `
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+  align-items: center;
+}
+
+.element {
+  background: #f5f5f5;
+  border-radius: 12px;
+  overflow: hidden;
+  width: 300px;
+}
+
+.inner {
+  padding: 16px;
+}
+`;
+
+export default function AnimateHeight() {
+  const [showExtraContent, setShowExtraContent] = useState(false);
+  const [ref, bounds] = useMeasure();
+
+  return (
+    <div className="wrapper">
+      <button onClick={() => setShowExtraContent((b) => !b)}>
+        Toggle height
+      </button>
+
+      {/* Outer div animates to measured height */}
+      <motion.div
+        className="element"
+        animate={{ height: bounds.height }}
+        transition={{ duration: 0.3 }}
+      >
+        {/* Inner div is measured */}
+        <div className="inner" ref={ref}>
+          <h1>Expandable Drawer</h1>
+          <p>
+            This content can grow and shrink. The animation smoothly
+            transitions between heights.
+          </p>
+          {showExtraContent && (
+            <p>
+              This extra content will change the height of the drawer.
+              The animation handles any content changes automatically.
+            </p>
+          )}
+        </div>
+      </motion.div>
+    </div>
+  );
+}

package/src/skills-lib/animate/examples/app-store-card.tsx

@@ -0,0 +1,164 @@
+/**
+ * App Store Card Expansion
+ *
+ * iOS App Store-style card that expands to full screen with shared
+ * layout animation. Multiple elements animate together.
+ *
+ * Key techniques:
+ * - Multiple layoutId elements that animate together
+ * - whileTap for press feedback
+ * - Overlay with separate AnimatePresence
+ * - useOnClickOutside and Escape key for dismiss
+ * - borderRadius in style prop to prevent distortion
+ */
+"use client";
+
+import { useState, useEffect, useRef } from "react";
+import { AnimatePresence, motion } from "framer-motion";
+import { useOnClickOutside } from "usehooks-ts";
+
+type Card = {
+  title: string;
+  description: string;
+  longDescription: string;
+  image: string;
+};
+
+// Card in grid view
+function Card({
+  card,
+  setActiveCard,
+}: {
+  card: Card;
+  setActiveCard: (card: Card | null) => void;
+}) {
+  return (
+    <motion.div
+      layoutId={`card-${card.title}`}
+      className="card"
+      whileTap={{ scale: 0.98 }}
+      onClick={() => setActiveCard(card)}
+      style={{ borderRadius: 20 }}
+    >
+      <motion.img
+        layoutId={`image-${card.title}`}
+        src={card.image}
+        alt=""
+        style={{ borderRadius: 20 }}
+        draggable={false}
+      />
+      <motion.div layoutId={`card-content-${card.title}`} className="card-content">
+        <motion.h2 layoutId={`card-heading-${card.title}`}>
+          {card.title}
+        </motion.h2>
+        <motion.p layoutId={`card-description-${card.title}`}>
+          {card.description}
+        </motion.p>
+      </motion.div>
+
+      {/* Hidden long description - will animate in when expanded */}
+      <motion.div
+        layoutId={`card-long-description-${card.title}`}
+        style={{ position: "absolute", top: "100%", opacity: 0 }}
+      >
+        {card.longDescription}
+      </motion.div>
+    </motion.div>
+  );
+}
+
+// Expanded card view
+function ActiveCard({
+  activeCard,
+  setActiveCard,
+}: {
+  activeCard: Card;
+  setActiveCard: (card: Card | null) => void;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  useOnClickOutside(ref, () => setActiveCard(null));
+
+  return (
+    <motion.div
+      ref={ref}
+      layoutId={`card-${activeCard.title}`}
+      className="card card-active"
+      style={{ borderRadius: 0 }}
+    >
+      <motion.img
+        layoutId={`image-${activeCard.title}`}
+        src={activeCard.image}
+        alt=""
+        style={{ borderRadius: 0 }}
+      />
+      <motion.button
+        className="close-button"
+        onClick={() => setActiveCard(null)}
+      >
+        ✕
+      </motion.button>
+      <motion.div layoutId={`card-content-${activeCard.title}`} className="card-content">
+        <motion.h2 layoutId={`card-heading-${activeCard.title}`}>
+          {activeCard.title}
+        </motion.h2>
+        <motion.p layoutId={`card-description-${activeCard.title}`}>
+          {activeCard.description}
+        </motion.p>
+      </motion.div>
+
+      {/* Long description now visible */}
+      <motion.div layoutId={`card-long-description-${activeCard.title}`}>
+        {activeCard.longDescription}
+      </motion.div>
+    </motion.div>
+  );
+}
+
+export default function AppStoreCards() {
+  const [activeCard, setActiveCard] = useState<Card | null>(null);
+
+  // Dismiss on Escape
+  useEffect(() => {
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") setActiveCard(null);
+    }
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, []);
+
+  return (
+    <div className="cards-wrapper">
+      {CARDS.map((card) => (
+        <Card key={card.title} card={card} setActiveCard={setActiveCard} />
+      ))}
+
+      {/* Overlay */}
+      <AnimatePresence>
+        {activeCard && (
+          <motion.div
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            className="overlay"
+          />
+        )}
+      </AnimatePresence>
+
+      {/* Expanded card */}
+      <AnimatePresence>
+        {activeCard && (
+          <ActiveCard activeCard={activeCard} setActiveCard={setActiveCard} />
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}
+
+const CARDS: Card[] = [
+  {
+    title: "Game Title",
+    description: "A brief description",
+    longDescription: "Full description with more details about the game...",
+    image: "/game-image.webp",
+  },
+];

package/src/skills-lib/animate/examples/card-hover.tsx

@@ -0,0 +1,79 @@
+/**
+ * Card Hover Animation
+ *
+ * A card component where the description slides up from the bottom on hover.
+ * Uses CSS transitions with transform and opacity for smooth animation.
+ *
+ * Key techniques:
+ * - Transform translateY to slide content in/out
+ * - Combined transition on transform and opacity
+ * - :hover and :focus-visible for accessibility
+ * - overflow: hidden on parent to clip content
+ */
+
+// card-hover.css
+const styles = `
+.card-hover {
+  width: 340px;
+  height: 340px;
+  border-radius: 16px;
+  background: #fff;
+  display: flex;
+  align-items: flex-end;
+  text-decoration: none;
+  box-shadow: 0px 0px 0px 1px rgba(9, 9, 11, 0.08),
+    0px 1px 2px -1px rgba(9, 9, 11, 0.08),
+    0px 2px 4px 0px rgba(9, 9, 11, 0.04);
+  overflow: hidden;
+}
+
+.card-hover-description {
+  border-radius: 12px;
+  border: 1px solid #fff;
+  position: relative;
+  background: #fafafa;
+  margin: 6px;
+  width: 100%;
+  padding: 10px 14px 13px;
+  font-size: 13px;
+  box-shadow: 0px 0px 0px 1px rgba(0, 0, 0, 0.08),
+    0px 1px 2px -1px rgba(0, 0, 0, 0.08),
+    0px 2px 4px 0px rgba(0, 0, 0, 0.04);
+
+  /* Animation - hidden by default */
+  transform: translateY(calc(100% + 8px));
+  transition-duration: 350ms;
+  transition-timing-function: ease;
+  transition-property: transform, opacity;
+  opacity: 0;
+}
+
+/* Show on hover or keyboard focus */
+.card-hover:hover .card-hover-description,
+.card-hover:focus-visible .card-hover-description {
+  transform: translateY(0%);
+  opacity: 1;
+}
+
+.card-hover-title {
+  color: #1b1b1d;
+  font-weight: 500;
+}
+
+.card-hover-subtitle {
+  color: #717175;
+  line-height: 1;
+  margin-top: 4px;
+}
+`;
+
+export default function CardHover() {
+  return (
+    <a href="#" className="card-hover">
+      <div className="card-hover-description">
+        <h3 className="card-hover-title">Project name</h3>
+        <p className="card-hover-subtitle">Project description</p>
+      </div>
+    </a>
+  );
+}

package/src/skills-lib/animate/examples/feedback-popover.tsx

@@ -0,0 +1,119 @@
+/**
+ * Feedback Popover Animation
+ *
+ * A button that expands into a feedback form using shared layout animation.
+ * Shows loading and success states with animated transitions.
+ *
+ * Key techniques:
+ * - layoutId on button and popover for seamless expansion
+ * - Nested layoutId elements (text placeholder)
+ * - AnimatePresence for popover enter/exit
+ * - Form state transitions (idle -> loading -> success)
+ * - useOnClickOutside for dismiss behavior
+ *
+ * Note: Install usehooks-ts: pnpm add usehooks-ts
+ */
+"use client";
+
+import { AnimatePresence, motion } from "framer-motion";
+import { useEffect, useState, useRef } from "react";
+import { useOnClickOutside } from "usehooks-ts";
+
+export default function FeedbackPopover() {
+  const [open, setOpen] = useState(false);
+  const [formState, setFormState] = useState<"idle" | "loading" | "success">("idle");
+  const [feedback, setFeedback] = useState("");
+  const ref = useRef<HTMLDivElement>(null);
+
+  // Close on click outside
+  useOnClickOutside(ref, () => setOpen(false));
+
+  function submit() {
+    setFormState("loading");
+    setTimeout(() => setFormState("success"), 1500);
+    setTimeout(() => setOpen(false), 3300);
+  }
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setOpen(false);
+      if ((event.ctrlKey || event.metaKey) && event.key === "Enter" && open && formState === "idle") {
+        submit();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [open, formState]);
+
+  return (
+    <div className="feedback-wrapper">
+      {/* Button with layoutId - will animate into popover */}
+      <motion.button
+        onClick={() => {
+          setOpen(true);
+          setFormState("idle");
+          setFeedback("");
+        }}
+        className="feedback-button"
+        style={{ borderRadius: 8 }}
+        layoutId="background"
+      >
+        <motion.span layoutId="placeholder">
+          Feedback
+        </motion.span>
+      </motion.button>
+
+      <AnimatePresence>
+        {open && (
+          <motion.div
+            ref={ref}
+            className="feedback-popover"
+            style={{ borderRadius: 12 }}
+            layoutId="background"
+          >
+            {/* Placeholder text animates with the layout */}
+            <motion.span
+              aria-hidden
+              className="placeholder"
+              layoutId="placeholder"
+              style={{ opacity: feedback ? 0 : 0.5 }}
+            >
+              Feedback
+            </motion.span>
+
+            {formState === "success" ? (
+              <div className="success-wrapper">
+                <h3>Feedback received!</h3>
+                <p>Thanks for your feedback.</p>
+              </div>
+            ) : (
+              <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
+                <textarea
+                  autoFocus
+                  placeholder="Feedback"
+                  onChange={(e) => setFeedback(e.target.value)}
+                  value={feedback}
+                  required
+                />
+                <button type="submit">
+                  <AnimatePresence mode="popLayout" initial={false}>
+                    <motion.span
+                      key={formState}
+                      initial={{ opacity: 0, y: -25 }}
+                      animate={{ opacity: 1, y: 0 }}
+                      exit={{ opacity: 0, y: 25 }}
+                      transition={{ type: "spring", duration: 0.3, bounce: 0 }}
+                    >
+                      {formState === "loading" ? "Sending..." : "Send feedback"}
+                    </motion.span>
+                  </AnimatePresence>
+                </button>
+              </form>
+            )}
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}