Communitygithub.com

ComeOnOliver/skillshub

Úsalo cuando el manejador de finalización de CAAnimation no se ejecute, la física de resortes se vea incorrecta en el dispositivo, la duración de la animación no coincida con el tiempo real, la interacción gesto + animación cause tirones o el tiempo difiera entre el simulador y el hardware real: diagnóstico sistemático de CAAnimation con patrones de CATransaction, conciencia de la tasa de fotogramas y comportamiento específico del dispositivo.

¿Qué es skillshub?

Esta habilidad proporciona un enfoque sistemático y basado en diagnóstico para depurar problemas de CAAnimation en UIKit. Se enfoca en el principio central de que el 90% de los problemas de animación se deben a errores en la lógica de desarrollo (como el tiempo de CATransaction, el estado de la capa o suposiciones sobre la tasa de fotogramas), y no a fallos reales de Core Animation. La habilidad guía a los desarrolladores a través de pasos de diagnóstico obligatorios, como verificar la ejecución del manejador de finalización, medir la duración real de la animación, inspeccionar las animaciones activas en una capa y comprobar el estado de la capa, antes de modificar cualquier código. Incluye un árbol de decisión para identificar la causa raíz en función de síntomas específicos (por ejemplo, el manejador de finalización nunca se ejecuta, discrepancia de duración, física incorrecta de resortes, tirones con gestos) y aplica patrones de solución comunes en un orden estricto, comenzando siempre por el Patrón 1 (Conceptos básicos del manejador de finalización). El flujo de trabajo prohíbe aplicar múltiples patrones a la vez, saltarse pasos o solucionar problemas con valores codificados. También exige realizar pruebas en un dispositivo real antes de enviar el código y, si es necesario, usar Instruments para la creación de perfiles de Core Animation en casos complejos. La habilidad está diseñada para plataformas Apple (iOS, macOS, etc.) con UIKit y Core Animation.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Depuración de Animaciones UIKit

Descripción general

Los problemas de CAAnimation se manifiestan como manejadores de finalización faltantes, tiempos incorrectos o tirones bajo condiciones específicas. Principio fundamental: el 90% de los problemas de CAAnimation se deben al tiempo de CATransaction, el estado de la capa o suposiciones sobre la tasa de fotogramas, no a errores de Core Animation.

Señales de alerta: sospechar un problema de CAAnimation

Si ves CUALQUIERA de estas señales, sospecha que es un problema de lógica de animación, no de comportamiento del dispositivo:

  • El manejador de finalización se ejecuta en el simulador pero no en el dispositivo
  • La duración de la animación (0.5s) no coincide con la duración visual (1.2s)
  • La animación con resorte se ve correcta en iPhone 15 Pro pero entrecortada en dispositivos más antiguos
  • La combinación de gesto + animación causa tartamudeo (por separado funciona bien)
  • Usas [weak self] en el manejador de finalización y no estás seguro de por qué
  • ❌ PROHIBIDO: Codificar duraciones/valores para "que coincidan con lo que realmente sucede"
    • Esto envía errores específicos del dispositivo a usuarios con hardware diferente
    • No justifiques esto como una "solución temporal" o "suficientemente buena"

Distinción crítica: el simulador a menudo oculta problemas de tiempo (solo 60Hz, sin limitación). Los dispositivos reales los exponen (tasa de fotogramas variable, limitación de CPU, presión en segundo plano). OBLIGATORIO: probar en un dispositivo real (el modelo más antiguo compatible) antes de enviar.

Pasos obligatorios iniciales

SIEMPRE ejecuta estos PRIMERO (antes de cambiar el código):

// 1. Verificar si la finalización se está ejecutando
animation.completion = { [weak self] finished in
    print("🔥 FINALIZACIÓN EJECUTADA: finished=\(finished)")
    guard let self = self else {
        print("🔥 SELF ERA NIL")
        return
    }
    // código original
}

// 2. Verificar la duración real vs. la 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("Tiempo transcurrido: \(Date().timeIntervalSince(startTime))")  // Real
}

// 3. Verificar qué animaciones están activas
if let keys = layer.animationKeys() {
    print("Animaciones activas: \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key): duración=\(anim.duration), eliminada=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. Verificar el estado de la capa
print("Velocidad de la capa: \(layer.speed)")  // != 1.0 significa que el tiempo está escalado
print("Desplazamiento de tiempo de la capa: \(layer.timeOffset)")  // != 0 significa que la animación está desplazada

Qué te dice esto

  • Aparece el print de finalización → El manejador se ejecuta, el problema está en el código de callback
  • Falta el print de finalización → El manejador no se ejecuta, verifica CATransaction/estado de la capa
  • Tiempo transcurrido == declarado → La duración es correcta, el tirón visual se debe a los fotogramas
  • Tiempo transcurrido != declarado → El envoltorio de CATransaction está cambiando la duración
  • layer.speed != 1.0 → Algo está ralentizando la animación
  • La lista de animaciones activas es larga → Múltiples animaciones compitiendo

INTERPRETACIÓN OBLIGATORIA

Antes de cambiar CUALQUIER código, debes identificar CUÁL diagnóstico es la causa raíz:

  1. Si la finalización se ejecuta pero el tiempo transcurrido != duración declarada → Aplicar Patrón 2 (CATransaction)
  2. Si la finalización no se ejecuta Y isRemovedOnCompletion es true → Aplicar Patrón 3
  3. Si la finalización se ejecuta pero lo visual es entrecortado → DEBES perfilar con Instruments primero
    • No puedes adivinar "probablemente son los fotogramas" - demuéstralo con datos
    • Perfil > Instrumento Core Animation muestra las caídas de fotogramas con certeza
    • Si omites Instruments, estás adivinando

Si los diagnósticos son contradictorios o poco claros

  • DETENTE. No procedas a los patrones todavía
  • Agrega más declaraciones print para reducir la causa
  • Pregunta: "Los diagnósticos muestran X e Y pero Z no coincide. ¿Qué me estoy perdiendo?"
  • Perfila con Instruments > Core Animation si no estás seguro

Árbol de decisión

¿Problema de CAAnimation?
├─ ¿El manejador de finalización nunca se ejecuta?
│  ├─ ¿Solo en el simulador?
│  │  └─ El tiempo del simulador es diferente (60Hz). Prueba en un dispositivo real.
│  ├─ ¿Solo en el dispositivo real?
│  │  ├─ Verificar: isRemovedOnCompletion y fillMode
│  │  ├─ Verificar: envoltorio de CATransaction
│  │  └─ Verificar: la aplicación pasa a segundo plano durante la animación
│  └─ ¿En simulador y dispositivo?
│     ├─ Verificar: el manejador de finalización se establece ANTES de agregar la animación
│     └─ Verificar: [weak self] realmente se captura (no es nil antes de la finalización)
│
├─ ¿Discrepancia de duración (declarada != visual)?
│  ├─ ¿layer.speed != 1.0?
│  │  └─ Algo escaló la duración de la animación. Encuéntralo y arréglalo.
│  ├─ ¿La animación está envuelta en CATransaction?
│  │  └─ CATransaction.setAnimationDuration() anula animation.duration
│  └─ ¿La duración visual es MÁS LARGA que la declarada?
│     └─ Simulador (60Hz) vs. tasa de fotogramas del dispositivo (120Hz). Recalcula para hardware real.
│
├─ ¿Física de resortes incorrecta en el dispositivo?
│  ├─ ¿Los valores están codificados para un dispositivo?
│  │  └─ Usa la clase de rendimiento del dispositivo, no el modelo
│  ├─ ¿La amortiguación/rigidez están intercambiadas con masa/rigidez?
│  │  └─ Verifica los significados de los parámetros de CASpringAnimation
│  └─ ¿Funciona en el simulador pero no en el dispositivo?
│     └─ El simulador usa 60Hz. El dispositivo puede usar 120Hz. Recalcula.
│
└─ ¿Tirones de gesto + animación?
   ├─ ¿Las animaciones compiten (mismo keyPath)?
   │  └─ Elimina la animación antigua antes de agregar la nueva
   ├─ ¿El gesto actualiza la capa mientras se ejecuta la animación?
   │  └─ Usa CADisplayLink para actualizaciones sincronizadas
   └─ ¿El gesto bloquea el hilo principal?
      └─ Perfila con Instruments > Core Animation

Patrones comunes

Reglas de selección de patrones (OBLIGATORIO)

Aplica UN patrón a la vez, en este orden

  1. Siempre comienza con el Patrón 1 (Conceptos básicos del manejador de finalización)

    • Si la finalización NUNCA se ejecuta → Patrón 1
    • Verifica que la finalización se establezca ANTES de add() con una declaración print (línea 33)
    • Solo procede al Patrón 2 si la finalización SE EJECUTA pero el tiempo es incorrecto
  2. Luego Patrón 2 (Discrepancia de duración de CATransaction)

    • Solo si la finalización se ejecuta pero el tiempo transcurrido != duración declarada
    • Verifica los registros de los Pasos obligatorios iniciales (línea 40-47)
  3. Luego Patrón 3 (isRemovedOnCompletion)

    • Solo si la animación se completa pero el estado visual revierte
  4. Patrones 4-7 Aplica según el síntoma específico (ver Árbol de decisión, línea 91+)

PROHIBIDO

  • ❌ Aplicar múltiples patrones a la vez ("déjame probar el Patrón 2 Y el Patrón 4 juntos")
  • ❌ Saltarse el Patrón 1 porque "ya sé que no es eso"
  • ❌ Combinar patrones sin entender por qué se necesita cada uno
  • ❌ Probar patrones al azar con la esperanza de que uno funcione

Patrón 1: Conceptos básicos del manejador de finalización

❌ INCORRECTO (Manejador establecido DESPUÉS de agregar la animación)

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

✅ CORRECTO (Manejador establecido ANTES de agregar)

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

Por qué: El manejador de finalización debe establecerse antes de agregar la animación a la capa. Establecerlo después no hace nada.


Patrón 2: CATransaction vs. animation.duration

❌ INCORRECTO (CATransaction anula la duración de la animación)

CATransaction.begin()
CATransaction.setAnimationDuration(2.0)  // ❌ ¡Anula todas las animaciones!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5  // Esto se ignora
layer.add(anim, forKey: nil)
CATransaction.commit()  // La animación tarda 2.0 segundos, no 0.5

✅ CORRECTO (Establecer la duración en la animación, no en la transacción)

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

Por qué: CATransaction.setAnimationDuration() afecta a TODAS las animaciones dentro del bloque de transacción. Úsalo solo si deseas cambiar todas las animaciones de manera uniforme.


Patrón 3: isRemovedOnCompletion y fillMode

❌ INCORRECTO (La animación desaparece después de completarse)

let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Después de 0.5s, la animación se elimina Y la capa vuelve a su estado original

✅ CORRECTO (Mantener el estado de la animación)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // Mantener el estado final después de la animación
layer.add(anim, forKey: nil)
// Después de 0.5s, el estado de la animación se conserva

Por qué: De forma predeterminada, las animaciones se eliminan y la capa revierte. Para cambios de estado permanentes, establece isRemovedOnCompletion = false y fillMode = .forwards.


Patrón 4: Weak Self en la finalización (OBLIGATORIO)

❌ PROHIBIDO (Self fuerte crea un ciclo de retención)

anim.completion = { finished in
    self.property = "valor"  // ❌ Ciclo de retención GARANTIZADO
}

✅ OBLIGATORIO (Usar siempre weak self)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "valor"  // Seguro de acceder
}

Por qué esto es OBLIGATORIO, no opcional

  • CAAnimation mantiene vivo el manejador de finalización hasta que la animación se completa
  • El manejador de finalización captura self fuertemente (a menos que sea explícitamente weak)
  • Crea un ciclo de retención: self → animación → finalización → self
  • La fuga de memoria ocurre incluso si la animación es de corta duración (0.3s no lo previene)

Racionalizaciones PROHIBIDAS

  • ❌ "La animación es corta, así que no hay riesgo de ciclo de retención"
  • ❌ "Eliminaré la animación manualmente, así que está bien"
  • ❌ "Esta ruta de código solo se ejecuta una vez"

SIEMPRE usa [weak self] en los manejadores de finalización. Sin excepciones.


Patrón 5: Múltiples animaciones (Mismo keyPath)

❌ INCORRECTO (Las animaciones entran en conflicto)

// Agregar animación 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")

// Más tarde, agregar animación 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")  // ❌ Misma clave, ¡reemplaza anim1!

✅ CORRECTO (Eliminar antes de agregar)

layer.removeAnimation(forKey: "slide")  // Eliminar la antigua primero

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

O usar claves ú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")  // Clave diferente

Por qué: Agregar una animación con la misma clave reemplaza la animación anterior. Elimina la animación anterior o usa claves únicas.


Patrón 6: CADisplayLink para sincronización de gesto + animación

❌ INCORRECTO (El gesto actualiza directamente, la animación actualiza a una velocidad diferente)

func handlePan(_ gesture: UIPanGestureRecognizer) {
    let translation = gesture.translation(in: view)
    view.layer.position.x = translation.x  // ❌ Problema de sincronización
}

// Por separado:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // Tirón por desincronización

✅ CORRECTO (Usar CADisplayLink para la sincronización)

var displayLink: CADisplayLink?

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

@objc func updateAnimation() {
    // Actualizar gesto Y animación en el mismo fotograma
    let gesture = currentGesture
    let position = calculatePosition(from: gesture)
    layer.position = position  // Actualización sincronizada
}

Por qué: El reconocedor de gestos y CAAnimation pueden ejecutarse a diferentes velocidades de fotograma. CADisplayLink sincroniza ambos con la velocidad de actualización de la pantalla.


Patrón 7: Diferencias de animación con resorte entre dispositivos

❌ INCORRECTO (Codificado para un dispositivo)

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

✅ CORRECTO (Adaptar al rendimiento del dispositivo)

let springAnim = CASpringAnimation()

// Usar la clase de rendimiento del dispositivo, no el modelo
if ProcessInfo.processInfo.processorCount >= 6 {
    // A-series moderna (A14+)
    springAnim.damping = 0.7
    springAnim.stiffness = 100
} else {
    // A-series antigua
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

Por qué: La física de resortes se siente diferente a 60Hz vs. 120Hz. Usa la clase de dispositivo (número de núcleos, GPU) no el modelo.


Tabla de referencia rápida

ProblemaVerificarSolución
La finalización nunca se ejecutaEstablecer el manejador ANTES de add()Mover completion = antes de add()
Discrepancia de duración¿Está envuelto en CATransaction?Eliminar CATransaction o eliminar la animación de él
Tirón en dispositivos antiguos¿Está el valor codificado?Usar ProcessInfo para la clase de dispositivo
La animación desaparece¿isRemovedOnCompletion?Establecer a false, usar fillMode = .forwards
Tirón de gesto + animación¿Actualizaciones sincronizadas?Usar CADisplayLink
Conflicto de múltiples animaciones¿Misma clave?Usar claves únicas o removeAnimation() primero
Weak self en el manejador¿Finalización capturada correctamente?Siempre usar [weak self] en la finalización

Cuando estés atascado después de 30 minutos

Si has pasado >30 minutos y la animación sigue sin funcionar:

DETENTE. O bien:

  1. Te saltaste un paso obligatorio (lo más común)
  2. Malinterpretaste la salida del diagnóstico
  3. Aplicaste el patrón incorrecto para tu síntoma
  4. Estás en el 5% de casos extremos que requieren creación de perfiles con Instruments

Lista de verificación OBLIGATORIA antes de afirmar "la habilidad no funcionó"

  • Ejecuté TODOS los 4 bloques de diagnóstico de los Pasos obligatorios iniciales (líneas 28-63)
  • Pegué la salida EXACTA de los diagnósticos (registros, declaraciones print)
  • Identifiqué UNA causa raíz de "Qué te dice esto" (líneas 66-72)
  • Apliqué el PRIMER patrón coincidente del Árbol de decisión (líneas 91+)
  • Probé el patrón en un dispositivo REAL, no solo en el simulador
  • Verifiqué el patrón con declaraciones print/registros que muestran que la solución funcionó

Si TODAS las casillas están marcadas y aún no funciona

  • DEBES perfilar con Instruments > Core Animation
  • Costo de tiempo: 30-60 minutos (inevitable para casos extremos)
  • Codificar, asyncAfter o "enviar y esperar" están PROHIBIDOS
  • Pide orientación antes de agregar cualquier solución alternativa

Transparencia del costo de tiempo

  • Patrón 1: 2-5 minutos
  • Patrón 2: 2-5 minutos
  • Patrón 3: 2-5 minutos
  • Patrón 4: 2-5 minutos
  • Patrón 5: 2-5 minutos
  • Patrón 6: 2-5 minutos
  • Patrón 7: 2-5 minutos
  • Instruments > Core Animation: 30-60 minutos

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

Skills relacionados