Animation & Motion Design

Quick Reference

rules/motion-layout.md

rules/motion-gestures.md

rules/motion-exit.md

rules/view-transitions-api.md

rules/motion-accessibility.md

rules/motion-performance.md

Decision Table — Motion vs View Transitions API

Quick Start

Motion — Component Animation

import { motion, AnimatePresence } from "motion/react"

const fadeInUp = {
  initial: { opacity: 0, y: 20 },
  animate: { opacity: 1, y: 0 },
  exit: { opacity: 0, y: -10 },
  transition: { type: "spring", stiffness: 300, damping: 24 },
}

function Card({ item }: { item: Item }) {
  return (
    <motion.div {...fadeInUp} layout layoutId={item.id}>
      {item.content}
    </motion.div>
  )
}

function CardList({ items }: { items: Item[] }) {
  return (
    <AnimatePresence mode="wait">
      {items.map((item) => (
        <Card key={item.id} item={item} />
      ))}
    </AnimatePresence>
  )
}

View Transitions API — Page Navigation

// React Router v7+ with View Transitions
import { Link, useNavigate } from "react-router"

function NavLink({ to, children }: { to: string; children: React.ReactNode }) {
  return <Link to={to} viewTransition>{children}</Link>
}

// CSS for the transition
// ::view-transition-old(root) { animation: fade-out 200ms ease; }
// ::view-transition-new(root) { animation: fade-in 200ms ease; }

Motion — Accessible by Default

import { useReducedMotion } from "motion/react"

function AnimatedComponent() {
  const shouldReduceMotion = useReducedMotion()

  return (
    <motion.div
      animate={{ x: 100 }}
      transition={shouldReduceMotion
        ? { duration: 0 }
        : { type: "spring", stiffness: 300, damping: 24 }
      }
    />
  )
}

Rule Details

Layout Animations (Motion)

layout

layoutId

Load:

rules/motion-layout.md

Gesture Interactions (Motion)

Load:

rules/motion-gestures.md

Exit Animations (Motion)

Load:

rules/motion-exit.md

View Transitions API

document.startViewTransition()

Load:

rules/view-transitions-api.md

Motion Accessibility

Load:

rules/motion-accessibility.md

Motion Performance

Load:

rules/motion-performance.md

Key Principles

1. 60fps or nothing — Only animate

   transform

   and

   opacity

   (composite properties). Never animate

   width

   ,

   height

   ,

   top

   , or

   left

   .
2. Centralized presets — Define animation variants in a shared file, not inline on every component.
3. AnimatePresence for exits — React unmounts instantly; wrap with AnimatePresence to animate out.
4. Spring over duration — Springs feel natural and are interruptible. Use

   stiffness

   /

   damping

   , not

   duration

   .
5. Respect user preferences — Always check

   prefers-reduced-motion

   and provide instant alternatives.

Performance Budget

PerformanceObserver

Anti-Patterns (FORBIDDEN)

• Animating layout properties — Never animate

  width

  ,

  height

  ,

  margin

  ,

  padding

  directly. Use

  transform: scale()

  instead.
• Missing AnimatePresence — Components unmount instantly without it; exit animations are silently lost.
• Ignoring prefers-reduced-motion — Causes vestibular disorders for ~35% of users with motion sensitivity.
• Inline transition objects — Creates new objects every render, breaking React memoization.
• duration-based springs — Motion springs use

  stiffness

  /

  damping

  , not

  duration

  . Mixing causes unexpected behavior.
• Synchronous startViewTransition — Always await or handle the promise from

  document.startViewTransition()

  .

Detailed Documentation

Related Skills

• ork:ui-components

  — shadcn/ui component patterns and CVA variants

• ork:responsive-patterns

  — Responsive layout and container query patterns

• ork:performance

  — Core Web Vitals and runtime performance optimization

• ork:accessibility

  — WCAG compliance, ARIA patterns, screen reader support