Communitygithub.com

503496348-ops/mischief-production

Tokens de animação, presets de mola, regras de desempenho, adaptação de dispositivos, aplicação de acessibilidade e segurança SSR para React / Next.js usando motion/react. Camada fundamental — todas as outras habilidades de animação dependem desta.

O que é mischief-production?

Esta habilidade estabelece a base fundamental do sistema de animação para aplicações React e Next.js que utilizam a biblioteca `motion/react`. Ela define todos os valores, restrições e regras que habilidades downstream (como `motion-patterns` e `motion-advanced`) irão herdar, garantindo consistência, desempenho e acessibilidade em todo o projeto. O core da habilidade é composto por um sistema de tokens compartilhados (`motionTokens`) com durações, easings, distâncias e escalas predefinidas, além de um mapa de presets de mola (`springs`) com 5 configurações nomeadas. Também inclui uma função `shouldAnimate()` que atua como um gate central para decidir quando uma animação deve ou não ser executada, e hooks para suporte a `prefers-reduced-motion` que desabilitam transformações e limitam fades de opacidade. Para garantir segurança SSR e evitar erros de hidratação, a habilidade impõe regras rigorosas: o estado `initial` deve sempre corresponder à saída do servidor; o uso de `window` ou `navigator` em nível de módulo é proibido; e todo arquivo que importa `motion/react` deve ter a diretiva `"use client"`. Além disso, animações de propriedades de layout (`width`, `height`, `margin`, `padding`) são terminantemente proibidas em favor de `transform` e `opacity`. A habilidade oferece diretrizes de decisão para escolha de durações e molas, além de critérios claros para desabilitar animações completamente. É suportada em plataformas React/Next.js e depende exclusivamente do pacote `motion/react` (sem `framer-motion`). Ela não cobre padrões de componentes UI, gestos ou animações CSS — esses são delegados às habilidades complementares.

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

Perguntar na sua IA favorita

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

Documentação

Fundamentos de Movimento

A camada base do sistema de movimento. Define todos os valores, restrições e regras que as habilidades downstream (motion-patterns, motion-advanced) herdam. Carregue esta habilidade antes de qualquer trabalho de animação.

Quando Ativar

  • Iniciar qualquer componente animado do zero
  • Configurar tokens, presets de mola ou valores de easing
  • Implementar suporte a prefers-reduced-motion
  • Depurar incompatibilidades de hidratação provenientes de estados iniciais de animação
  • Avaliar se uma animação deve existir

Saídas

Esta habilidade produz:

  • Um objeto motionTokens compartilhado (duração, easing, distância, escala)
  • Um mapa de presets springs (5 configurações nomeadas)
  • Um gate shouldAnimate() usado por todos os componentes
  • Padrões de animação compatíveis com acessibilidade via useReducedMotion
  • Estados iniciais seguros para SSR sem avisos de hidratação

Princípios

O movimento deve realizar pelo menos uma das seguintes ações ou deve ser removido:

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

A responsividade sempre supera a suavidade. Uma animação de 60 fps que causa delay de entrada é pior do que nenhuma animação.

Regras

Estas são inegociáveis. Aplicam-se a todos os componentes do sistema.

  1. Use motion/react apenas. Nunca importe de framer-motion. Nunca misture os dois na mesma árvore.
  2. initial deve corresponder à saída do servidor. Se o servidor renderizar opacity: 1, a prop initial também deve ser opacity: 1. Sem exceções.
  3. Movimento reduzido sobrepõe tudo. Quando useReducedMotion() retornar true ou prefersReduced for true, todas as transformações são desabilitadas. Fades de opacidade com ≤ 0,2s são a única alternativa permitida.
  4. Nunca anime propriedades de layout. width, height, top, left, margin, padding são proibidos em animate. Use transform e opacity apenas.
  5. Todos os valores de token vêm de motionTokens. Durações e easings codificados em arquivos de componente são proibidos.
  6. Todas as configurações de mola vêm do mapa springs. Valores inline de stiffness/damping são proibidos.
  7. "use client" é obrigatório em todo arquivo que importa motion/react.
  8. Nunca leia window ou navigator em nível de módulo. Sempre proteja com typeof window !== "undefined".

Guia de Decisão

Escolhendo uma duração

TokenUse quando
instantShow/hide de tooltip, anel de foco, atualização de badge
fastFeedback de botão, troca de ícone, alternância de chip
normalAbertura de modal, expansão de cartão, entrada de elemento de página
slowEntrada heroica, transição de tela inteira
crawlNarrativa deliberada; use com moderação

Escolhendo uma mola

PresetUse quando
snappyUI padrão — botões, chips, itens de navegação
gentleCartões, modais, painéis pousando suavemente
bouncyMomentos lúdicos — estados vazios, onboarding
instantTooltips, popovers, dropdowns
releaseSoltar ao arrastar — sensação física natural

Quando desabilitar a animação completamente

Desabilite (faça shouldAnimate() retornar false) quando:

  • prefersReduced for true
  • isLowEnd for true e a animação não for essencial
  • O elemento estiver fora da tela e nunca entrar no viewport
  • A animação for puramente decorativa, sem propósito de UX

Conceitos Principais

Sistema de tokens

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

Flags de tempo de execução

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

Acessibilidade

Ordem de prioridade (da mais alta para a mais baixa):

  1. prefers-reduced-motion: reduce — desabilita todas as transformações, limita transições de opacidade a ≤ 0,2s
  2. Detecção de dispositivo de baixo desempenho — reduz duração, remove animações não essenciais
  3. Preferência de design — todo o resto

O movimento deve degradar graciosamente. Nunca deve desaparecer abruptamente de forma que cause alteração de layout ou confunda a orientação.

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

Segurança SSR / hidratação

Regra: initial deve sempre corresponder ao que o servidor renderiza.

// ERRADO — servidor renderiza opacity:1 mas initial diz 0 → incompatibilidade de hidratação
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />

// CORRETO — use AnimatePresence ou adie para montagem no cliente
"use client"
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])

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

Exemplos de Código

Exemplo completo: tokens + molas + acessibilidade + proteção 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) {
  // Proteção SSR — initial deve corresponder à saída do servidor (opacity: 1)
  const [mounted, setMounted] = useState(false)
  useEffect(() => setMounted(true), [])

  // Acessibilidade — desabilita transformação quando movimento reduzido é preferido
  const safeMotion = useSafeMotion(motionTokens.distance.md)

  // Gate de dispositivo — pula animação em hardware de baixo desempenho
  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>
  )
}

Restrições / Não-Objetivos

Esta habilidade não cobre:

  • Padrões de componentes de UI (botão, modal, escalonamento) → consulte motion-patterns
  • Arrastar, gestos, SVG, animações de texto, hooks personalizados → consulte motion-advanced
  • Animações apenas em CSS ou classes Tailwind animate-* sem motion/react
  • Bibliotecas de animação de terceiros (GSAP, anime.js, etc.)
  • Decisões de design de movimento (quando animar, o que enfatizar) — isso é uma preocupação de design, não uma restrição de código

Anti-Padrões

Anti-padrãoRegra violadaCorreção
import { motion } from "framer-motion"Regra 1Use motion/react
initial={{ opacity: 0 }} em componente SSRRegra 2Adicione proteção de montagem
Pular verificação useReducedMotionRegra 3Use o hook useSafeMotion
animate={{ width: "100%" }}Regra 4Use transformação scaleX
transition={{ duration: 0.4 }} inlineRegra 5Use motionTokens.duration.normal
{ stiffness: 300, damping: 30 } inlineRegra 6Use springs.snappy
Diretiva "use client" ausenteRegra 7Adicione ao topo do arquivo
navigator.hardwareConcurrency em nível de móduloRegra 8Envolva em typeof navigator !== "undefined"

Habilidades Relacionadas

  • motion-patterns — consome tokens e molas definidos aqui para construir padrões de botão, modal, escalonamento, transição de página e rolagem. Não redefine nenhum valor.
  • motion-advanced — consome tokens e molas definidos aqui para padrões de arrastar, SVG, texto e gestos. Adiciona sequências useAnimate e hooks personalizados sobre esta fundação.

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.

Habilidades Relacionadas