Communitygithub.com

모션 파운데이션

모션 토큰, 스프링 프리셋, 성능 규칙, 기기 적응, 접근성 시행 및 React/Next.js용 SSR 안전성을 제공합니다. 모든 다른 모션 스킬이 의존하는 기본 레이어입니다.

모션 파운데이션란 무엇인가요?

Motion Foundations는 React 및 Next.js 애플리케이션을 위한 모션 시스템의 기본 레이어입니다. 공유 `motionTokens` 객체(지속 시간, 이징, 거리, 스케일)와 5개의 명명된 스프링 프리셋을 정의하고, `shouldAnimate()` 게이트와 접근성 규칙을 통해 모든 구성 요소가 일관된 애니메이션 값을 사용하도록 강제합니다. `motion/react` 라이브러리만 사용하며, `framer-motion`과 혼용할 수 없고, 모든 애니메이션은 `transform`과 `opacity`로 제한됩니다. `useReducedMotion()` 훅을 통해 접근성을 자동으로 처리하고, SSR 환경에서는 `initial` prop이 서버 렌더링 출력과 일치하도록 하여 하이드레이션 불일치를 방지합니다. 저사양 기기 및 접근성 선호도를 감지하여 `shouldAnimate()`에서 애니메이션을 비활성화할 수 있습니다. 이 스킬은 `motion-patterns` 및 `motion-advanced` 같은 하위 스킬이 상속하는 규칙, 토큰 및 패턴의 중앙 소스 역할을 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/503496348-ops/mischief-production/tree/HEAD/skills/ecc-motion-foundations

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

모션 파운데이션은(는) 무엇을 하나요?

모션 시스템의 기본 레이어입니다. 하위 스킬(motion-patterns, motion-advanced)이 상속하는 모든 값, 제약 조건 및 규칙을 정의합니다. 애니메이션 작업을 시작하기 전에 이 스킬을 로드하세요.

활성화 시점

  • 처음부터 애니메이션 컴포넌트를 시작할 때
  • 토큰, 스프링 프리셋 또는 이징 값을 설정할 때
  • prefers-reduced-motion 지원을 구현할 때
  • 애니메이션 초기 상태로 인한 하이드레이션 불일치를 디버깅할 때
  • 애니메이션이 존재해야 하는지 여부를 평가할 때

출력

이 스킬은 다음을 생성합니다:

  • 공유 motionTokens 객체 (지속 시간, 이징, 거리, 스케일)
  • 공유 springs 프리셋 맵 (5개의 명명된 구성)
  • 모든 컴포넌트에서 사용하는 shouldAnimate() 게이트
  • useReducedMotion을 통한 접근성 준수 애니메이션 기본값
  • 하이드레이션 경고가 없는 SSR 안전 초기 상태

원칙

모션은 다음 중 하나 이상을 수행해야 하며, 그렇지 않으면 제거되어야 합니다:

  • 주의를 안내
  • 상태를 전달
  • 공간적 연속성을 유지

반응성은 항상 부드러움보다 우선합니다. 입력 지연을 유발하는 60fps 애니메이션은 애니메이션이 없는 것보다 나쁩니다.

규칙

이 규칙은 협상 불가능합니다. 시스템의 모든 컴포넌트에 적용됩니다.

  1. motion/react만 사용하세요. 절대 framer-motion에서 가져오지 마세요. 동일한 트리에서 둘을 혼용하지 마세요.
  2. initial은 서버 출력과 일치해야 합니다. 서버가 opacity: 1을 렌더링하면 initial prop도 opacity: 1이어야 합니다. 예외 없음.
  3. 모션 감소(reduced motion)가 모든 것을 재정의합니다. useReducedMotion()이 true를 반환하거나 prefersReduced가 true이면 모든 변환이 비활성화됩니다. ≤ 0.2초의 불투명도 페이드만 허용되는 폴백입니다.
  4. 레이아웃 속성을 절대 애니메이션하지 마세요. width, height, top, left, margin, padding은 animate에서 금지됩니다. transform과 opacity만 사용하세요.
  5. 모든 토큰 값은 motionTokens에서 가져옵니다. 컴포넌트 파일에 하드코딩된 지속 시간과 이징은 금지됩니다.
  6. 모든 스프링 구성은 springs 맵에서 가져옵니다. 인라인 stiffness/damping 값은 금지됩니다.
  7. "use client"는 motion/react에서 가져오는 모든 파일에 필요합니다.
  8. 모듈 수준에서 window 또는 navigator를 절대 읽지 마세요. 항상 typeof window !== "undefined"로 보호하세요.

결정 가이드

지속 시간 선택

토큰사용 시기
instant툴팁 표시/숨기기, 포커스 링, 배지 업데이트
fast버튼 피드백, 아이콘 교체, 칩 토글
normal모달 열기, 카드 확장, 페이지 요소 진입
slow히어로 진입, 전체 페이지 전환
crawl의도적인 스토리텔링; 절약해서 사용

스프링 선택

프리셋사용 시기
snappy기본 UI — 버튼, 칩, 네비게이션 아이템
gentle부드럽게 착지하는 카드, 모달, 패널
bouncy장난스러운 순간 — 빈 상태, 온보딩
instant툴팁, 팝오버, 드롭다운
release드래그 해제 — 자연스러운 물리적 느낌

애니메이션을 완전히 비활성화해야 하는 경우

다음 경우 shouldAnimate()가 false를 반환하도록 비활성화하세요:

  • prefersReduced가 true인 경우
  • isLowEnd가 true이고 애니메이션이 필수가 아닌 경우
  • 요소가 화면 밖에 있고 뷰포트에 진입하지 않을 경우
  • 애니메이션이 UX 목적 없이 순수하게 장식용인 경우

핵심 개념

토큰 시스템

// lib/motion-tokens.ts
export const motionTokens = {
  duration: {
    instant: 0.08,
    fast:    0.18,
    normal:  0.35,
    slow:    0.6,
    crawl:   1.0,
  },
  easing: {
    smooth: [0.22, 1, 0.36, 1],
    sharp:  [0.4, 0, 0.2, 1],
    bounce: [0.34, 1.56, 0.64, 1],
    linear: [0, 0, 1, 1],
  },
  distance: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 48,
  },
  scale: {
    subtle: 0.98,
    press:  0.95,
    pop:    1.04,
  },
}

export const springs = {
  snappy:  { type: "spring", stiffness: 300, damping: 30 },
  gentle:  { type: "spring", stiffness: 120, damping: 14 },
  bouncy:  { type: "spring", stiffness: 400, damping: 10 },
  instant: { type: "spring", stiffness: 600, damping: 35 },
  release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },
}

런타임 플래그

// lib/motion-config.ts
export const motionConfig = {
  isLowEnd() {
    return (
      typeof navigator !== "undefined" &&
      navigator.hardwareConcurrency <= 4
    )
  },

  prefersReduced() {
    return (
      typeof window !== "undefined" &&
      window.matchMedia("(prefers-reduced-motion: reduce)").matches
    )
  },

  shouldAnimate({ essential = false } = {}) {
    if (this.prefersReduced()) return false
    if (!essential && this.isLowEnd()) return false
    return true
  },

  duration() {
    return this.isLowEnd() || this.prefersReduced()
      ? motionTokens.duration.instant
      : motionTokens.duration.normal
  },
}

접근성

우선 순위 (높은 순에서 낮은 순):

  1. prefers-reduced-motion: reduce — 모든 변환을 비활성화하고 opacity 전환을 ≤ 0.2초로 제한
  2. 저사양 기기 감지 — 지속 시간을 줄이고 필수가 아닌 애니메이션을 제거
  3. 디자인 선호도 — 그 외 모든 것

모션은 우아하게 저하되어야 합니다. 레이아웃 이동을 일으키거나 방향 감각을 혼란스럽게 하는 방식으로 갑자기 사라져서는 안 됩니다.

// hooks/use-reduced-motion.tsx
"use client"
import { useReducedMotion } from "motion/react"

export function useSafeMotion(fullY: number = 16) {
  const reduce = useReducedMotion()
  return {
    initial: { opacity: 0, y: reduce ? 0 : fullY },
    animate: { opacity: 1, y: 0 },
    exit:    { opacity: 0, y: reduce ? 0 : -fullY },
  }
}
/* globals.css */
@media (prefers-reduced-motion: reduce) {
  .motion-safe-transition  { transition: opacity 0.15s; }
  .motion-reduce-transform { transform: none !important; }
}
<!-- Tailwind -->
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>

SSR / 하이드레이션 안전성

규칙: initial은 항상 서버가 렌더링하는 것과 일치해야 합니다.

// 잘못된 예 — 서버는 opacity:1을 렌더링하지만 initial은 0 → 하이드레이션 불일치
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />

// 올바른 예 — AnimatePresence를 사용하거나 클라이언트 마운트로 지연
"use client"
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])

<motion.div
  initial={{ opacity: mounted ? 0 : 1 }}
  animate={{ opacity: 1 }}
/>

코드 예제

종합: 토큰 + 스프링 + 접근성 + SSR 가드

// components/fade-in-card.tsx
"use client"

import { useState, useEffect } from "react"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
import { motionConfig } from "@/lib/motion-config"

interface FadeInCardProps {
  children: React.ReactNode
  delay?: number
}

export function FadeInCard({ children, delay = 0 }: FadeInCardProps) {
  // SSR 가드 — initial은 서버 출력(opacity: 1)과 일치해야 함
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])

  // 접근성 — 모션 감소가 선호될 때 transform 비활성화
  const safeMotion = useSafeMotion(motionTokens.distance.md)

  // 기기 게이트 — 저사양 하드웨어에서 애니메이션 건너뛰기
  if (!motionConfig.shouldAnimate() || !mounted) {
    return <div>{children}</div>
  }

  return (
    <motion.div
      initial={safeMotion.initial}
      animate={safeMotion.animate}
      exit={safeMotion.exit}
      transition={{
        ...springs.gentle,
        delay,
      }}
      whileHover={{ scale: motionTokens.scale.pop }}
      whileTap={{ scale: motionTokens.scale.press }}
    >
      {children}
    </motion.div>
  )
}

제약 사항 / 비목표

이 스킬은 다음을 다루지 않습니다:

  • UI 컴포넌트 패턴 (버튼, 모달, 스태거) → motion-patterns 참조
  • 드래그, 제스처, SVG, 텍스트 애니메이션, 커스텀 훅 → motion-advanced 참조
  • CSS 전용 애니메이션 또는 motion/react 없는 Tailwind animate-* 클래스
  • 타사 애니메이션 라이브러리 (GSAP, anime.js 등)
  • 모션 디자인 결정 (애니메이션 시기, 강조할 내용) — 이는 코드 제약이 아닌 디자인 고려 사항입니다

안티패턴

안티패턴위반된 규칙수정
import { motion } from "framer-motion"규칙 1motion/react 사용
SSR 컴포넌트에서 initial={{ opacity: 0 }}규칙 2마운트 가드 추가
useReducedMotion 검사 생략규칙 3useSafeMotion 훅 사용
animate={{ width: "100%" }}규칙 4scaleX transform 사용
인라인 transition={{ duration: 0.4 }}규칙 5motionTokens.duration.normal 사용
인라인 { stiffness: 300, damping: 30 }규칙 6springs.snappy 사용
"use client" 지시문 누락규칙 7파일 상단에 추가
모듈 수준의 navigator.hardwareConcurrency규칙 8typeof navigator !== "undefined"로 감싸기

관련 스킬

  • motion-patterns — 여기에 정의된 토큰과 스프링을 소비하여 버튼, 모달, 스태거, 페이지 전환 및 스크롤 패턴을 만듭니다. 어떤 값도 재정의하지 않습니다.
  • motion-advanced — 여기에 정의된 토큰과 스프링을 소비하여 드래그, SVG, 텍스트 및 제스처 패턴을 만듭니다. 이 기반 위에 useAnimate 시퀀스와 커스텀 훅을 추가합니다.

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

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

Production-ready UI motion system for React/Next.js. Use when implementing animations, transitions, or motion patterns.

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.

관련 스킬