Communitygithub.com

モーションシステム v4.2(React/Next.js向け本番UIモーション)

React/Next.jsのための本番環境対応UIモーションシステムです。アニメーション、トランジション、モーションパターンの実装に使用します。

Next.js向け本番UIモーション) とは?

このスキルは、React / Next.jsアプリケーション向けに設計された、本番環境対応のUIモーションシステム(v4.2)です。パフォーマンス、アクセシビリティ、ユーザビリティに焦点を当てており、単なる装飾ではなく、ユーザーの注意誘導、状態の伝達、空間的な連続性の維持を目的としています。サポートするプラットフォームは `motion/react`(最新パッケージ)と `framer-motion`(レガシー)の2系統で、両者の混在は禁止されています。SKILL.mdでは、モーショントークン(duration、easing、distance)の定義、パフォーマンスルール(transform と opacity のみ安全)、デバイス適応(低スペック端末ではアニメーション時間を短縮)、アクセシビリティ(useReducedMotion と CSS メディアクエリ)、アーキテクチャパターン(AnimatePresence の mode 指定、layoutId による共有要素トランジションなど)を詳細に解説しています。デバッグチェックリストやアンチパターン(レイアウトプロパティのアニメーション、無限アニメーション、アクセシビリティ無視など)も含まれており、開発者が実践的なモーション設計を即座に行えるよう支援します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/503496348-ops/mischief-production/tree/HEAD/skills/ecc-motion-ui

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

モーションシステム v4.2

React / Next.js 向けの本番環境対応 UI モーションシステム。

パフォーマンス、アクセシビリティ、ユーザビリティ に重点を置いています。装飾ではありません。

使用するタイミング

このモーションシステムは、以下の目的でモーションを使用する場合に使用します。

  • 注意を誘導する(例:オンボーディング、主要なアクション)
  • 状態を伝達する(ローディング、成功、エラー、トランジション)
  • 空間的な連続性を維持する(レイアウト変更、ナビゲーション)

適切なシナリオ

  • インタラクティブコンポーネント(ボタン、モーダル、メニュー)
  • 状態トランジション(ローディング→ロード完了、開く→閉じる)
  • ナビゲーションとレイアウトの連続性(共有要素、クロスフェード)

考慮事項

  • アクセシビリティ: 常に動きの抑制をサポートする
  • デバイス適応: 低スペック端末に合わせて調整する
  • パフォーマンスのトレードオフ: 視覚的な滑らかさよりも応答性を優先する

モーションを使用すべきでない場合

  • 純粋に装飾的な場合
  • ユーザビリティや明瞭性が低下する場合
  • パフォーマンスに悪影響を及ぼす場合

仕組み

基本原則

モーションは以下の目的を果たす必要があります。

  • 注意を誘導する
  • 状態を伝達する
  • 空間的な連続性を維持する

いずれも満たさない場合は削除します。


インストール

npm install motion

バージョン

  • motion/react - 現在の Motion for React プロジェクトのデフォルト(パッケージ: motion)
  • framer-motion - 依然として Framer Motion に依存しているプロジェクト向けのレガシーインポートパス

混在させないでください。 混在すると、内部スケジューラが競合し、AnimatePresence コンテキストが壊れます。一方のパッケージのコンポーネントは、他方のパッケージのコンポーネントと終了アニメーションを連携できなくなります。

プロジェクトで使用されているバージョンを確認するには:

cat package.json | grep -E '"motion"|"framer-motion"'

常に1つのソースから一貫してインポートします:

// 正しい(最新)
import { motion, AnimatePresence } from "motion/react"

// 正しい(レガシー)
import { motion, AnimatePresence } from "framer-motion"

// 同じプロジェクトで両方を混在させない

モーショントークン

// motionTokens.ts
export const motionTokens = {
  duration: {
    fast: 0.18,
    normal: 0.35,
    slow: 0.6
  },
  // これらを transition オブジェクト内の `ease` 値として使用:
  // transition={{ duration: motionTokens.duration.normal, ease: motionTokens.easing.smooth }}
  easing: {
    smooth: [0.22, 1, 0.36, 1] as [number, number, number, number],
    sharp:  [0.4,  0, 0.2, 1] as [number, number, number, number]
  },
  distance: {
    sm: 8,
    md: 16,
    lg: 24
  }
}

使用例:

import { motionTokens } from "@/lib/motionTokens"

<motion.div
  initial={{ opacity: 0, y: motionTokens.distance.md }}
  animate={{ opacity: 1, y: 0 }}
  transition={{
    duration: motionTokens.duration.normal,
    ease: motionTokens.easing.smooth
  }}
/>

パフォーマンスルール

安全

  • transform
  • opacity

避けるべきもの

  • width / height
  • top / left

ルール: 応答性 > 滑らかさ


デバイス適応

ヒューリスティックは、CPUコア数 と 利用可能メモリを組み合わせて、より信頼性の高いシグナルを得ます。deviceMemory は Chrome/Android で使用可能です。フォールバックは Safari と Firefox をカバーします。

const isLowEnd =
  typeof navigator !== "undefined" && (
    // 低メモリ(Chrome/Android のみ。それ以外は undefined → 高性能と判断)
    (navigator.deviceMemory !== undefined && navigator.deviceMemory <= 2) ||
    // コア数が少ない かつ メモリAPIがない(Safari/Firefox の低スペックハードウェアをカバー)
    (navigator.deviceMemory === undefined && navigator.hardwareConcurrency <= 4)
  )

const duration = isLowEnd ? 0.2 : 0.4

アクセシビリティ

JS(useReducedMotion)

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

export function FadeIn() {
  const reduce = useReducedMotion()

  return (
    <motion.div
      initial={{ opacity: 0, y: reduce ? 0 : 24 }}
      animate={{ opacity: 1, y: 0 }}
    />
  )
}

CSS

@media (prefers-reduced-motion: reduce) {
  .motion-safe-transition {
    transition: opacity 0.2s;
  }

  .motion-reduce-transform {
    transform: none !important;
  }
}

Tailwind

<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>

アーキテクチャとパターン

コアパターン

シナリオパターン
ホバーフィードバックwhileHover
タップ/プレスフィードバックwhileTap
スクロールに応じた表示whileInView
スクロール連動値useScroll + useTransform
条件付きマウント/アンマウントAnimatePresence
小さなレイアウトシフト(単一要素、~300px未満の変化)layout プロパティ
大きなレイアウトシフトまたは全ページリフローlayout は避ける。代わりにCSSトランジションまたはページレベルルーティングを使用
複雑な命令的シーケンスuseAnimate

大きなコンテナで layout を避ける理由は? Framerのレイアウトアニメーションは transform を使用して位置を調整しますが、ビューポート全体にまたがる要素や深いリフローをトリガーする要素では、計測コストが目に見えるジャンクやCLSを引き起こします。代わりに、CSS Grid/Flexbox トランジションを優先するか、特定の子要素のみに layoutId を付けて連携させてください。

レイアウトとトランジション

  • 共有要素トランジション → layoutId(マウントされたインスタンスごとに一意である必要があります)
  • 進入/終了トランジション → AnimatePresence(以下の mode ガイダンスを参照)

AnimatePresence の mode

常に明示的に mode を指定してください。デフォルト("sync")は進入と終了を同時に実行するため、ほとんどのUIパターンで視覚的な重複が発生します。

mode使用するタイミング
"wait"終了が完了してから進入が開始されます。モーダル、トースト、ページトランジションに使用します。
"sync"(デフォルト)進入と終了が重なります。意図的に重複させる場合のみ使用します(例:クロスフェードカルーセル)。
"popLayout"終了する要素は即座にフローから削除され、残りの要素がアニメーションで隙間を埋めます。リスト、タブ、却下可能なカードに使用します。
// モーダル — 常に "wait" を使用
<AnimatePresence mode="wait">
  {open && <Modal key="modal" />}
</AnimatePresence>

// 却下可能なリスト項目 — "popLayout" を使用
<AnimatePresence mode="popLayout">
  {items.map(item => <Card key={item.id} />)}
</AnimatePresence>

高度なパターン(コンセプト)

  • パララックス(スクロール連動トランスフォーム)
  • スクロールストーリーテリング(スティッキーセクション)
  • 3Dチルト(ポインタベースのトランスフォーム)
  • クロスフェード(共有 layoutId)
  • プログレッシブリビール(clip-path)
  • スケルトンローディング(ループするopacity)
  • マイクロインタラクション(ホバー/タップフィードバック)
  • スプリングシステム(物理ベースのモーション)

モーダルの必須要素

  • フォーカストラップ
  • Escapeキーで閉じる
  • スクロールロック
  • ARIAロール
  • AnimatePresence mode="wait" を使用して、次のモーダルが入る前に終了アニメーションが完了するようにする

完全な例

import React, { useEffect, useRef, useState } from "react"
import { motion, AnimatePresence } from "motion/react"

function useFocusTrap(ref: React.RefObject<HTMLDivElement | null>, active: boolean) {
  useEffect(() => {
    if (!active || !ref.current) return
    const el = ref.current
    const focusable = el.querySelectorAll<HTMLElement>(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    )
    const first = focusable[0]
    const last  = focusable[focusable.length - 1]

    function handleKey(e: KeyboardEvent) {
      if (e.key !== "Tab") return
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault()
        last?.focus()
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault()
        first?.focus()
      }
    }

    el.addEventListener("keydown", handleKey)
    first?.focus()
    return () => el.removeEventListener("keydown", handleKey)
  }, [active, ref])
}

function useScrollLock(active: boolean) {
  useEffect(() => {
    if (!active) return
    const prev = document.body.style.overflow
    document.body.style.overflow = "hidden"
    return () => { document.body.style.overflow = prev }
  }, [active])
}

function Modal({ open, closeModal }: { open: boolean; closeModal: () => void }) {
  const ref = useRef<HTMLDivElement>(null)

  useFocusTrap(ref, open)
  useScrollLock(open)

  useEffect(() => {
    function onKey(e: KeyboardEvent) {
      if (e.key === "Escape") closeModal()
    }
    if (open) window.addEventListener("keydown", onKey)
    return () => window.removeEventListener("keydown", onKey)
  }, [open, closeModal])

  return (
    // mode="wait" により、終了アニメーションが完了してから新しいモーダルが入る
    <AnimatePresence mode="wait">
      {open && (
        <motion.div
          role="dialog"
          aria-modal="true"
          aria-labelledby="modal-title"
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          exit={{ opacity: 0 }}
          transition={{ duration: 0.2 }}
          className="fixed inset-0 flex items-center justify-center bg-black/40"
        >
          <motion.div
            ref={ref}
            initial={{ scale: 0.95, opacity: 0 }}
            animate={{ scale: 1,    opacity: 1 }}
            exit={{    scale: 0.95, opacity: 0 }}
            transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}
            className="bg-white p-6 rounded"
          >
            <h2 id="modal-title">ダイアログタイトル</h2>
            <button onClick={closeModal}>閉じる</button>
          </motion.div>
        </motion.div>
      )}
    </AnimatePresence>
  )
}

export function Example() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <button onClick={() => setOpen(true)}>開く</button>
      <Modal open={open} closeModal={() => setOpen(false)} />
    </>
  )
}

SSR の安全性

  • サーバーとクライアントのレンダリング間で初期状態を一致させる
  • 暗黙的なアニメーション起点を避ける(常に initial を明示的に設定する)
  • Next.js App Router ではモーションコンポーネントを "use client" でラップする

デバッグ

確認事項:

  • 間違ったインポート(motion/react と framer-motion の混在)
  • Next.js App Router での "use client" ディレクティブの欠落
  • AnimatePresence の子要素での key プロパティの欠落
  • ハイドレーションの不一致(SSRとクライアントで初期状態が異なる)
  • 大きなコンテナでの layout プロパティの誤用によるリフロージャンク
  • 状態駆動型アニメーションがトリガーされない(依存関係配列を確認)

QA

  • CLSがないこと
  • キーボード操作が機能すること
  • モーダルでフォーカスがトラップされていること
  • ARIAロールが正しいこと(role="dialog"、aria-modal="true")
  • 動きの抑制が尊重されていること(useReducedMotion + CSSメディアクエリ)
  • Next.jsでハイドレーション警告が出ないこと
  • アンマウント時にアニメーションがクリーンに停止すること(メモリリークなし)
  • すべての使用箇所で AnimatePresence mode が明示的に設定されていること

アンチパターン

  • レイアウトプロパティ(width、height、top、left)のアニメーション
  • 目的のない無限アニメーション(常に問いかける:このアニメーションは何の状態を伝えているのか?)
  • 過度なスタッガーリスト(staggerChildren は 0.1秒以下に保つ。それを超えると遅く感じる)
  • 動きの抑制設定の無視
  • 大きなコンテナやビューポート全体での layout の使用
  • AnimatePresence での mode 省略(デフォルトの "sync" は視覚的な重複を引き起こす)
  • 純粋に装飾目的でのモーション使用

哲学

モーションはインタラクションデザインです。


最終ルール

モーションがUXを向上させないのであれば、削除する。


例

ボタンインタラクション

import { motion } from "motion/react"

export function Button() {
  return (
    <motion.button
      whileHover={{ scale: 1.02 }}
      whileTap={{ scale: 0.97 }}
      transition={{ duration: 0.15, ease: [0.4, 0, 0.2, 1] }}
    >
      クリック
    </motion.button>
  )
}

動きの抑制の例

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

export function FadeIn() {
  const reduce = useReducedMotion()

  return (
    <motion.div
      initial={{ opacity: 0, y: reduce ? 0 : 24 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: reduce ? 0.1 : 0.35, ease: [0.22, 1, 0.36, 1] }}
    />
  )
}

スタッガーリスト

import { motion } from "motion/react"

const container = {
  hidden: {},
  visible: {
    transition: { staggerChildren: 0.08 } // 遅さを避けるため 0.1秒以下に保つ
  }
}

const item = {
  hidden:  { opacity: 0, y: 10 },
  visible: { opacity: 1, y: 0,  transition: { duration: 0.3, ease: [0.22, 1, 0.36, 1] } }
}

export function List() {
  return (
    <motion.ul variants={container} initial="hidden" animate="visible">
      {[1, 2, 3].map(i => (
        <motion.li key={i} variants={item}>アイテム {i}</motion.li>
      ))}
    </motion.ul>
  )
}

AnimatePresence を使用したモーダル

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

export function Modal({ open }: { open: boolean }) {
  return (
    <AnimatePresence mode="wait">
      {open && (
        <motion.div
          initial={{ opacity: 0, scale: 0.95 }}
          animate={{ opacity: 1, scale: 1    }}
          exit={{    opacity: 0, scale: 0.95 }}
          transition={{ duration: 0.2, ease: [0.22, 1, 0.36, 1] }}
        />
      )}
    </AnimatePresence>
  )
}

スクロールパララックス

import { useScroll, useTransform, motion } from "motion/react"

export function Parallax() {
  const { scrollYProgress } = useScroll()
  const y = useTransform(scrollYProgress, [0, 1], [0, -80])

  return <motion.div style={{ y }} />
}

スケルトンローディング

import { motion } from "motion/react"

export function Skeleton() {
  return (
    <motion.div
      className="bg-gray-200 h-6 w-full rounded"
      animate={{ opacity: [0.5, 1, 0.5] }}
      transition={{
        duration: 1.5,       // 快適なパルス — 以前は欠落しており、高速フラッシュを引き起こしていた
        repeat: Infinity,
        ease: "easeInOut"
      }}
    />
  )
}

共有レイアウト(クロスフェード)

import { motion } from "motion/react"

// layoutId はマウントされたインスタンスごとに一意である必要があります。
// 複数のインスタンスが同時に存在できる場合は、一意のIDを追加:
// layoutId={`shared-${item.id}`}
export function Shared() {
  return <motion.div layoutId="shared" />
}

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

503496348-ops/mischief-production

Use this skill when inspecting Blender characters, rigs, poses, animation retargeting, ground contact, facing direction, or model-vs-motion alignment where screenshots alone are not enough.

503496348-ops/mischief-production

Build reusable Manim explainers for technical concepts, graphs, system diagrams, and product walkthroughs, then hand off to the wider HCP video stack if needed. Use when the user wants a clean animated explainer rather than a generic talking-head script.

503496348-ops/mischief-production

Advanced motion patterns for React / Next.js — drag & drop, gestures, text animations, SVG path drawing, custom hooks, imperative sequences (useAnimate), loaders, and the full API decision tree. Requires motion-foundations.

503496348-ops/mischief-production

Motion tokens, spring presets, performance rules, device adaptation, accessibility enforcement, and SSR safety for React / Next.js using motion/react. Foundation layer — all other motion skills depend on this.

503496348-ops/mischief-production

Production-ready animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs.

503496348-ops/mischief-production

Best practices for Remotion - Video creation in React. 29 domain-specific rules covering 3D, animations, audio, captions, charts, transitions, and more.

503496348-ops/mischief-production

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

関連スキル