wizz-method 1.3.1 → 1.4.0

package/src/skills-lib/animate/examples/multi-step-flow.tsx

@@ -0,0 +1,128 @@
+/**
+ * Multi-Step Flow Animation
+ *
+ * Animated wizard/stepper with directional slide transitions.
+ * Steps slide in from the direction of navigation.
+ *
+ * Key techniques:
+ * - AnimatePresence mode="popLayout" for exit animations
+ * - custom prop for directional variants (slide left or right)
+ * - useMeasure for animating container height
+ * - useReducedMotion for accessibility
+ * - MotionConfig for shared transition settings
+ */
+"use client";
+
+import { useMemo, useState } from "react";
+import {
+  AnimatePresence,
+  MotionConfig,
+  motion,
+  useReducedMotion,
+} from "framer-motion";
+import useMeasure from "react-use-measure";
+
+// Directional slide variants
+const variants = {
+  initial: (direction: number) => ({
+    x: `${110 * direction}%`,
+    opacity: 0,
+  }),
+  active: {
+    x: "0%",
+    opacity: 1,
+  },
+  exit: (direction: number) => ({
+    x: `${-110 * direction}%`,
+    opacity: 0,
+  }),
+};
+
+// Reduced motion alternative - just fade
+const reducedMotionVariants = {
+  initial: { opacity: 0 },
+  active: { opacity: 1 },
+  exit: { opacity: 0 },
+};
+
+export default function MultiStepComponent() {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [direction, setDirection] = useState<number>(0);
+  const [ref, bounds] = useMeasure();
+  const reducedMotion = useReducedMotion();
+
+  const content = useMemo(() => {
+    switch (currentStep) {
+      case 0:
+        return (
+          <>
+            <h2>Step One</h2>
+            <p>First step content goes here.</p>
+          </>
+        );
+      case 1:
+        return (
+          <>
+            <h2>Step Two</h2>
+            <p>Second step with different content length.</p>
+            <p>Extra paragraph to show height animation.</p>
+          </>
+        );
+      case 2:
+        return (
+          <>
+            <h2>Step Three</h2>
+            <p>Final step - you made it!</p>
+          </>
+        );
+    }
+  }, [currentStep]);
+
+  return (
+    <MotionConfig transition={{ duration: 0.5, type: "spring", bounce: 0 }}>
+      {/* Container animates height based on content */}
+      <motion.div
+        className="multi-step-wrapper"
+        animate={reducedMotion ? {} : { height: bounds.height }}
+      >
+        <div className="multi-step-inner" ref={ref}>
+          {/* AnimatePresence handles exit animations */}
+          <AnimatePresence mode="popLayout" initial={false} custom={direction}>
+            <motion.div
+              key={currentStep}
+              variants={reducedMotion ? reducedMotionVariants : variants}
+              initial="initial"
+              animate="active"
+              exit="exit"
+              custom={direction}
+            >
+              {content}
+            </motion.div>
+          </AnimatePresence>
+
+          {/* Buttons use layout animation to stay in place */}
+          <motion.div className="actions" layout={!reducedMotion}>
+            <button
+              disabled={currentStep === 0}
+              onClick={() => {
+                setCurrentStep((prev) => prev - 1);
+                setDirection(-1); // Slide from left
+              }}
+            >
+              Back
+            </button>
+            <button
+              disabled={currentStep === 2}
+              onClick={() => {
+                setCurrentStep((prev) => prev + 1);
+                setDirection(1); // Slide from right
+              }}
+            >
+              Continue
+            </button>
+          </motion.div>
+        </div>
+      </motion.div>
+    </MotionConfig>
+  );
+}

package/src/skills-lib/animate/examples/shared-layout.tsx

@@ -0,0 +1,64 @@
+/**
+ * Shared Layout Animation
+ *
+ * Demonstrates Framer Motion's layoutId for seamless transitions
+ * between two different elements/positions.
+ *
+ * Key techniques:
+ * - layoutId creates a shared identity between elements
+ * - Motion automatically animates position and size changes
+ * - style={{ borderRadius }} prevents border radius distortion during animation
+ */
+"use client";
+
+import { motion } from "framer-motion";
+import { useState } from "react";
+
+// styles.css
+const styles = `
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+  align-items: center;
+}
+
+.element {
+  width: 100px;
+  height: 100px;
+  background: #3b82f6;
+}
+
+.second-element {
+  width: 200px;
+  height: 200px;
+  background: #3b82f6;
+}
+`;
+
+export default function SharedLayoutExample() {
+  const [showSecond, setShowSecond] = useState(false);
+
+  return (
+    <div className="wrapper">
+      <button onClick={() => setShowSecond((s) => !s)}>
+        Animate
+      </button>
+
+      {/* Same layoutId = smooth transition between the two */}
+      {showSecond ? (
+        <motion.div
+          layoutId="rectangle"
+          className="second-element"
+          style={{ borderRadius: 12 }}
+        />
+      ) : (
+        <motion.div
+          layoutId="rectangle"
+          className="element"
+          style={{ borderRadius: 12 }}
+        />
+      )}
+    </div>
+  );
+}

package/src/skills-lib/animate/examples/text-reveal.tsx

@@ -0,0 +1,70 @@
+/**
+ * Text Reveal Animation
+ *
+ * Staggered letter-by-letter text reveal animation using CSS keyframes.
+ * Each letter animates in sequence with a delay based on its index.
+ *
+ * Key techniques:
+ * - Split text into individual spans
+ * - CSS custom property (--index) for stagger delay
+ * - @keyframes for the reveal animation
+ * - animation-fill-mode: backwards to hide before animation
+ * - cubic-bezier for smooth easing
+ */
+"use client";
+
+import { useState } from "react";
+
+// text-reveal.css
+const styles = `
+.h1 {
+  font-size: 4rem;
+  font-weight: bold;
+  overflow: hidden;
+}
+
+.h1 span {
+  display: inline-block;
+  animation: reveal 1.3s cubic-bezier(0.19, 1, 0.22, 1);
+  animation-fill-mode: backwards;
+  animation-delay: calc(var(--index) * 0.03s);
+}
+
+@keyframes reveal {
+  from {
+    transform: translateY(100%);
+    opacity: 0;
+  }
+  to {
+    transform: translateY(0);
+    opacity: 1;
+  }
+}
+`;
+
+const WORD = "Animations";
+
+export default function TextReveal() {
+  const [reset, setReset] = useState(0);
+
+  return (
+    <div className="flex flex-col gap-4">
+      {/* Key change forces re-render and replays animation */}
+      <div key={reset}>
+        <h1 className="h1">
+          {WORD.split("").map((char, index) => (
+            <span
+              key={index}
+              style={{ "--index": index } as React.CSSProperties}
+            >
+              {char}
+            </span>
+          ))}
+        </h1>
+      </div>
+      <button onClick={() => setReset(reset + 1)}>
+        Replay animation
+      </button>
+    </div>
+  );
+}

package/src/skills-lib/animate/examples/toast-stacking.tsx

@@ -0,0 +1,95 @@
+/**
+ * Toast Stacking Animation
+ *
+ * Animated toast notifications that stack vertically with smooth transitions.
+ * Uses CSS custom properties (--index) for dynamic positioning.
+ *
+ * Key techniques:
+ * - CSS custom properties for dynamic values
+ * - data-* attributes to trigger CSS transitions
+ * - useEffect to trigger mount animation
+ * - calc() for computing stack positions
+ */
+"use client";
+
+import { useEffect, useState } from "react";
+
+// toast-animation.css
+const styles = `
+.toast {
+  position: absolute;
+  bottom: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 10px 14px 13px;
+  width: 100%;
+  font-size: 13px;
+  border-radius: 8px;
+  background: white;
+  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 - starts hidden below */
+  transition-property: transform, opacity;
+  transition-duration: 350ms;
+  transition-timing-function: ease;
+  transform: translateY(100%);
+  opacity: 0;
+}
+
+/* Animate to stacked position when mounted */
+.toast[data-mounted="true"] {
+  transform: translateY(calc(var(--index) * (100% + var(--gap)) * -1));
+  opacity: 1;
+}
+
+.toaster {
+  position: absolute;
+  left: 50%;
+  bottom: 80px;
+  display: flex;
+  flex-direction: column;
+  gap: var(--gap);
+  width: 356px;
+  transform: translateX(-50%);
+  --gap: 16px;
+}
+`;
+
+export default function Toaster() {
+  const [toasts, setToasts] = useState(0);
+
+  return (
+    <div className="toast-wrapper">
+      <div className="toaster">
+        {Array.from({ length: toasts }).map((_, i) => (
+          <Toast key={i} index={toasts - (i + 1)} />
+        ))}
+      </div>
+      <button onClick={() => setToasts(toasts + 1)}>
+        Add toast
+      </button>
+    </div>
+  );
+}
+
+function Toast({ index }: { index: number }) {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  return (
+    <div
+      className="toast"
+      style={{ "--index": index } as React.CSSProperties}
+      data-mounted={mounted}
+    >
+      <span className="title">Event Created</span>
+      <span className="description">Monday, January 3rd at 6:00pm</span>
+    </div>
+  );
+}

package/src/skills-lib/animate/references/css-animations.md

@@ -0,0 +1,232 @@
+# CSS Animations Reference
+
+## Transforms
+
+Transforms change an element's position, size, or rotation without affecting layout. They are GPU-accelerated and performant.
+
+### Transform Functions
+
+```css
+/* Translation (movement) */
+transform: translateX(10px);
+transform: translateY(-20px);
+transform: translate(10px, -20px);  /* X, Y */
+transform: translate3d(10px, 20px, 30px);  /* X, Y, Z */
+
+/* Scale */
+transform: scale(1.1);  /* Uniform scale */
+transform: scaleX(0.5);
+transform: scaleY(1.5);
+transform: scale(0.5, 1.5);  /* X, Y */
+
+/* Rotation */
+transform: rotate(45deg);
+transform: rotateX(45deg);  /* 3D - around X axis */
+transform: rotateY(45deg);  /* 3D - around Y axis */
+transform: rotateZ(45deg);  /* Same as rotate() */
+
+/* Combining transforms */
+transform: translateY(-10px) scale(1.05) rotate(5deg);
+```
+
+### Transform Origin
+
+Controls the point around which transforms occur:
+
+```css
+transform-origin: center;  /* Default */
+transform-origin: top left;
+transform-origin: 50% 100%;  /* Center bottom */
+transform-origin: 0 0;  /* Top left corner */
+```
+
+### 3D Transforms
+
+```css
+/* Enable 3D space on parent */
+.parent {
+  perspective: 1000px;  /* Distance from viewer */
+  perspective-origin: center;
+}
+
+/* 3D transforms on children */
+.child {
+  transform: rotateY(45deg);
+  transform-style: preserve-3d;  /* Maintain 3D for nested elements */
+  backface-visibility: hidden;  /* Hide back of element */
+}
+```
+
+## Transitions
+
+Transitions animate property changes over time.
+
+### Syntax
+
+```css
+/* Individual properties */
+transition-property: transform, opacity;
+transition-duration: 200ms;
+transition-timing-function: ease-out;
+transition-delay: 0ms;
+
+/* Shorthand */
+transition: transform 200ms ease-out, opacity 150ms ease-out 50ms;
+/*          property  duration timing   property duration timing  delay */
+```
+
+### Common Transition Patterns
+
+```css
+/* Hover lift effect */
+.card {
+  transition: transform 200ms ease-out, box-shadow 200ms ease-out;
+}
+.card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15);
+}
+
+/* Button press effect */
+.button {
+  transition: transform 100ms ease-out;
+}
+.button:active {
+  transform: scale(0.97);
+}
+
+/* Fade in/out */
+.element {
+  opacity: 0;
+  transition: opacity 200ms ease-out;
+}
+.element.visible {
+  opacity: 1;
+}
+```
+
+### Performance-Safe Properties
+
+These properties are GPU-accelerated and won't cause layout recalculation:
+- `transform`
+- `opacity`
+
+Avoid animating (cause layout/paint):
+- `width`, `height`
+- `top`, `left`, `right`, `bottom`
+- `margin`, `padding`
+- `border-width`
+
+## Keyframe Animations
+
+For complex, multi-step animations.
+
+### Basic Syntax
+
+```css
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pulse {
+  0%, 100% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.05);
+  }
+}
+
+.element {
+  animation: fadeIn 300ms ease-out forwards;
+}
+```
+
+### Animation Properties
+
+```css
+animation-name: fadeIn;
+animation-duration: 300ms;
+animation-timing-function: ease-out;
+animation-delay: 0ms;
+animation-iteration-count: 1;  /* or 'infinite' */
+animation-direction: normal;  /* or 'reverse', 'alternate' */
+animation-fill-mode: forwards;  /* 'none', 'forwards', 'backwards', 'both' */
+animation-play-state: running;  /* or 'paused' */
+
+/* Shorthand */
+animation: fadeIn 300ms ease-out 0ms 1 normal forwards;
+```
+
+### Fill Modes Explained
+
+- `none`: No styles applied before/after animation
+- `forwards`: Retains final keyframe styles after animation
+- `backwards`: Applies initial keyframe styles during delay
+- `both`: Applies both forwards and backwards
+
+## Clip-Path Animations
+
+Clip-path creates masked areas that can be animated.
+
+### Common Shapes
+
+```css
+/* Circle */
+clip-path: circle(50% at center);
+clip-path: circle(0% at center);  /* Hidden */
+
+/* Ellipse */
+clip-path: ellipse(50% 30% at center);
+
+/* Inset (rectangle) */
+clip-path: inset(0);  /* Full visibility */
+clip-path: inset(50%);  /* Hidden (collapsed to center) */
+clip-path: inset(0 50% 0 0);  /* Right half hidden */
+/* inset(top right bottom left) */
+
+/* Polygon */
+clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);  /* Rectangle */
+clip-path: polygon(50% 0, 100% 100%, 0 100%);  /* Triangle */
+```
+
+### Clip-Path Animation Example (Image Comparison Slider)
+
+```css
+.before-image {
+  clip-path: inset(0 50% 0 0);  /* Show left half */
+  transition: clip-path 0ms;  /* Instant update */
+}
+
+/* JavaScript updates the clip-path based on slider position */
+```
+
+### Tab Indicator with Clip-Path
+
+```tsx
+// Active tab background slides using clip-path
+<div className="relative">
+  {tabs.map((tab, index) => (
+    <button
+      key={tab}
+      onClick={() => setActive(index)}
+      className="relative z-10 px-4 py-2"
+    >
+      {tab}
+    </button>
+  ))}
+  <div
+    className="absolute inset-0 bg-blue-500 rounded transition-all duration-200"
+    style={{
+      clipPath: `inset(0 ${100 - (activeIndex + 1) * (100 / tabs.length)}% 0 ${activeIndex * (100 / tabs.length)}% round 8px)`
+    }}
+  />
+</div>
+```

package/src/skills-lib/animate/references/easing-and-timing.md

@@ -0,0 +1,105 @@
+# Easing and Timing Reference
+
+## Core Principles
+
+Animations should feel natural and purposeful. The goal is to make interfaces feel responsive without drawing attention to the animation itself.
+
+## Easing Functions
+
+### When to Use Each Easing Type
+
+| Easing | Use Case | Timing |
+|--------|----------|--------|
+| `ease-out` | Elements entering the screen | 200-300ms |
+| `ease-in-out` | Elements moving on screen | 200-300ms |
+| `ease-in` | Elements exiting the screen | 150-200ms |
+| `ease` | Hover effects | 150ms |
+| `linear` | Opacity changes, progress bars | varies |
+
+### Custom Easing Variables
+
+Define these CSS custom properties for consistent animations:
+
+```css
+:root {
+  /* Recommended easing curves */
+  --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);
+  --ease-in-cubic: cubic-bezier(.32, 0, .67, 0);
+
+  /* Spring-like feel */
+  --ease-out-back: cubic-bezier(.34, 1.56, .64, 1);
+}
+```
+
+### Cubic Bezier Explained
+
+`cubic-bezier(x1, y1, x2, y2)` defines a curve with two control points:
+- `(x1, y1)` - First control point (influences start of animation)
+- `(x2, y2)` - Second control point (influences end of animation)
+
+Values > 1 create overshoot effects (like `ease-out-back`).
+
+## Timing Guidelines
+
+### Duration Sweet Spots
+
+- **General animations**: 200-300ms (the sweet spot)
+- **Hover effects**: 150ms
+- **Modal enter**: 200ms
+- **Modal exit**: 150ms (exits should be faster than enters)
+- **Page transitions**: 300-400ms
+- **Micro-interactions**: 100-150ms
+
+### Rules of Thumb
+
+1. **Exits faster than enters**: Exit animations should be ~75% of enter duration
+2. **Smaller elements = faster animations**: Scale duration with element size
+3. **User-initiated = faster response**: Direct actions should feel immediate
+4. **System-initiated = can be slower**: Background transitions can take longer
+
+## Spring Animations
+
+Springs are excellent for interruptible animations and natural-feeling motion.
+
+### Spring Parameters
+
+| Parameter | Effect |
+|-----------|--------|
+| `mass` | Weight of the object (higher = slower, more momentum) |
+| `tension` (stiffness) | Spring tightness (higher = faster, snappier) |
+| `friction` (damping) | Resistance (higher = less oscillation) |
+| `velocity` | Initial speed |
+
+### Framer Motion Spring Config
+
+```tsx
+// Snappy spring (UI elements)
+const snappy = { type: "spring", stiffness: 400, damping: 30 }
+
+// Gentle spring (larger elements)
+const gentle = { type: "spring", stiffness: 200, damping: 20 }
+
+// Bouncy spring (playful interactions)
+const bouncy = { type: "spring", stiffness: 300, damping: 10 }
+```
+
+### Duration-Based Springs (Framer Motion)
+
+```tsx
+// Using duration instead of physics
+const durationSpring = {
+  type: "spring",
+  duration: 0.3,
+  bounce: 0.2  // 0 = no bounce, 1 = max bounce
+}
+```
+
+## When NOT to Animate
+
+- Loading states that block interaction
+- Error messages that need immediate attention
+- Accessibility: respect `prefers-reduced-motion`
+- When animation adds no value to the experience
+- Repeated actions the user performs frequently