@design-ai/cli 4.55.0

package/knowledge/motion/choreography-depth.md

@@ -0,0 +1,297 @@
+<!-- hand-written -->
+---
+title: Motion choreography (multi-element coordination)
+applies_to: [motion, animation, page-transition, complex-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Motion choreography
+
+When multiple elements animate together, they need to be **choreographed** — sequenced, staggered, hierarchical. Random simultaneous motion looks chaotic. This is the floor for orchestrating multiple animations.
+
+## Core principles
+
+### 1. Sequence, don't unison
+
+Don't fire all animations at 0ms. Stagger them.
+
+```
+Bad (unison):
+  All cards: 0ms → fade in over 250ms
+
+Good (staggered):
+  Card 1: 0ms → fade in
+  Card 2: 50ms → fade in
+  Card 3: 100ms → fade in
+  Total: still ~350ms but reads as composed
+```
+
+Stagger 30–80ms per item is the sweet spot. Larger feels glacial; smaller feels simultaneous.
+
+### 2. Establish a primary
+
+When multiple things animate, there's a **lead**. Other elements support.
+
+```
+Hero entrance:
+  - Heading appears first (the lead)
+  - Sub-headline 100ms later
+  - CTAs 200ms later
+  - Visual 300ms later (last; supports the message)
+
+Reading order matches motion order.
+```
+
+### 3. Anchor with a focal point
+
+Animation should originate from a meaningful place:
+- Modal: from center, or from the trigger button (transform-origin)
+- List item entering: from top (new) or bottom (just-added)
+- Drawer: from edge it slides in from
+- Hero CTA: from the primary's position
+
+Random origins read as "AI-generated motion" (the wrong kind).
+
+## Five choreography patterns
+
+### 1. Cascade (waterfall)
+
+Items animate in sequence, like a waterfall.
+
+```
+Card 1 enters at 0ms
+Card 2 enters at 50ms
+Card 3 enters at 100ms
+...
+```
+
+Use for: list reveals, grid fills, multi-step forms.
+
+```ts
+{children.map((c, i) => (
+  <motion.div
+    key={c.id}
+    initial={{ opacity: 0, y: 8 }}
+    animate={{ opacity: 1, y: 0 }}
+    transition={{ delay: i * 0.05, duration: 0.25 }}
+  >
+    {c}
+  </motion.div>
+))}
+```
+
+### 2. FLIP (First, Last, Invert, Play)
+
+When an element changes position (different parent, layout shift), animate the transition smoothly.
+
+```
+1. First: record element's position before change
+2. Last: render new layout (element at new position)
+3. Invert: apply transform that puts element back at "First" position
+4. Play: animate transform to identity (transform: 0)
+
+Result: element appears to smoothly move from old to new position.
+```
+
+Used in:
+- Reordering lists (drag-and-drop result)
+- Layout changes (collapse/expand)
+- Hero / shared-element transitions
+
+Tools that handle FLIP automatically:
+- Framer Motion `layout` prop / `layoutId`
+- React Aria's drag-and-drop
+- Vue's `<transition-group>`
+- View Transitions API (web-native)
+
+### 3. View Transitions API (web-native)
+
+Modern browsers (Chrome 111+, Safari 18+, Edge 111+) ship `document.startViewTransition()`:
+
+```js
+function navigate(newRoute) {
+  if (!document.startViewTransition) {
+    // Fallback: just update
+    updateDOM(newRoute);
+    return;
+  }
+  document.startViewTransition(() => {
+    updateDOM(newRoute);
+  });
+}
+```
+
+Browser handles the cross-fade automatically. Pair with `view-transition-name` CSS for shared elements:
+
+```css
+.product-image {
+  view-transition-name: product-image;
+}
+```
+
+Now navigating from list to detail: the image automatically morphs from list position to detail position.
+
+### 4. Choreographed sequences (storytelling)
+
+A series of coordinated animations that tell a story.
+
+```
+Marketing storyboard:
+  Scene 1 (0-1s): "Sketch your idea" — pencil draws line
+  Scene 2 (1-2s): "Add color" — palette appears, fills shapes
+  Scene 3 (2-3s): "Share with team" — cursors stream in, comments appear
+```
+
+Tools:
+- **Lottie** — designer creates in After Effects, ships as JSON
+- **Rive** — designer creates with state machine, runtime interactive
+- **GSAP timelines** — engineer codes the sequence
+- **CSS keyframes + JS triggers** — for simple sequences
+
+For long sequences (3+ seconds): Lottie or Rive (designer-led).
+For short (< 1s) coordinated: Framer Motion or GSAP (engineer-led).
+
+### 5. Reactive choreography (state machines)
+
+Animations driven by **state**, not duration:
+- Mouse position → cursor effect
+- Scroll position → parallax + reveals
+- Form state → field validation animation
+- Page state → skeleton vs content vs error
+
+Tools:
+- **Rive** state machine (visual, designer-friendly)
+- **XState** + Framer Motion (engineer-friendly)
+- **Spring physics** libraries (react-spring) for natural motion responding to state
+
+## Stagger formulas
+
+| Items | Stagger ms | Total time |
+| --- | --- | --- |
+| 3 | 80ms | 240ms + each item's duration |
+| 5 | 60ms | 300ms |
+| 10 | 40ms | 400ms |
+| 20+ | 20–30ms | 500ms+ (cap; longer is glacial) |
+
+Rule: total animation time of all items shouldn't exceed ~600ms. If it does, you're animating too many items.
+
+## Choreographing exits
+
+Exits are the underdesigned half. Most teams design entrances and forget exits.
+
+```
+Modal open: 250ms ease-out (slow, settle in)
+Modal close: 200ms ease-in (faster, accelerates away)
+
+The exit is faster than entrance — feels right.
+```
+
+For lists:
+- Removed item: slide-out + fade
+- New item appears in the gap: 100–150ms
+
+```ts
+<AnimatePresence mode="popLayout">
+  {items.map(item => (
+    <motion.div
+      key={item.id}
+      layout
+      initial={{ opacity: 0, y: -8 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, x: -100, transition: { duration: 0.2 } }}
+    >
+      {item}
+    </motion.div>
+  ))}
+</AnimatePresence>
+```
+
+## Choreographing across components
+
+Multi-component sequences (e.g., dashboard onboarding):
+
+```
+0ms: Header enters (top-down)
+200ms: Sidebar enters (left-right)
+400ms: Content area starts skeleton
+600ms: Skeleton replaced with real content (cascade)
+```
+
+Tools:
+- Framer Motion `<MotionConfig>` for shared transition defaults
+- GSAP `gsap.timeline()` for explicit time control
+
+## Timing diagrams
+
+For complex sequences, document with a timing diagram:
+
+```
+Time:    0ms   200ms   400ms   600ms   800ms   1000ms
+Header:  ▕━━━━▏
+Side:           ▕━━━━▏
+Skel:                  ▕━━━━━━━━━━━━━━━━━━━━━━▏
+Content:                                       ▕━━━━▏
+```
+
+When designing, sketch this. Helps spot conflicts and pacing issues.
+
+## Performance for choreographed motion
+
+Multiple simultaneous animations × multiple frames per second = expensive.
+
+Rules:
+- Animate `transform` and `opacity` only (GPU layer).
+- Use `will-change: transform` on heavy items (sparingly — kills GPU memory if overused).
+- Batch DOM reads + writes (avoid layout thrashing).
+- For 60+ items: virtualize or fall back to instant.
+
+For Framer Motion: `LazyMotion` + `domAnimation` ships smaller bundle:
+
+```ts
+import { LazyMotion, domAnimation, m } from "framer-motion";
+
+<LazyMotion features={domAnimation}>
+  <m.div ... />
+</LazyMotion>
+```
+
+## Reduced motion in choreographed sequences
+
+For sequences with reduced motion preference:
+- Skip stagger (everything appears together).
+- Skip slide / scale / parallax.
+- Keep cross-fade (opacity is OK).
+- Skip Hero / FLIP transitions (instant layout change).
+
+Don't try to "preserve choreography" — just disable.
+
+## Korean motion language
+
+For Korean fintech / consumer apps:
+- **Toss style**: smooth, decisive, no overshoot. Stagger 50ms typical.
+- **KakaoBank style**: slightly warmer, occasional gentle overshoot. Stagger 60ms.
+- **Naver style**: less choreographed; more direct.
+
+Avoid Western "playful Disney-style" sequencing for Korean financial apps — reads as toy-like.
+
+## Don't
+
+- Don't fire 10+ animations simultaneously without staggering.
+- Don't use 200ms+ stagger (feels glacial).
+- Don't choreograph for the sake of motion. Reduce to what serves the message.
+- Don't animate `width` / `height` / `left` / `top` (layout-triggering, janky).
+- Don't ignore exits.
+- Don't over-spring with bouncy curves on financial / serious surfaces.
+- Don't design choreography that breaks under reduced motion.
+
+## Cross-reference
+
+- [`knowledge/motion/principles.md`](principles.md) — durations + easings
+- [`knowledge/motion/marketing-motion.md`](marketing-motion.md) — landing-page choreography
+- [`knowledge/motion/app-loading-sequences.md`](app-loading-sequences.md) — splash + route transitions
+- [`knowledge/motion/micro-interactions.md`](micro-interactions.md) — single-element motions
+- [`knowledge/motion/motion-tools.md`](motion-tools.md) — Framer Motion / GSAP / Lottie / Rive
+- [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)
+- [Framer Motion docs](https://www.framer.com/motion/)

package/knowledge/motion/marketing-motion.md

@@ -0,0 +1,223 @@
+<!-- hand-written -->
+---
+title: Marketing motion (landing pages, ads, hero animations)
+applies_to: [marketing, landing, hero, ads]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Marketing motion
+
+Motion in marketing differs from motion in product UI. Product motion is functional (navigate, confirm, focus). Marketing motion is **persuasive** — it stops the scroll, reveals the value prop, drives emotional response.
+
+Different rules. This is the floor.
+
+## Three intents
+
+| Intent | Goal |
+| --- | --- |
+| **Stop the scroll** | Catch attention before user bounces |
+| **Reveal value** | Tell the product story through motion |
+| **Anchor brand** | Motion as part of brand recognition |
+
+A marketing animation should hit at least one. Animation that doesn't is decoration — cut it.
+
+## Six marketing motion patterns
+
+### 1. Hero entrance (above-the-fold reveal)
+
+The hero text and visual fade-in / slide-in on page load.
+
+```
+On load:
+0ms — hero hidden
+50ms — sub-headline starts fading in (translateY +12px → 0)
+100ms — headline starts (offset by 50ms)
+250ms — primary CTA appears
+500ms — visual / illustration enters (scale 0.95 → 1 + opacity)
+```
+
+Total budget: 600–800ms. Done.
+
+Don't:
+- Don't make hero entrance > 1s (user is waiting).
+- Don't auto-replay on scroll.
+- Don't entrance from far off-screen (cheesy).
+
+### 2. Scroll-triggered reveals
+
+Sections animate in as user scrolls them into view. The classic landing-page motion pattern.
+
+```
+[scroll position]
+- Section enters viewport at 80% threshold
+- 200ms fade + 16px translateY → 0
+- Stagger child elements (cards, list items) by 50–80ms
+```
+
+Use `IntersectionObserver` (or library like Framer Motion / GSAP ScrollTrigger).
+
+Rules:
+- **Trigger once per element**. Not on every up/down scroll.
+- **Stagger small** (50–80ms). Larger feels slow.
+- **Don't reveal everything**. Body text already-rendered is fine; reserve animation for sections / cards / images.
+
+### 3. Parallax
+
+Background elements move at different speeds than foreground.
+
+```
+foreground: scroll at 1× rate
+background image: scroll at 0.5× rate (slower, "deeper")
+floating shape: scroll at 1.5× rate (faster, "closer")
+```
+
+Implementation: CSS `transform: translateY(var(--scroll))` driven by JS scroll listener, OR `background-attachment: fixed` (limited).
+
+When to use:
+- Storytelling pages with strong visual narrative.
+- Hero sections with depth.
+
+When to skip:
+- Content-heavy sites (parallax distracts from reading).
+- Mobile (most parallax breaks on iOS Safari).
+- Performance-sensitive (parallax requires constant scroll repaints).
+
+### 4. Choreographed sequences (storytelling)
+
+A series of coordinated animations that tell a story. Common in product walkthroughs:
+
+```
+"Sketch your idea" → screen shows pencil drawing
+"Add color" → palette appears, color fills
+"Share with team" → cursors appear, comments stream in
+```
+
+Tools: Lottie / Rive (designer-led), Framer Motion / GSAP (engineer-led).
+
+For Korean fintech: Toss's "money flows from one account to another" animations are canonical examples.
+
+### 5. Hover / cursor-driven
+
+Elements respond to cursor position or hover:
+- Magnetic buttons (button slightly tracks cursor near it)
+- 3D card tilt on cursor (popular 2023+)
+- Cursor effects (custom cursor, trailing dot)
+
+Cool but use sparingly:
+- 3D tilt on every card = performance death.
+- Custom cursors break a11y if wrongly done.
+- Magnetic effects only work on desktop.
+
+### 6. Loop animations / ambient motion
+
+Background animations that loop continuously:
+- Floating geometric shapes
+- Animated gradients
+- Particle systems
+
+Risk: visual noise, performance, distraction. Use ONLY if motion IS part of the brand identity.
+
+## Tools comparison
+
+| Tool | Use | Skill needed |
+| --- | --- | --- |
+| **CSS animations** | Simple entrances, hovers | Low |
+| **Framer Motion** | React-based product motion + marketing | Medium |
+| **GSAP** | Complex sequences, timeline-based | Medium-high |
+| **Lottie** | After Effects → web (designer-led) | Designer + dev |
+| **Rive** | Interactive animations (state-machine) | Designer + dev |
+| **Three.js / WebGL** | 3D scenes | High |
+| **Spline** | 3D scenes (designer-friendly) | Designer-led |
+
+For most marketing sites: Framer Motion + Lottie covers 90%. See [`motion-tools.md`](motion-tools.md) for full comparison.
+
+## Performance budget
+
+Marketing motion runs in browsers across devices. Performance matters:
+
+| Metric | Budget |
+| --- | --- |
+| First Contentful Paint | < 1.8s |
+| Largest Contentful Paint | < 2.5s (don't block on motion) |
+| Cumulative Layout Shift | < 0.1 (motion shouldn't cause layout shift) |
+| Total animations on page | < 10 simultaneously |
+| Animation framerate | 60fps target |
+
+Tips:
+- Animate `transform` and `opacity` only (GPU-composited).
+- Avoid animating `width`, `height`, `top`, `left` (layout-triggering).
+- Lazy-load heavy animations below the fold.
+- Provide static fallbacks for `prefers-reduced-motion`.
+
+## Reduced motion
+
+Critical for marketing — many users have it on:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+But blanket-killing all motion can be too much. Better:
+
+| Animation | When motion reduced |
+| --- | --- |
+| Fade-in entrances | Keep (opacity is fine) |
+| Translate-Y entrances | Convert to instant or pure fade |
+| Parallax | Disable |
+| Scroll-driven sequences | Show all states at once |
+| Loop animations | Pause |
+| Hover tilt | Disable |
+| Auto-play hero video | Show poster image instead |
+
+## Korean marketing motion conventions
+
+Korean fintech / consumer landing pages trend toward:
+- **Toss-style** — minimal, smooth, brand-color-led, restrained
+- **Kakao-style** — playful, character-driven, warmer
+- **Naver-style** — denser, less motion
+
+For most Korean B2C: lean Toss-style — restrained, fast, smooth. Heavy motion reads as foreign / over-designed.
+
+## Brand motion as identity
+
+Some brands have a defined "motion language":
+- Apple: smooth, decisive, rubber-band
+- Stripe: refined, geometric, minimal
+- Linear: fast, snappy, decisive
+- Toss: gentle, calming, money-friendly
+
+Define yours:
+- **Easing curves** (rubber-band? smooth? snappy?)
+- **Duration tier preferences** (fast vs medium)
+- **Choreography style** (staggered? unison? cascading?)
+- **Reaction to interaction** (eager vs reserved)
+
+Document in your brand kit alongside color and typography.
+
+## Common marketing motion mistakes
+
+- **Motion as decoration**, no purpose.
+- **Auto-play heavy video** without poster fallback.
+- **Hero entrance > 1s** — feels slow.
+- **Stagger > 100ms per item** — feels glacial.
+- **Animating layout properties** (width, height) — janky.
+- **No reduced motion** support.
+- **Motion that interferes with reading** (text moving while reading).
+- **Custom cursor that hides the OS cursor** entirely — accessibility break.
+- **Looping motion at 0.5fps** to "save battery" — looks broken.
+
+## Cross-reference
+
+- [`knowledge/motion/principles.md`](principles.md) — duration tiers, easings (foundation)
+- [`knowledge/motion/app-loading-sequences.md`](app-loading-sequences.md) — splash + app load
+- [`knowledge/motion/choreography-depth.md`](choreography-depth.md) — multi-element coordination
+- [`knowledge/motion/motion-tools.md`](motion-tools.md) — tool comparison
+- [`knowledge/patterns/landing-hero-design.md`](../patterns/landing-hero-design.md) — hero strategy
+- [`knowledge/patterns/landing-page-patterns.md`](../patterns/landing-page-patterns.md)