Communitygithub.com

ComeOnOliver/skillshub

Use quando o manipulador de conclusão de CAAnimation não dispara, as físicas de mola parecem erradas no dispositivo, a duração da animação não corresponde ao tempo real, a interação entre gestos e animação causa travamentos, ou o tempo difere entre simulador e hardware real — diagnóstico sistemático de CAAnimation com padrões de CATransaction, consciência de taxa de quadros e comportamento específico do dispositivo.

O que é skillshub?

Esta skill oferece uma abordagem sistemática e baseada em diagnóstico para depuração de problemas de animação UIKit com CAAnimation no iOS. Ela ajuda desenvolvedores a identificar rapidamente a causa raiz de problemas como manipuladores de conclusão que não disparam, durações incorretas de animação (declarada vs. visual), físicas de mola que funcionam de forma diferente entre dispositivos e travamentos causados pela interação entre gestos e animações. A skill fornece um conjunto obrigatório de etapas de diagnóstico (blocos de código) para isolar o problema antes de qualquer alteração de código, enfatizando a proibição de soluções paliativas como codificar valores. Ela inclui uma árvore de decisão para guiar o usuário na seleção do padrão correto (como verificar CATransaction, isRemovedOnCompletion, weak self e sincronização CADisplayLink) e uma tabela de referência rápida. A skill suporta a criação de perfis com Instruments para casos extremos e exige testes em dispositivos reais, sendo adequada para ambientes de desenvolvimento iOS que usam Swift e Core Animation.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-uikit-animation-debugging

Perguntar na sua IA favorita

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

Documentação

Depuração de Animação UIKit

Visão Geral

Problemas com CAAnimation se manifestam como manipuladores de conclusão ausentes, tempo incorreto ou travamentos sob condições específicas. Princípio central: 90% dos problemas de CAAnimation são causados pelo tempo de CATransaction, estado da camada ou suposições sobre a taxa de quadros, não por bugs no Core Animation.

Sinais de Alerta — Suspeitar de Problema com CAAnimation

Se você vir QUALQUER UM destes, suspeite da lógica de animação, não do comportamento do dispositivo:

  • O manipulador de conclusão dispara no simulador, mas não no dispositivo
  • A duração da animação (0,5s) não corresponde à duração visual (1,2s)
  • A animação de mola parece correta no iPhone 15 Pro, mas trava em dispositivos mais antigos
  • Gestos + animação juntos causam gagueira (funcionam bem separadamente)
  • [weak self] no manipulador de conclusão e você não tem certeza do porquê
  • ❌ PROIBIDO: Codificar duração/valores para "corresponder ao que realmente acontece"
    • Isso envia bugs específicos do dispositivo para usuários em hardware diferente
    • Não racionalize isso como uma "correção temporária" ou "bom o suficiente"

Distinção crítica: O simulador frequentemente oculta problemas de tempo (apenas 60Hz, sem aceleração). Dispositivos reais os expõem (taxa de quadros variável, aceleração da CPU, pressão de segundo plano). OBRIGATÓRIO: Testar em dispositivo real (modelo mais antigo suportado) antes de enviar.

Primeiros Passos Obrigatórios

SEMPRE execute estes PRIMEIRO (antes de alterar o código):

// 1. Verificar se a conclusão está disparando
animation.completion = { [weak self] finished in
    print("🔥 COMPLETION FIRED: finished=\(finished)")
    guard let self = self else {
        print("🔥 SELF WAS NIL")
        return
    }
    // código original
}

// 2. Verificar duração real vs. declarada
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5  // Declarada
layer.add(anim, forKey: "test")

DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
    print("Tempo decorrido: \(Date().timeIntervalSince(startTime))")  // Real
}

// 3. Verificar quais animações estão ativas
if let keys = layer.animationKeys() {
    print("Animações ativas: \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key): duração=\(anim.duration), removida=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. Verificar estado da camada
print("Velocidade da camada: \(layer.speed)")  // != 1.0 significa que o tempo está sendo escalado
print("TimeOffset da camada: \(layer.timeOffset)")  // != 0 significa que a animação está deslocada

O que isso te diz

  • Print da conclusão aparece → O manipulador dispara, o problema está no código do callback
  • Print da conclusão ausente → O manipulador não dispara, verifique CATransaction/estado da camada
  • Tempo decorrido == declarado → A duração está correta, o travamento visual é devido aos quadros
  • Tempo decorrido != declarado → O encapsulamento CATransaction está alterando a duração
  • layer.speed != 1.0 → Algo está desacelerando a animação
  • Lista de animações ativas é longa → Múltiplas animações competindo

INTERPRETAÇÃO OBRIGATÓRIA

Antes de alterar QUALQUER código, você deve identificar qual ÚNICO diagnóstico é a causa raiz:

  1. Se a conclusão dispara, mas o tempo decorrido != duração declarada → Aplicar Padrão 2 (CATransaction)
  2. Se a conclusão não dispara E isRemovedOnCompletion é verdadeiro → Aplicar Padrão 3
  3. Se a conclusão dispara, mas o visual está travado → DEVE criar perfil com Instruments primeiro
    • Você não pode adivinhar "provavelmente são os quadros" - prove com dados
    • O instrumento Perfil > Core Animation mostra quedas de quadros com certeza
    • Se você pular Instruments, está adivinhando

Se os diagnósticos são contraditórios ou pouco claros

  • PARE. Não prossiga para os padrões ainda
  • Adicione mais prints para restringir a causa
  • Pergunte: "Os diagnósticos mostram X e Y, mas Z não corresponde. O que estou perdendo?"
  • Crie perfil com Instruments > Core Animation se não tiver certeza

Árvore de Decisão

Problema com CAAnimation?
├─ O manipulador de conclusão nunca dispara?
│  ├─ Apenas no simulador?
│  │  └─ O tempo do simulador é diferente (60Hz). Teste em dispositivo real.
│  ├─ Apenas no dispositivo real?
│  │  ├─ Verifique: isRemovedOnCompletion e fillMode
│  │  ├─ Verifique: encapsulamento CATransaction
│  │  └─ Verifique: app vai para segundo plano durante a animação
│  └─ Tanto no simulador quanto no dispositivo?
│     ├─ Verifique: manipulador de conclusão está definido ANTES de adicionar a animação
│     └─ Verifique: [weak self] está realmente capturado (não nil antes da conclusão)
│
├─ Incompatibilidade de duração (declarada != visual)?
│  ├─ layer.speed != 1.0?
│  │  └─ Algo escalou a duração da animação. Encontre e corrija.
│  ├─ A animação está encapsulada em CATransaction?
│  │  └─ CATransaction.setAnimationDuration() substitui animation.duration
│  └─ A duração visual é MAIOR que a declarada?
│     └─ Simulador (60Hz) vs. taxa de quadros do dispositivo (120Hz). Recalcule para hardware real.
│
├─ Física de mola errada no dispositivo?
│  ├─ Os valores estão codificados para um dispositivo?
│  │  └─ Use classe de desempenho do dispositivo, não modelo
│  ├─ Os parâmetros damping/stiffness estão trocados com mass/stiffness?
│  │  └─ Verifique os significados dos parâmetros de CASpringAnimation
│  └─ Funciona no simulador, mas não no dispositivo?
│     └─ Simulador usa 60Hz. Dispositivo pode usar 120Hz. Recalcule.
│
└─ Travamento de gesto + animação?
   ├─ As animações estão competindo (mesmo keyPath)?
   │  └─ Remova a animação antiga antes de adicionar a nova
   ├─ O gesto está atualizando a camada enquanto a animação roda?
   │  └─ Use CADisplayLink para atualizações sincronizadas
   └─ O gesto está bloqueando a thread principal?
      └─ Crie perfil com Instruments > Core Animation

Padrões Comuns

Regras de Seleção de Padrões (OBRIGATÓRIO)

Aplique UM padrão por vez, nesta ordem

  1. Sempre comece com o Padrão 1 (Básico do Manipulador de Conclusão)

    • Se a conclusão NUNCA dispara → Padrão 1
    • Verifique se a conclusão está definida ANTES de add() com print (linha 33)
    • Só prossiga para o Padrão 2 se a conclusão DISPARAR, mas o tempo estiver errado
  2. Depois, Padrão 2 (Incompatibilidade de duração CATransaction)

    • Somente se a conclusão disparar, mas o tempo decorrido != duração declarada
    • Verifique os logs dos Primeiros Passos Obrigatórios (linha 40-47)
  3. Depois, Padrão 3 (isRemovedOnCompletion)

    • Somente se a animação completar, mas o estado visual reverter
  4. Padrões 4-7 Aplique com base no sintoma específico (veja Árvore de Decisão linha 91+)

PROIBIDO

  • ❌ Aplicar múltiplos padrões ao mesmo tempo ("deixe-me tentar o Padrão 2 E o Padrão 4 juntos")
  • ❌ Pular o Padrão 1 porque "já sei que não é isso"
  • ❌ Combinar padrões sem entender por que cada um é necessário
  • ❌ Tentar padrões aleatoriamente esperando que um funcione

Padrão 1: Básico do Manipulador de Conclusão

❌ ERRADO (Manipulador definido DEPOIS de adicionar animação)

layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in  // ❌ Muito tarde!
    print("Pronto")
}

✅ CORRETO (Manipulador definido ANTES de adicionar)

animation.completion = { [weak self] finished in
    print("🔥 Animação finalizada: \(finished)")
    guard let self = self else { return }
    self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")

Por que O manipulador de conclusão deve ser definido antes que a animação seja adicionada à camada. Definir depois não faz nada.


Padrão 2: CATransaction vs. animation.duration

❌ ERRADO (CATransaction substitui a duração da animação)

CATransaction.begin()
CATransaction.setAnimationDuration(2.0)  // ❌ Substitui todas as animações!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5  // Isso é ignorado
layer.add(anim, forKey: nil)
CATransaction.commit()  // A animação leva 2.0 segundos, não 0.5

✅ CORRETO (Definir duração na animação, não na transação)

let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Sem encapsulamento CATransaction

Por que CATransaction.setAnimationDuration() afeta TODAS as animações no bloco de transação. Use-o apenas se quiser alterar todas as animações uniformemente.


Padrão 3: isRemovedOnCompletion e fillMode

❌ ERRADO (Animação desaparece após a conclusão)

let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Após 0.5s, a animação é removida E a camada reverte ao estado original

✅ CORRETO (Manter estado da animação)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // Manter estado final após a animação
layer.add(anim, forKey: nil)
// Após 0.5s, o estado da animação é preservado

Por que Por padrão, as animações são removidas e a camada reverte. Para mudanças de estado permanentes, defina isRemovedOnCompletion = false e fillMode = .forwards.


Padrão 4: Weak Self na Conclusão (OBRIGATÓRIO)

❌ PROIBIDO (Strong self cria ciclo de retenção)

anim.completion = { finished in
    self.property = "value"  // ❌ CICLO DE RETENÇÃO GARANTIDO
}

✅ OBRIGATÓRIO (Sempre usar weak self)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "value"  // Seguro para acessar
}

Por que isso é OBRIGATÓRIO, não opcional

  • CAAnimation mantém o manipulador de conclusão vivo até que a animação termine
  • O manipulador de conclusão captura self fortemente (a menos que explicitamente fraco)
  • Cria um ciclo de retenção: self → animation → completion → self
  • O vazamento de memória ocorre mesmo que a animação seja de curta duração (0,3s não o impede)

Racionalizações PROIBIDAS

  • ❌ "A animação é curta, então não há risco de ciclo de retenção"
  • ❌ "Vou remover a animação manualmente, então está tudo bem"
  • ❌ "Este caminho de código só é executado uma vez"

SEMPRE use [weak self] nos manipuladores de conclusão. Sem exceções.


Padrão 5: Múltiplas Animações (Mesmo keyPath)

❌ ERRADO (Animações em conflito)

// Adicionar animação 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")

// Mais tarde, adicionar animação 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")  // ❌ Mesma chave, substitui anim1!

✅ CORRETO (Remover antes de adicionar)

layer.removeAnimation(forKey: "slide")  // Remover antiga primeiro

let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")

Ou use chaves únicas:

let anim1 = CABasicAnimation(keyPath: "position.x")
layer.add(anim1, forKey: "slide_1")

let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2")  // Chave diferente

Por que Adicionar animação com a mesma chave substitui a animação anterior. Remova a animação antiga ou use chaves únicas.


Padrão 6: CADisplayLink para Sincronização de Gesto + Animação

❌ ERRADO (Gesto atualiza diretamente, animação atualiza em taxa diferente)

func handlePan(_ gesture: UIPanGestureRecognizer) {
    let translation = gesture.translation(in: view)
    view.layer.position.x = translation.x  // ❌ Problema de sincronização
}

// Separadamente:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // Travamento por dessincronização

✅ CORRETO (Usar CADisplayLink para sincronização)

var displayLink: CADisplayLink?

func startSyncedAnimation() {
    displayLink = CADisplayLink(
        target: self,
        selector: #selector(updateAnimation)
    )
    displayLink?.add(to: .main, forMode: .common)
}

@objc func updateAnimation() {
    // Atualizar gesto E animação no mesmo quadro
    let gesture = currentGesture
    let position = calculatePosition(from: gesture)
    layer.position = position  // Atualização sincronizada
}

Por que O reconhecedor de gestos e a CAAnimation podem rodar em taxas de quadros diferentes. CADisplayLink sincroniza ambos com a taxa de atualização da tela.


Padrão 7: Diferenças de Animação Spring Entre Dispositivos

❌ ERRADO (Codificado para um dispositivo)

let springAnim = CASpringAnimation()
springAnim.damping = 0.7  // Codificado para iPhone 15 Pro
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil)  // Travando no iPhone 12

✅ CORRETO (Adaptar ao desempenho do dispositivo)

let springAnim = CASpringAnimation()

// Usar classe de desempenho do dispositivo, não modelo
if ProcessInfo.processInfo.processorCount >= 6 {
    // Série A moderna (A14+)
    springAnim.damping = 0.7
    springAnim.stiffness = 100
} else {
    // Série A mais antiga
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

Por que A física da mola parece diferente em 60Hz vs. 120Hz. Use a classe do dispositivo (contagem de núcleos, GPU), não o modelo.


Tabela de Referência Rápida

ProblemaVerificarCorreção
Conclusão nunca disparaDefinir manipulador ANTES de add()Mover completion = antes de add()
Incompatibilidade de duraçãoHá encapsulamento CATransaction?Remover CATransaction ou remover animação dele
Travamento em dispositivos mais antigosO valor está codificado?Usar ProcessInfo para classe do dispositivo
Animação desapareceisRemovedOnCompletion?Definir para false, usar fillMode = .forwards
Travamento de gesto + animaçãoAtualizações sincronizadas?Usar CADisplayLink
Múltiplas animações em conflitoMesma chave?Usar chaves únicas ou removeAnimation() primeiro
Weak self no manipuladorA conclusão está capturada corretamente?Sempre usar [weak self] na conclusão

Quando Estiver Travado Após 30 Minutos

Se você gastou >30 minutos e a animação ainda está quebrada:

PARE. Você:

  1. Pulou uma etapa obrigatória (mais comum)
  2. Interpretou mal a saída do diagnóstico
  3. Aplicou o padrão errado para seu sintoma
  4. Está nos 5% de casos extremos que exigem perfil com Instruments

Checklist OBRIGATÓRIO antes de alegar que "a skill não funcionou"

  • Eu executei TODOS os 4 blocos de diagnóstico dos Primeiros Passos Obrigatórios (linhas 28-63)
  • Eu colei a saída EXATA dos diagnósticos (logs, prints)
  • Eu identifiquei UMA causa raiz de "O que isso te diz" (linhas 66-72)
  • Eu apliquei o PRIMEIRO padrão correspondente da Árvore de Decisão (linhas 91+)
  • Eu testei o padrão em um dispositivo REAL, não apenas no simulador
  • Eu verifiquei o padrão com prints/logs mostrando que a correção funcionou

Se TODAS as caixas estiverem marcadas e ainda estiver quebrado

  • Você DEVE criar perfil com Instruments > Core Animation
  • Custo de tempo: 30-60 minutos (inevitável para casos extremos)
  • Codificar valores, asyncAfter, ou "enviar e torcer" são PROIBIDOS
  • Peça orientação antes de adicionar qualquer solução alternativa

Transparência de custo de tempo

  • Padrão 1: 2-5 minutos
  • Padrão 2: 5-10 minutos
  • Padrão 3: 2-5 minutos
  • Padrão 4: 2 minutos (sempre aplique)
  • Padrão 5: 5-10 minutos
  • Padrão 6: 10-20 minutos
  • Padrão 7: 10-15 minutos
  • Instruments: 30-60 minutos (apenas para casos extremos)

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

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.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

Habilidades Relacionadas