@design-ai/cli 4.55.0

package/knowledge/motion/micro-interactions.md

@@ -0,0 +1,266 @@
+<!-- hand-written -->
+---
+title: Micro-interactions (the small motions that make UI feel alive)
+applies_to: [ui, motion, interactive-elements]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Micro-interactions
+
+The < 200ms motions that respond to user input — button press, switch toggle, focus ring, hover. They're invisible when right; janky when wrong. This is the floor.
+
+## What is a micro-interaction
+
+A motion that:
+- Lasts < 200ms
+- Responds directly to user action
+- Confirms an event happened
+- Doesn't navigate or change state at the system level
+
+Examples: button scale-down on press, switch toggle, checkbox checkmark draw-in, hover glow, focus ring expand, tooltip fade-in, ripple, chip dismiss.
+
+## Five categories
+
+### 1. Press feedback
+
+User taps / clicks. The element confirms with a brief visual reaction.
+
+| Pattern | Use |
+| --- | --- |
+| **Scale 0.97** + opacity 0.85 | iOS-feeling, default for buttons |
+| **Ripple** (Material) | Material-aligned products |
+| **Subtle bg shift** (10% darker) | Calm, business-feeling |
+| **Border emphasis** | Buttons with no fill |
+| **Shadow lift** then settle | Card-like elements |
+
+Duration: 100–150ms. `ease-out` going down, `ease-out` returning.
+
+```css
+.button {
+  transition: transform 100ms ease-out, opacity 100ms ease-out;
+}
+.button:active {
+  transform: scale(0.97);
+  opacity: 0.85;
+}
+```
+
+### 2. State change confirmation
+
+A binary state changes (toggle, checkbox, radio). Show the change physically.
+
+```
+Switch: 200ms ease-out track color + thumb translateX
+Checkbox: 100ms checkmark draw-in (SVG path with stroke-dashoffset)
+Radio: 100ms scale 0 → 1 of inner dot
+Star rating: 150ms scale 0.8 → 1.1 → 1 (slight overshoot for satisfaction)
+```
+
+The "physical satisfaction" of the toggle matters. Don't strip the motion.
+
+### 3. Hover (desktop only)
+
+| Element | Hover motion |
+| --- | --- |
+| Button | bg darken 5–8%, no scale |
+| Card (interactive) | shadow deepen, optional 1–2px translateY -1 |
+| Link | underline appears |
+| Icon button | bg circle appears (40px round) |
+| Checkbox | border color emphasis |
+
+Duration: 100–150ms. Apply `@media (hover: hover)` so touch devices skip.
+
+### 4. Focus ring
+
+When element receives keyboard focus.
+
+```css
+.button:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+  transition: outline-offset 100ms ease-out;
+}
+```
+
+Optional: animate ring scale on appearance. But mostly: just appear instantly.
+
+`:focus-visible` (modern browsers) keeps focus rings on keyboard nav, hides on mouse click. Keyboard users get them; mouse users don't.
+
+### 5. Loading / progress micro-states
+
+Inside a button or input, motion reflects async work:
+
+| Pattern | Use |
+| --- | --- |
+| Spinner inside button | Loading after click |
+| Progress bar inline | File upload row |
+| Pulse on indicator | "live" / refreshing |
+| Shimmer | Skeleton loading |
+
+Duration: continuous loop until done. Spinner: 1000ms linear rotate. Shimmer: 1500ms linear sweep.
+
+## The four laws of micro-interactions
+
+### Law 1: Be fast
+
+< 200ms feels instant. > 300ms feels sluggish. > 500ms is broken.
+
+### Law 2: Be functional
+
+Every micro-interaction confirms something:
+- Button press → "I registered your tap"
+- Switch → "I changed the state"
+- Focus ring → "You're here now"
+
+If a motion communicates nothing, cut it.
+
+### Law 3: Match the input
+
+| Input source | Motion type |
+| --- | --- |
+| Mouse click | Subtle (mouse is precise) |
+| Touch | Pronounced (finger needs feedback) |
+| Keyboard | Focus ring (visual only) |
+| Voice | Visual + audio (TBD pattern) |
+
+Touch needs more motion than mouse — fingers cover the button on tap. The press feedback is the only confirmation.
+
+### Law 4: Stagger redundancy
+
+If a button changes 3 things on click (color, scale, shadow), don't fire all at exactly 0ms. Stagger by 30–50ms for a more natural sequence.
+
+```
+Press:
+  0ms — scale 1 → 0.97
+  20ms — opacity 1 → 0.85
+  40ms — shadow drops
+```
+
+Tiny stagger; enough that the eye reads "physical."
+
+## Reduced motion
+
+For micro-interactions:
+
+| Pattern | Reduced-motion alternative |
+| --- | --- |
+| Press scale | Instant bg color shift |
+| Switch toggle | Instant state change |
+| Checkbox draw | Instant checkmark |
+| Hover lift | No motion; rely on color + cursor |
+| Spinner | Static "loading" text |
+| Shimmer | Static skeleton, no animation |
+
+Skip motion, keep meaning.
+
+## The animation timing function — fine-tuning
+
+Most micro-interactions use `ease-out` (decelerate to rest). For finer control:
+
+| Curve | Feel | Use |
+| --- | --- | --- |
+| `cubic-bezier(0, 0, 0.2, 1)` | Standard ease-out | Default |
+| `cubic-bezier(0.4, 0, 0.2, 1)` | Material standard | Material-aligned products |
+| `cubic-bezier(0.34, 1.56, 0.64, 1)` | Slight overshoot (back-out) | Toggle satisfaction, checkmark |
+| `cubic-bezier(0.68, -0.55, 0.27, 1.55)` | Big bounce | Avoid for UI; OK for celebration |
+| `linear` | Constant | Spinners, progress bars |
+
+For micro-interactions: stick with the first three. Bouncier curves feel toy-like in serious products.
+
+## Sound and haptic
+
+Mobile micro-interactions can pair with haptic:
+- iOS: `UIImpactFeedbackGenerator` (light, medium, heavy)
+- Android: `Vibrator.vibrate(pattern)`
+- React Native: `Haptics.impactAsync()`
+
+When to add haptic:
+- Long-press confirmation (helps users know they pressed long enough)
+- Switch / toggle (physical satisfaction)
+- Pull-to-refresh activation
+- Drag-and-drop pickup
+
+When to skip:
+- Every button press (excessive)
+- Settings or read-only screens (annoying)
+
+Sound: rarely appropriate in product UI. Reserve for games, accessibility cues, video calls.
+
+## Korean fintech micro-interactions
+
+Toss-style: smooth, calm, money-friendly.
+- Press: 0.97 scale + 0.85 opacity (gentle).
+- Toggle: 250ms (slightly slower than typical, "deliberate").
+- Number ticker for amounts: 300ms count-up.
+- Sub-200ms haptic for transfer confirmation.
+
+KakaoBank-style: warmer, slightly more pronounced.
+- Press: 0.95 scale (more visible).
+- Checkmark: with slight bounce.
+- Coin / money icons may rotate playfully in success states.
+
+For Korean banking specifically: don't over-do motion. Users associate restraint with trustworthiness.
+
+## Button micro-interaction spec (canonical)
+
+```css
+.button {
+  background: var(--color-primary-default);
+  transition:
+    background-color 150ms ease-out,
+    transform 100ms ease-out,
+    opacity 100ms ease-out,
+    box-shadow 150ms ease-out;
+}
+
+@media (hover: hover) {
+  .button:hover {
+    background: var(--color-primary-hover);
+    box-shadow: var(--shadow-card);
+  }
+}
+
+.button:active {
+  background: var(--color-primary-active);
+  transform: scale(0.97);
+  opacity: 0.85;
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .button {
+    transition: background-color 0ms;
+    transform: none;
+  }
+  .button:active {
+    transform: none;
+  }
+}
+```
+
+## Common micro-interaction mistakes
+
+- **Over 200ms** — too slow.
+- **No press feedback** — touch users wonder if tap registered.
+- **Hover-only feedback** — fails for touch.
+- **All elements animating equally** — no hierarchy.
+- **Bounce/spring on serious surfaces** (banking, government) — toy-like.
+- **Same motion for press and hover** — should differ.
+- **Animation interferes with rapid tapping** — rapid taps shouldn't queue up animations.
+- **Spinner inside disabled button** — looks broken.
+- **No reduced-motion fallback**.
+
+## Cross-reference
+
+- [`knowledge/motion/principles.md`](principles.md) — duration tiers, easings
+- [`knowledge/motion/choreography-depth.md`](choreography-depth.md) — coordinating multiple micro-interactions
+- [`knowledge/motion/motion-tools.md`](motion-tools.md) — when CSS vs Framer Motion
+- [`knowledge/a11y/keyboard-and-focus.md`](../a11y/keyboard-and-focus.md) — focus indicator rules
+- [`examples/component-button.md`](../../examples/component-button.md) — Button spec with full state machine
+- [`examples/component-form-controls.md`](../../examples/component-form-controls.md) — Switch/Checkbox/Radio motions

package/knowledge/motion/motion-tools.md

@@ -0,0 +1,281 @@
+<!-- hand-written -->
+---
+title: Motion tools comparison
+applies_to: [motion, animation, tools]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Motion tools comparison
+
+Designers and developers split the work of motion. The tool depends on who creates and how complex.
+
+## Decision tree
+
+```
+Is the motion < 200ms and triggered by user input?
+  ├── Yes → CSS transition / animation
+  └── No
+      ├── Designer-led, complex sequence?
+      │   ├── Yes, interactive → Rive
+      │   └── Yes, non-interactive → Lottie
+      └── Engineer-led, in React?
+          ├── Simple → Framer Motion
+          ├── Timeline-based, complex → GSAP
+          └── Physics / springs → react-spring
+```
+
+## Six tools, when to use each
+
+### 1. CSS animations / transitions
+
+**Use for**: hover, press feedback, state changes, simple entrances.
+
+Built into the browser. No bundle cost. Universally supported.
+
+```css
+.button {
+  transition: transform 100ms ease-out, opacity 100ms ease-out;
+}
+.button:active {
+  transform: scale(0.97);
+  opacity: 0.85;
+}
+
+@keyframes shimmer {
+  0%   { background-position: -200% 0; }
+  100% { background-position: 200% 0; }
+}
+```
+
+Limitations:
+- No JS-driven control (can't pause / scrub / sequence imperatively).
+- Limited to single elements (no choreographing many).
+- No state-machine animations.
+
+For 80% of micro-interactions: CSS is the right answer.
+
+### 2. Framer Motion (React)
+
+**Use for**: React apps. Component entrances, page transitions, shared elements (`layoutId`), choreographed sequences.
+
+```tsx
+import { motion, AnimatePresence } from "framer-motion";
+
+<motion.div
+  initial={{ opacity: 0, y: 8 }}
+  animate={{ opacity: 1, y: 0 }}
+  exit={{ opacity: 0 }}
+  transition={{ duration: 0.2, ease: "easeOut" }}
+>
+  Content
+</motion.div>
+```
+
+Strengths:
+- React-native API (declarative).
+- Layout animations (`layout` prop, FLIP technique built-in).
+- Shared element transitions (`layoutId`).
+- Drag, gesture support.
+- Variants (orchestrate parent → children).
+- AnimatePresence for exits.
+
+Bundle cost: ~30 kB gz. Use `LazyMotion` + `domAnimation` to slim to ~7 kB for simple needs.
+
+When NOT to use:
+- Non-React apps.
+- Simple CSS hovers (overkill).
+- Timeline-heavy sequences (GSAP is better).
+
+### 3. GSAP (GreenSock)
+
+**Use for**: complex marketing sequences, scroll-triggered animations, timeline-based choreography. Framework-agnostic.
+
+```js
+gsap.timeline()
+  .from(".hero-headline", { y: 40, opacity: 0, duration: 0.6 })
+  .from(".hero-sub", { y: 20, opacity: 0, duration: 0.5 }, "-=0.4")
+  .from(".hero-cta", { scale: 0.9, opacity: 0, duration: 0.4 }, "-=0.3")
+  .from(".hero-visual", { x: 80, opacity: 0, duration: 0.7 }, "-=0.5");
+```
+
+Strengths:
+- **ScrollTrigger** plugin — best-in-class for scroll-driven motion.
+- **Timeline** — precise control over sequence timing.
+- **Performance** — heavily optimized, 60fps on complex scenes.
+- Framework-agnostic (works in React, Vue, vanilla, etc.).
+
+License: MIT for non-business use; **paid for commercial use** of certain plugins (ScrollTrigger, MorphSVG, etc.). Check current pricing.
+
+Bundle: 30–60 kB depending on plugins.
+
+When NOT to use:
+- Simple CSS fades (overkill).
+- Pure micro-interactions (CSS is faster).
+
+### 4. Lottie
+
+**Use for**: designer-created animations exported from After Effects, used as JSON.
+
+```tsx
+import Lottie from "lottie-react";
+import animationData from "./checkmark-success.json";
+
+<Lottie animationData={animationData} loop={false} />
+```
+
+Workflow:
+1. Designer animates in After Effects.
+2. Export with [Bodymovin plugin](https://aescripts.com/bodymovin/) → JSON.
+3. Engineer drops JSON into runtime (React, RN, iOS, Android, web).
+
+Strengths:
+- **Designer-led** — designers create motion in their familiar tool.
+- **Cross-platform** — same JSON runs on web, iOS, Android, RN.
+- **Vector-based** — scales to any size cleanly.
+- Best for: brand logos animated, success / error states with motion, hero illustrations.
+
+When NOT to use:
+- Interactive animations (Lottie can play / pause / scrub but not state-machine — use Rive instead).
+- Animations that should respond to user input (use Rive).
+- Tiny micro-interactions (overkill; CSS faster).
+
+Bundle: lottie-web is ~150 kB. Use `lottie-react-light` (~50 kB) if you don't need all features.
+
+### 5. Rive
+
+**Use for**: interactive animations with state machines. Designer + engineer collaborate.
+
+```tsx
+import { useRive } from "@rive-app/react-canvas";
+
+function HeartButton() {
+  const { rive, RiveComponent } = useRive({
+    src: "/animations/heart.riv",
+    stateMachines: "Like Button",
+    autoplay: true,
+  });
+
+  return (
+    <button onClick={() => rive?.fireState("Like Button", "Click")}>
+      <RiveComponent />
+    </button>
+  );
+}
+```
+
+Strengths:
+- **State machines** — animations respond to events / inputs.
+- **Smaller files** than Lottie (binary format).
+- **Designer-friendly** tool (rive.app).
+- **Cross-platform**: web, iOS, Android, RN, Flutter, Unity, Unreal.
+
+Best for:
+- Interactive characters (mascots that react).
+- Button states (idle → hover → press → success).
+- Onboarding flow visuals.
+- Game UI (character emotes, etc.).
+
+When NOT to use:
+- Static animation clips (Lottie is fine).
+- Design-system-internal motion (CSS / Framer Motion fits closer to code).
+
+Bundle: ~150 kB runtime.
+
+### 6. react-spring (React)
+
+**Use for**: physics-based motion that responds to user input naturally.
+
+```tsx
+import { useSpring, animated } from "@react-spring/web";
+
+function Card() {
+  const styles = useSpring({
+    from: { scale: 0.9, opacity: 0 },
+    to: { scale: 1, opacity: 1 },
+    config: { tension: 280, friction: 60 },
+  });
+
+  return <animated.div style={styles}>...</animated.div>;
+}
+```
+
+Strengths:
+- **Spring physics** — natural feeling motion (no fixed durations).
+- **Imperative + declarative APIs**.
+- **Smaller** than Framer Motion (~17 kB).
+
+When NOT to use:
+- You don't need spring physics — Framer Motion is more featureful.
+- You're outside React.
+
+Bundle: ~17 kB.
+
+## When to pick which (decision matrix)
+
+| Need | Tool |
+| --- | --- |
+| Hover, press, focus rings | CSS |
+| Loading shimmers | CSS |
+| Page transitions in React | Framer Motion |
+| Modal entrances in React | Framer Motion |
+| List re-orders (FLIP) | Framer Motion `layout` prop |
+| Hero / shared-element morph | Framer Motion `layoutId` OR View Transitions API |
+| Scroll-driven parallax | GSAP ScrollTrigger |
+| Marketing storyboard (3+ second sequence) | GSAP timeline OR Lottie |
+| Brand-led illustrated success state | Lottie |
+| Interactive mascot / character | Rive |
+| Onboarding visuals that react | Rive |
+| Drag-and-drop with physics | react-spring or Framer Motion |
+| Cross-platform (web + iOS + Android) | Lottie or Rive |
+
+## Performance comparison
+
+| Tool | First load | Per-animation cost |
+| --- | --- | --- |
+| CSS | 0 kB | Minimal (GPU-composited) |
+| Framer Motion | 7–30 kB gz | Low (DOM + transforms) |
+| GSAP | 30–60 kB gz | Low (highly optimized) |
+| Lottie | 50–150 kB | Medium (canvas / SVG rendering) |
+| Rive | ~150 kB | Low (canvas, optimized) |
+| react-spring | 17 kB | Low |
+
+For most apps: CSS + Framer Motion ≈ 20-40 kB total motion budget. Don't add Lottie / Rive unless designer-created animation justifies it.
+
+## Korean / Toss-style preference
+
+Toss / KakaoBank-style apps often use:
+- CSS for micro-interactions
+- Framer Motion for app transitions
+- Lottie for brand moments (success animations, money-flow demos)
+- Rarely GSAP (less common in Korean tech stacks)
+
+## Reduced motion handling
+
+| Tool | Reduced-motion support |
+| --- | --- |
+| CSS | Native via `@media (prefers-reduced-motion: reduce)` |
+| Framer Motion | `useReducedMotion()` hook |
+| GSAP | Manual: check `matchMedia("(prefers-reduced-motion)")` and disable timelines |
+| Lottie | Pause / show single frame |
+| Rive | Pause state machine; show "rest" state |
+
+Implement always. Don't ship without it.
+
+## Don't
+
+- Don't load Lottie just to do a fade-in.
+- Don't import Framer Motion for one CSS-doable hover.
+- Don't ship 4 different motion libraries in one app.
+- Don't auto-play Lottie / Rive for purely decorative effect (battery drain).
+- Don't use library-specific easings without exposing them as tokens.
+
+## Cross-reference
+
+- [`knowledge/motion/principles.md`](principles.md) — fundamentals
+- [`knowledge/motion/micro-interactions.md`](micro-interactions.md) — when CSS is enough
+- [`knowledge/motion/marketing-motion.md`](marketing-motion.md) — when GSAP is right
+- [`knowledge/motion/app-loading-sequences.md`](app-loading-sequences.md) — Framer Motion patterns
+- [`knowledge/motion/choreography-depth.md`](choreography-depth.md) — multi-element coordination
+- [`examples/component-lottie-player.md`](../../examples/component-lottie-player.md) — Lottie integration spec

package/knowledge/motion/principles.md

@@ -0,0 +1,126 @@
+<!-- hand-written -->
+---
+title: Motion principles for product UI
+applies_to: [web, mobile, all-ui]
+version: 1.0.0
+last_updated: 2026-05
+stability: stable
+---
+
+# Motion principles for product UI
+
+Motion in product UI is functional, not decorative. Every animation should answer one of: *Where did this come from? Where is it going? What just happened? What can I do now?*
+
+If an animation answers none of those, cut it.
+
+## The three duration tiers
+
+| Tier | Duration | Use |
+| --- | --- | --- |
+| **Fast** | 100–150 ms | Micro-interactions: hover, focus ring, button press, ripple, switch toggle, checkbox, simple state changes within a component. |
+| **Default** | 200–300 ms | Component-level transitions: drawer slide, modal fade-in, tooltip, dropdown, accordion expand, page transition (within an SPA). |
+| **Slow** | 400–600 ms | Hero/storytelling moments only: celebrating a completed action, full-screen welcome, large card flip in onboarding. |
+
+> Above 600 ms, users perceive the system as slow. Reserve for genuinely emotional moments or intentional delays.
+
+## Easing curves
+
+Pick a small set of named curves. Don't author one-off `cubic-bezier()` per animation.
+
+| Token | cubic-bezier | Feel | Use |
+| --- | --- | --- | --- |
+| `ease-out` | `cubic-bezier(0, 0, 0.2, 1)` | starts fast, decelerates | **Default for entrances** — element settles into place |
+| `ease-in` | `cubic-bezier(0.4, 0, 1, 1)` | accelerates, snaps off | **Default for exits** — element accelerates away |
+| `ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | symmetric | Position changes within view (e.g., reorder, accordion height) |
+| `emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | Material 3 style — strong start, slow end | Hero entrances, primary CTA reveal |
+| `bounce` | `cubic-bezier(0.34, 1.56, 0.64, 1)` | overshoot | **Use rarely** — celebratory micro-moments only |
+| `linear` | `linear` | constant | progress bars, spinners, anything that should not "feel" elastic |
+
+**Do not** ship custom-named curves like `wobble`, `whoosh`, `pop` unless you have a brand-driven motion language and a designer who maintains it.
+
+Source for emphasized curves: Material 3 motion (https://m3.material.io/styles/motion/easing-and-duration). Ant Design uses `cubic-bezier(0.215, 0.61, 0.355, 1)` for `motionEaseOut` — also good.
+
+## Choreography (multi-element transitions)
+
+When several elements animate together:
+
+1. **Sequence, don't overlap chaos**. A list reveal: first item starts at 0 ms, each subsequent at +30 ms (stagger). Total duration ≤ 400 ms even with 10 items.
+2. **Stack hierarchy**. The most important element animates first (or last — for emphasis). Don't animate everything in unison; one anchor point + supporting elements.
+3. **Match-move on transitions**. Element A turns into element B (e.g., FAB expands into modal). Use FLIP technique or shared element transitions (CSS View Transitions API in 2024+).
+
+## Reduced motion
+
+WCAG 2.3.3 (AAA) and platform conventions:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+But blanket-killing all motion is too aggressive. Better:
+
+- **Keep**: state changes (color shift, opacity 0→1) without movement.
+- **Drop**: spring/bounce, parallax, hero auto-play, scroll-jacking, anything that translates >20px.
+- **Replace**: heavy transitions with instant state changes.
+
+Audit every animation for reduced-motion behavior. The system either respects user preference or it fails AA.
+
+## Performance budget
+
+| Animated property | Cost | Use when |
+| --- | --- | --- |
+| `transform` (translate, scale, rotate) | **cheap** — GPU-composited | first choice, almost always |
+| `opacity` | cheap | first choice |
+| `filter` (blur, brightness) | medium | sparingly, not on large surfaces |
+| `width` / `height` | **expensive** — triggers layout | avoid; use `transform: scale` |
+| `top` / `left` | **expensive** — triggers layout | avoid; use `transform: translate` |
+| `box-shadow` | medium-expensive | OK for hover, avoid for keyframe loops |
+| `background-color` | cheap | yes |
+
+Aim for **60fps**. If a transition stutters on a mid-range Android device, simplify it.
+
+## Common animations and their specs
+
+| Pattern | Duration | Easing | Property |
+| --- | --- | --- | --- |
+| Button hover | 150 ms | `ease-out` | `background-color` |
+| Button press | 100 ms | `ease-out` | `transform: scale(0.97)` |
+| Focus ring | 0 ms (instant) | — | — |
+| Modal fade-in | 200 ms | `ease-out` | `opacity 0→1`, `transform: translateY(8px)→0` |
+| Drawer slide-in | 300 ms | `ease-out` | `transform: translateX(±100%)→0` |
+| Drawer slide-out | 250 ms | `ease-in` | reverse |
+| Tooltip appear | 100 ms (300 ms delay) | `ease-out` | `opacity`, slight `scale 0.95→1` |
+| Toast enter | 250 ms | `ease-out` | `transform: translateY(100%)→0`, opacity |
+| Toast auto-dismiss | 200 ms (after 4–5s linger) | `ease-in` | reverse |
+| Accordion expand | 250 ms | `ease-in-out` | `height: 0→auto` (actually animate `grid-template-rows` 0fr→1fr or use FLIP) |
+| Tab indicator slide | 200 ms | `ease-out` | `transform: translateX` |
+| Page transition (SPA) | 200–300 ms | `ease-out` | `opacity` only — avoid horizontal slide |
+| List item enter | 200 ms (30 ms stagger) | `ease-out` | `opacity 0→1`, `translateY(8px)→0` |
+| Skeleton shimmer | 1500 ms loop | `linear` | `background-position` |
+| Spinner rotation | 1000 ms loop | `linear` | `transform: rotate` |
+| Form error shake | 400 ms | `ease-in-out` | `transform: translateX` (4 cycles) — **rarely; use color/border instead** |
+
+## Anti-patterns
+
+- **Auto-playing hero video without pause control**: WCAG fail. Always provide pause and respect reduced-motion.
+- **Long entrance animations on every page load**: 400+ ms transitions every navigation feel sluggish. Reserve for first-load or rare transitions.
+- **Bouncy / springy on serious surfaces**: a banking app with bouncy delete confirmations reads as toy-like.
+- **Decorative motion on focused work surfaces**: the data table doesn't need fade-ins on every cell.
+- **Motion as the only feedback**: a button that wiggles to indicate error but doesn't change color fails for users with reduced motion. Color, copy, and motion together.
+
+## Reference values from upstream systems
+
+- **Material 3**: short1 50ms, short2 100ms, short3 150ms, short4 200ms, medium1 250ms, medium2 300ms, medium3 350ms, medium4 400ms, long1 450ms, long2 500ms, long3 550ms, long4 600ms.
+- **Ant Design**: `motionUnit 0.1` (100ms base), most transitions `0.2–0.3s`. Easings in [knowledge/design-tokens/ant-design.md](../design-tokens/ant-design.md).
+- **iOS HIG**: 0.35s default for most transitions, 0.5s for cross-fade.
+
+## Cross-reference
+
+- [knowledge/design-tokens/ant-design.md](../design-tokens/ant-design.md) — Ant's motion easings as concrete cubic-bezier values
+- [knowledge/a11y/keyboard-and-focus.md](../a11y/keyboard-and-focus.md) — focus must not depend on motion