Preâmbulo (executar primeiro)
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRIA: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"page-load-animations","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"page-load-animations","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi
Se TEL_PROMPTED for no: Antes de iniciar o fluxo de trabalho da skill, pergunte ao usuário sobre telemetria.
Use AskUserQuestion:
Ajude o superstack a melhorar! Monitoramos quais skills são usadas e quanto tempo levam — nenhum código, caminho de arquivo ou PII. Mude a qualquer momento em
~/.superstack/config.json.
Opções:
- A) Claro, ajude o superstack a melhorar (anônimo)
- B) Não, obrigado
Se A: execute este bash:
echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted
Se B: execute este bash:
echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted
Isso só acontece uma vez. Se TEL_PROMPTED for yes, pule isso completamente e prossiga para o fluxo de trabalho da skill.
Skill errada? Veja SKILL_ROUTER.md para todas as skills disponíveis.
Animações de Carregamento de Página
Padrões adaptados de receitas framer-motion testadas em batalha. Inspiração original: suzi-ux-motions.
Receitas de produção para framer-motion que fazem com que os carregamentos de página pareçam intencionais em vez de caóticos. Esta skill existe porque o problema de animação mais comum em UIs cripto não é a falta de animação — é tudo aparecer de uma vez sem coreografia, escalonamento ou física de mola. O resultado parece quebrado mesmo quando o código está correto.
Esta skill fornece as receitas de implementação. Para teoria de animação (quando animar, faixas de duração, curvas de suavização, movimento reduzido), consulte frontend-design-guidelines/references/animation.md. Esta skill herda todas essas restrições de base.
Modelo de Autoridade
animation.md= restrições de base (faixas de duração, suavização, movimento reduzido, propriedades GPU)- Esta skill = receitas de produção que implementam dentro dessas restrições
frontend-design-guidelinesDELEGA a esta skill para padrões framer-motion, não o contrário
Configuração
npm install framer-motion
Transições CSS são o padrão para mudanças de estado simples (conforme animation.md). Use framer-motion quando precisar de: física de mola, sequências orquestradas, animações de saída AnimatePresence, gestos/arrasto, ou transições de layout compartilhadas.
Quando Acionar Esta Skill
Aplique estas receitas sempre que estiver:
- Construindo uma página que carrega várias seções (dashboard, tela de detalhes, landing page)
- Escalonando uma lista, grade de cartões ou tabela na montagem
- Animando um modal, dropdown ou popover
- Alternando abas ou filtros onde o conteúdo muda e a altura se desloca
- Exibindo números, gráficos ou gráficos de rosca com atualização ao vivo
- Adicionando feedback de hover, rotação de chevron ou entrada de tooltip
- Revisando código framer-motion existente em busca de anti-padrões
- Um usuário diz "a página parece desengonçada" ou "tudo aparece de uma vez"
Se você estiver construindo um componente de nível de página e esta skill não foi acionada, acione-a você mesmo.
Fluxo de Trabalho
Antes de escrever código de animação, identifique qual arquivo de referência é relevante e leia-o:
- Orquestrando uma entrada de página → references/page-choreography.md
- Escalonando uma lista ou grade de cartões → references/list-stagger.md
- Animando um modal, dropdown ou popover → references/popups-modals.md
- Alternando abas/filtros com mudanças de altura → references/filter-transitions.md
- Números rolantes, morfoses de gráfico, revelações de rosca → references/live-data.md
- Feedback de botão, rotação de chevron, tooltips → references/hover-micro.md
- Consultando uma predefinição de mola ou curva de suavização → references/spring-presets.md
Carregue apenas o que você precisa. Não leia todas as referências de antemão.
Modo 1: Construindo novas animações
- Leia o(s) arquivo(s) de referência relevante(s) para o padrão necessário.
- Comece com o comentário do storyboard ASCII — planeje a sequência completa antes de escrever qualquer código.
- Defina um objeto TIMING com constantes nomeadas para cada atraso.
- Implemente usando os padrões da referência. Use física de mola por padrão.
- Verifique os itens inegociáveis abaixo antes de relatar conclusão.
Modo 2: Revisando código de animação existente
- Varra em busca de anti-padrões comuns:
# layout prop no pai E nos filhos (fonte de tremor) grep -rn "layout" --include="*.tsx" --include="*.jsx" | head -20 # staggerChildren com AnimatePresence (não confiável) grep -rn "staggerChildren" --include="*.tsx" --include="*.jsx" | head -10 # transition-all (anima propriedades não intencionais) grep -rn "transition-all\|transition: all" --include="*.tsx" --include="*.css" | head -10 # Falta de tratamento de movimento reduzido grep -rn "motion\.\|animate=" --include="*.tsx" -l | while read f; do grep -L "reduced-motion\|useReducedMotion\|motion-safe" "$f"; done | head -10 - Para cada problema encontrado, referencie a regra de anti-padrão específica do arquivo de referência relevante.
- Forneça correções de código exatas.
Modo 3: Consulta rápida
Se o usuário perguntar "qual configuração de mola para X?" ou "como animo Y?", responda diretamente dos arquivos de referência e predefinições de mola sem executar um fluxo de trabalho completo.
Inegociáveis
- Comentário de storyboard ASCII. Toda página animada começa com um comentário de linha do tempo mostrando a sequência completa de relance. Os tempos são absolutos a partir da montagem, alinhados à direita.
- Constantes de timing nomeadas. Cada atraso vai em um objeto TIMING no topo do arquivo. Sem números mágicos em
setTimeoutou propsdelay. - Mola primeiro. Prefira física de mola em vez de suavização baseada em duração para movimento natural e interrompível. Use duração apenas para fades e tooltips.
- Sequenciamento orientado por estágio. Um único estado inteiro controla sequências de várias seções. Sem flags booleanas espalhadas.
- Padrão
stage >= N. As seções permanecem visíveis uma vez que aparecem. Nuncastage === N. - Nunca
layoutno pai E nos filhos. Esta é a causa nº 1 de animações de filtro tremidas. UseAnimatedHeightcomResizeObserver. - Nunca
staggerChildrencomAnimatePresence. Não funciona de forma confiável. Usedelay: i * staggermanual. - Respeite
prefers-reduced-motion. Herdado deanimation.md. Toda animação deve degradar-se graciosamente. - Distinção entre montagem e atualização. Animações de montagem são dramáticas (600ms, suavização expressiva). Animações de atualização são sutis (150ms, suavização suave). Fases diferentes, configurações diferentes.
Princípios de Design
- Storyboard primeiro — planeje a sequência antes de escrever código
- Mola primeiro — física de mola em vez de suavização baseada em duração
- Constantes nomeadas — todo valor de timing é declarado, não inline
- Orientado por estágio — um único estado inteiro orquestra sequências complexas
- Orientado a dados — elementos repetidos usam
.map()com atrasos baseados em índice, não blocos copiados e colados - Meça, não adivinhe —
ResizeObserverpara alturas dinâmicas, nunca alturas em pixels codificadas
Integração com Outras Skills
frontend-design-guidelines— a skill de UI geral. Ela delega o trabalho com framer-motion a esta skill. Quando ambas disparam, as regras de base deanimation.mdsão autoritativas para restrições; esta skill é autoritativa para receitas de implementação.number-formatting— para exibições de números com atualização ao vivo, usenumber-formattingpara a especificação de formatação e esta skill para o padrão de animação de dígitos rolantes.brand-design— as cores da marca podem afetar as escolhas de cor da animação (indicadores positivos/negativos, destaques de acento).
Recursos
references/
- references/page-choreography.md — Entrada de página orientada por estágio com storyboards ASCII, objetos TIMING, configurações de seção, predefinições de mola e o padrão
stage >= N - references/list-stagger.md — Atrasos de escalonamento baseados em índice, wrapper StaggerItem, diretrizes de timing/deslocamento e anti-padrões
- references/popups-modals.md — Animação de modal em três camadas (fundo, painel, escalonamento de conteúdo), padrão de dropdown, comportamentos de fechamento
- references/filter-transitions.md — AnimatedHeight com ResizeObserver, cross-fade com wrapper chaveado, anti-padrão crítico de
layout - references/live-data.md — Dígitos de número rolante (caça-níqueis), revelações de gráfico de rosca SVG, morfose de gráfico, gerenciamento de fase de montagem vs atualização
- references/hover-micro.md — Matriz de decisão CSS vs framer-motion, feedback de botão, rotação de chevron, entrada de tooltip, feedback de cópia
- references/spring-presets.md — Todas as predefinições como tabelas + JSON: configurações de mola, curvas de suavização, valores de escalonamento, predefinições de duração
Referências entre skills
frontend-design-guidelines/references/animation.md— restrições de base que esta skill herda (faixas de duração, suavização, movimento reduzido, propriedades GPU)number-formatting— para regras de exibição de números (formatação, não animação)
Início Rápido
# Gatilhos:
# "Corrigir o carregamento da minha página — tudo aparece de uma vez"
# "Adicionar animações de entrada a este dashboard"
# "A animação do modal parece desengonçada"
# "Como escalono estes cartões?"
# "Qual configuração de mola devo usar para um dropdown?"
# "Adicionar animação de número rolante ao display de saldo"
# "Dispara automaticamente ao construir componentes de nível de página"
Telemetria (executar por último)
Após a conclusão do fluxo de trabalho da skill (sucesso, erro ou aborto), registre o evento de telemetria.
Determine o resultado a partir do resultado do fluxo de trabalho: success se concluído normalmente, error se falhou, abort se o usuário interrompeu.
Execute este bash:
_TEL_END=$(date +%s)
_TEL_DUR=$(( _TEL_END - ${_TEL_START:-$_TEL_END} ))
_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//' || echo "anonymous")
if [ "$_TEL_TIER" != "off" ]; then
echo '{"skill":"page-load-animations","phase":"build","event":"completed","outcome":"OUTCOME","duration_s":"'"$_TEL_DUR"'","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","platform":"'$(uname -s)-$(uname -m)'"}' >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
true
fi
Substitua OUTCOME por success/error/abort com base no resultado do fluxo de trabalho.