Communitygithub.com

Abduovv/Arcadia-frontend

Corrige carregamentos desengonçados de página onde tudo aparece de uma vez. Receitas de produção para framer-motion com entradas coreografadas de página, listas escalonadas, transições de modal, cross-fades de filtro, animações de dados ao vivo e micro-interações.

O que é Arcadia-frontend?

Esta skill fornece um conjunto de receitas de produção para framer-motion, focadas em resolver o problema comum de animações em UIs que parecem quebradas ou desengonçadas porque tudo aparece ao mesmo tempo. Ela abrange desde coreografias de entrada de página até micro-interações em hover, passando por listas escalonadas, animações de modal, transições de filtro com mudança de altura e atualizações de dados ao vivo (como números rolantes e gráficos). A skill é projetada para ser usada proativamente ao construir componentes de nível de página ou revisar código de animação, e seu fluxo de trabalho inclui três modos: construir novas animações, revisar código existente e consulta rápida de configurações (e.g., molas). Ela se integra com outras skills de design (como `frontend-design-guidelines` e `number-formatting`) e impõe várias regras inegociáveis, como o uso de storyboards em ASCII para planejamento, constantes de timing nomeadas, física de mola como padrão, e respeito à preferência de movimento reduzido do usuário (`prefers-reduced-motion`).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Abduovv/Arcadia-frontend/tree/HEAD/.agents/skills/page-load-animations

Perguntar na sua IA favorita

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

Documentação

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-guidelines DELEGA 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:

Carregue apenas o que você precisa. Não leia todas as referências de antemão.

Modo 1: Construindo novas animações

  1. Leia o(s) arquivo(s) de referência relevante(s) para o padrão necessário.
  2. Comece com o comentário do storyboard ASCII — planeje a sequência completa antes de escrever qualquer código.
  3. Defina um objeto TIMING com constantes nomeadas para cada atraso.
  4. Implemente usando os padrões da referência. Use física de mola por padrão.
  5. Verifique os itens inegociáveis abaixo antes de relatar conclusão.

Modo 2: Revisando código de animação existente

  1. 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
    
  2. Para cada problema encontrado, referencie a regra de anti-padrão específica do arquivo de referência relevante.
  3. 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

  1. 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.
  2. Constantes de timing nomeadas. Cada atraso vai em um objeto TIMING no topo do arquivo. Sem números mágicos em setTimeout ou props delay.
  3. 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.
  4. Sequenciamento orientado por estágio. Um único estado inteiro controla sequências de várias seções. Sem flags booleanas espalhadas.
  5. Padrão stage >= N. As seções permanecem visíveis uma vez que aparecem. Nunca stage === N.
  6. Nunca layout no pai E nos filhos. Esta é a causa nº 1 de animações de filtro tremidas. Use AnimatedHeight com ResizeObserver.
  7. Nunca staggerChildren com AnimatePresence. Não funciona de forma confiável. Use delay: i * stagger manual.
  8. Respeite prefers-reduced-motion. Herdado de animation.md. Toda animação deve degradar-se graciosamente.
  9. 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

  1. Storyboard primeiro — planeje a sequência antes de escrever código
  2. Mola primeiro — física de mola em vez de suavização baseada em duração
  3. Constantes nomeadas — todo valor de timing é declarado, não inline
  4. Orientado por estágio — um único estado inteiro orquestra sequências complexas
  5. Orientado a dados — elementos repetidos usam .map() com atrasos baseados em índice, não blocos copiados e colados
  6. Meça, não adivinhe — ResizeObserver para 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 de animation.md sã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, use number-formatting para 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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas