Communitygithub.com

Sistema de Movimento v4.2

Sistema de movimento de UI pronto para produção para React/Next.js. Use ao implementar animações, transições ou padrões de movimento.

O que é Sistema de Movimento v4.2?

Este skill, 'Sistema de Movimento v4.2', é um sistema de movimento de UI focado em performance, acessibilidade e usabilidade, projetado para aplicações React e Next.js em produção. Ele fornece diretrizes e padrões para implementar animações que guiam a atenção do usuário, comunicam estados (como carregamento, sucesso, erro) e preservam a continuidade espacial durante transições e mudanças de layout. O sistema suporta as bibliotecas 'motion' (moderna) e 'framer-motion' (legado), alertando contra a mistura das duas. Inclui tokens de movimento pré-definidos (duração, easing, distância), recomendações de performance (usar transform e opacidade, evitar width/height), adaptação para dispositivos de baixo desempenho com base em memória e núcleos de CPU, e implementação completa de acessibilidade com `useReducedMotion` e CSS. O documento detalha padrões arquiteturais como `AnimatePresence` com modos explícitos (`wait`, `popLayout`), transições de elementos compartilhados via `layoutId`, e fornece exemplos práticos de interações de botão, listas escalonadas, modais, parallax e carregamento skeleton. A filosofia central é que movimento deve melhorar a experiência do usuário — caso contrário, deve ser removido.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Sistema de Movimento v4.2 faz?

Sistema de movimento de UI pronto para produção para React / Next.js.

Focado em performance, acessibilidade e usabilidade — não em decoração.

Quando Usar

Use este sistema de movimento quando o movimento:

  • Guia a atenção (ex.: integração, ações principais)
  • Comunica estado (carregamento, sucesso, erro, transições)
  • Preserva a continuidade espacial (mudanças de layout, navegação)

Cenários Apropriados

  • Componentes interativos (botões, modais, menus)
  • Transições de estado (carregando → carregado, aberto → fechado)
  • Navegação e continuidade de layout (elementos compartilhados, crossfade)

Considerações

  • Acessibilidade: Sempre suportar movimento reduzido
  • Adaptação de dispositivo: Ajustar para dispositivos de baixo desempenho
  • Trade-offs de performance: Preferir responsividade em vez de suavidade visual

Evite Usar Movimento Quando

  • É puramente decorativo
  • Reduz a usabilidade ou clareza
  • Impacta negativamente a performance

Como Funciona

Princípio Central

O movimento deve:

  • Guiar a atenção
  • Comunicar estado
  • Preservar a continuidade espacial

Se não fizer nada disso → remova-o.


Instalação

npm install motion

Versão

  • motion/react - padrão para projetos Motion for React atuais (pacote: motion)
  • framer-motion - caminho de importação legado para projetos que ainda dependem do Framer Motion

Não misture. Misturar causa conflitos nos agendadores internos e quebra o contexto AnimatePresence — componentes de um pacote não coordenarão animações de saída com componentes do outro.

Para verificar qual versão seu projeto usa:

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

Sempre importe de uma fonte consistente:

// Correto (moderno)
import { motion, AnimatePresence } from "motion/react"

// Correto (legado)
import { motion, AnimatePresence } from "framer-motion"

// Nunca misture ambos no mesmo projeto

Tokens de Movimento

// motionTokens.ts
export const motionTokens = {
  duration: {
    fast: 0.18,
    normal: 0.35,
    slow: 0.6
  },
  // Use estes como valor `ease` dentro de um objeto `transition`:
  // 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
  }
}

Exemplo de uso:

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
  }}
/>

Regras de Performance

Seguro

  • transform
  • opacity

Evitar

  • width / height
  • top / left

Regra: responsividade > suavidade


Adaptação de Dispositivo

A heurística combina a contagem de núcleos de CPU e memória disponível para um sinal mais confiável. deviceMemory está disponível no Chrome/Android; o fallback cobre Safari e Firefox.

const isLowEnd =
  typeof navigator !== "undefined" && (
    // Pouca memória (Chrome/Android apenas; indefinido em outros lugares → tratar como capaz)
    (navigator.deviceMemory !== undefined && navigator.deviceMemory <= 2) ||
    // Poucos núcleos E sem API de memória (cobre Safari/Firefox em hardware fraco)
    (navigator.deviceMemory === undefined && navigator.hardwareConcurrency <= 4)
  )

const duration = isLowEnd ? 0.2 : 0.4

Acessibilidade

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>

Arquitetura e Padrões

Padrões Principais

CenárioPadrão
Feedback de hoverwhileHover
Feedback de toque/pressionarwhileTap
Revelar ao scrollwhileInView
Valor vinculado ao scrolluseScroll + useTransform
Montagem/desmontagem condicionalAnimatePresence
Pequenas mudanças de layout (elemento único, < ~300px de alteração)Propriedade layout
Grandes mudanças de layout ou reflow de página inteiraEvitar layout; usar transições CSS ou roteamento no nível da página
Sequências imperativas complexasuseAnimate

Por que evitar layout em contêineres grandes? A animação de layout do Framer usa transform para reconciliar posições, mas em elementos que abrangem toda a viewport ou causam reflow profundo, o custo de medição causa travamentos visíveis e CLS. Prefira transições CSS Grid/Flexbox ou coordene com layoutId apenas em elementos filhos específicos.

Layout e Transições

  • Transições de elementos compartilhados → layoutId (deve ser único por instância montada)
  • Transições de entrada/saída → AnimatePresence (veja a orientação mode abaixo)

Modo AnimatePresence

Sempre especifique mode explicitamente — o padrão ("sync") executa entrada e saída simultaneamente, o que causa sobreposição visual na maioria dos padrões de UI.

modeQuando usar
"wait"A saída termina antes da entrada começar. Use para modais, toasts, transições de página.
"sync" (padrão)Entrada e saída se sobrepõem. Use apenas quando a sobreposição for intencional (ex.: carrosséis crossfade).
"popLayout"O elemento de saída é removido do fluxo imediatamente; os itens restantes animam para preencher. Use para listas, abas, cartões dispensáveis.
// Modal — sempre use "wait"
<AnimatePresence mode="wait">
  {open && <Modal key="modal" />}
</AnimatePresence>

// Item de lista dispensável — use "popLayout"
<AnimatePresence mode="popLayout">
  {items.map(item => <Card key={item.id} />)}
</AnimatePresence>

Padrões Avançados (Conceitos)

  • Parallax (transformações vinculadas ao scroll)
  • Contação de histórias com scroll (seções fixas)
  • Inclinação 3D (transformações baseadas em ponteiro)
  • Crossfade (layoutId compartilhado)
  • Revelação progressiva (clip-path)
  • Carregamento skeleton (opacidade em loop)
  • Micro-interações (feedback de hover/toque)
  • Sistema de mola (movimento baseado em física)

Essenciais de Modal

  • Armadilha de foco
  • Fechar com Escape
  • Bloqueio de scroll
  • Papéis ARIA
  • Use AnimatePresence mode="wait" para que a animação de saída termine antes do próximo modal entrar

Exemplo Completo

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" garante que a animação de saída termine antes de qualquer novo modal entrar
    <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">Título do Diálogo</h2>
            <button onClick={closeModal}>Fechar</button>
          </motion.div>
        </motion.div>
      )}
    </AnimatePresence>
  )
}

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

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

Segurança SSR

  • Corresponder estados iniciais entre renderizações do servidor e do cliente
  • Evitar origens de animação implícitas (sempre definir initial explicitamente)
  • Envolver componentes de movimento em "use client" no App Router do Next.js

Depuração

Verifique:

  • Importação errada (misturando motion/react e framer-motion)
  • Diretiva "use client" ausente no App Router do Next.js
  • Propriedade key ausente em filhos de AnimatePresence
  • Incompatibilidade de hidratação (estado inicial difere entre SSR e cliente)
  • Uso indevido da propriedade layout em contêineres grandes causando travamento de reflow
  • Animação acionada por estado não disparando (verifique arrays de dependência)

QA

  • Sem CLS
  • Teclado funciona
  • Foco preso em modais
  • Papéis ARIA corretos (role="dialog", aria-modal="true")
  • Movimento reduzido respeitado (useReducedMotion + media query CSS)
  • Sem avisos de hidratação no Next.js
  • Animações param limpa e completamente na desmontagem (sem vazamentos de memória)
  • AnimatePresence mode definido explicitamente em todos os locais de uso

Anti-Padrões

  • Animar propriedades de layout (width, height, top, left)
  • Animações infinitas sem propósito (sempre pergunte: que estado isso comunica?)
  • Escalonar listas em excesso (mantenha staggerChildren ≤ 0,1s; acima disso parece lento)
  • Ignorar preferências de movimento reduzido
  • Usar layout em contêineres grandes ou de viewport inteira
  • Omitir mode em AnimatePresence (o padrão "sync" causa sobreposição visual)
  • Usar movimento puramente para decoração

Filosofia

Movimento é design de interação.


Regra Final

Se o movimento não melhorar a UX → remova-o.


Exemplos

Interação de Botão

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] }}
    >
      Clique em mim
    </motion.button>
  )
}

Exemplo de Movimento Reduzido

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] }}
    />
  )
}

Lista Escalonada

import { motion } from "motion/react"

const container = {
  hidden: {},
  visible: {
    transition: { staggerChildren: 0.08 } // mantenha ≤ 0,1s para evitar lentidão
  }
}

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}>Item {i}</motion.li>
      ))}
    </motion.ul>
  )
}

Modal com 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>
  )
}

Parallax de Scroll

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 }} />
}

Carregamento Skeleton

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,       // pulsação confortável — estava ausente, causava flash rápido
        repeat: Infinity,
        ease: "easeInOut"
      }}
    />
  )
}

Layout Compartilhado (Crossfade)

import { motion } from "motion/react"

// layoutId deve ser único por instância montada.
// Se múltiplas instâncias podem existir simultaneamente, anexe um id único:
// 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.

Habilidades Relacionadas