Communitygithub.com

ComeOnOliver/skillshub

À utiliser lorsque le gestionnaire de fin de CAAnimation ne se déclenche pas, la physique du ressort semble incorrecte sur l'appareil, la durée de l'animation ne correspond pas au temps réel, l'interaction geste + animation provoque des à-coups, ou le timing diffère entre le simulateur et le matériel réel - diagnostic systématique de CAAnimation avec les motifs CATransaction, la connaissance du taux de rafraîchissement et le comportement spécifique à l'appareil.

Qu'est-ce que skillshub ?

Ce diagnostic systématique des animations CAAnimation aide les développeurs iOS à résoudre les problèmes courants liés aux animations Core Animation, tels que les gestionnaires de fin qui ne se déclenchent pas, les durées d'animation incorrectes, la physique des ressorts inadaptée selon l'appareil, et les à-coups lors d'interactions avec des gestes. Conçu pour les agents IA comme Claude Code, Cursor ou Codex, cette compétence fournit un arbre de décision structuré, des motifs de code corrects et incorrects, ainsi qu'une checklist obligatoire avant de modifier le code. Elle met l'accent sur le test sur des appareils réels (et non uniquement le simulateur) et l'utilisation d'Instruments pour profiler les performances. La compétence interdit explicitement les solutions de contournement comme le codage en dur des valeurs de durée, et exige l'utilisation de `[weak self]` dans les gestionnaires de fin pour éviter les cycles de rétention. Elle est adaptée à toutes les plateformes Apple (iOS, iPadOS, macOS) utilisant UIKit ou AppKit avec CAAnimation.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Débogage d'Animations UIKit

Aperçu

Les problèmes de CAAnimation se manifestent par des gestionnaires de fin manquants, un timing incorrect ou des à-coups dans des conditions spécifiques. Principe fondamental : 90 % des problèmes de CAAnimation sont dus au timing de CATransaction, à l'état de la couche ou aux hypothèses sur le taux de rafraîchissement, et non à des bogues de Core Animation.

Drapeaux Rouges — Suspecter un Problème CAAnimation

Si vous voyez L'UN de ces signes, suspectez la logique d'animation, pas le comportement de l'appareil :

  • Le gestionnaire de fin se déclenche sur le simulateur mais pas sur l'appareil
  • La durée de l'animation (0,5 s) ne correspond pas à la durée visuelle (1,2 s)
  • L'animation ressort semble correcte sur iPhone 15 Pro mais saccadée sur des appareils plus anciens
  • Geste + animation ensemble provoquent des à-coups (fonctionne bien séparément)
  • [weak self] dans le gestionnaire de fin et vous n'êtes pas sûr de la raison
  • ❌ INTERDIT : Coder en dur des durées/valeurs pour "correspondre à ce qui se passe réellement"
    • Cela introduit des bogues spécifiques à l'appareil chez des utilisateurs avec du matériel différent
    • Ne rationalisez pas cela comme une "correction temporaire" ou "assez bonne"

Distinction critique : Le simulateur cache souvent les problèmes de timing (60 Hz uniquement, pas de limitation de performance). Les appareils réels les exposent (taux de rafraîchissement variable, limitation du processeur, pression de l'arrière-plan). OBLIGATOIRE : Tester sur un appareil réel (le modèle le plus ancien pris en charge) avant de publier.

Premières Étapes Obligatoires

Exécutez TOUJOURS ces étapes en premier (avant de modifier le code) :

// 1. Vérifier si le gestionnaire de fin se déclenche
animation.completion = { [weak self] finished in
    print("🔥 GESTIONNAIRE DE FIN DÉCLENCHÉ : finished=\(finished)")
    guard let self = self else {
        print("🔥 SELF ÉTAIT NIL")
        return
    }
    // code original
}

// 2. Vérifier la durée réelle par rapport à la durée déclarée
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5  // Déclarée
layer.add(anim, forKey: "test")

DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
    print("Temps écoulé : \(Date().timeIntervalSince(startTime))")  // Réelle
}

// 3. Vérifier les animations actives
if let keys = layer.animationKeys() {
    print("Animations actives : \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key) : durée=\(anim.duration), supprimée=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. Vérifier l'état de la couche
print("Vitesse de la couche : \(layer.speed)")  // != 1.0 signifie que le timing est modifié
print("Décalage temporel de la couche : \(layer.timeOffset)")  // != 0 signifie que l'animation est décalée

Ce que cela vous indique

  • L'impression du gestionnaire de fin apparaît → Le gestionnaire se déclenche, le problème est dans le code de rappel
  • L'impression du gestionnaire de fin est absente → Le gestionnaire ne se déclenche pas, vérifier CATransaction/état de la couche
  • Temps écoulé == durée déclarée → La durée est correcte, les à-coups visuels sont dus aux trames
  • Temps écoulé != durée déclarée → L'encapsulation CATransaction modifie la durée
  • layer.speed != 1.0 → Quelque chose ralentit l'animation
  • La liste des animations actives est longue → Plusieurs animations en compétition

INTERPRÉTATION OBLIGATOIRE

Avant de modifier DU code, vous devez identifier LE diagnostic unique qui est la cause racine :

  1. Si le gestionnaire de fin se déclenche mais que le temps écoulé != durée déclarée → Appliquer le Motif 2 (CATransaction)
  2. Si le gestionnaire de fin ne se déclenche PAS ET isRemovedOnCompletion est vrai → Appliquer le Motif 3
  3. Si le gestionnaire de fin se déclenche mais que le visuel est saccadé → DOIT profiler avec Instruments en premier
    • Vous ne pouvez pas deviner "c'est probablement les trames" - prouvez-le avec des données
    • Profiler > Instrument Core Animation montre les chutes de trames avec certitude
    • Si vous sautez Instruments, vous devinez

Si les diagnostics sont contradictoires ou peu clairs

  • ARRÊTEZ. Ne passez pas encore aux motifs
  • Ajoutez plus d'instructions print pour cerner la cause
  • Demandez : "Les diagnostics montrent X et Y mais Z ne correspond pas. Qu'est-ce que je manque ?"
  • Profiler avec Instruments > Core Animation si vous n'êtes pas sûr

Arbre de Décision

Problème CAAnimation ?
├─ Le gestionnaire de fin ne se déclenche jamais ?
│  ├─ Uniquement sur le simulateur ?
│  │  └─ Le timing du simulateur est différent (60 Hz). Testez sur un appareil réel.
│  ├─ Uniquement sur l'appareil réel ?
│  │  ├─ Vérifier : isRemovedOnCompletion et fillMode
│  │  ├─ Vérifier : encapsulation CATransaction
│  │  └─ Vérifier : l'application passe en arrière-plan pendant l'animation
│  └─ À la fois sur simulateur et appareil ?
│     ├─ Vérifier : le gestionnaire de fin est défini AVANT d'ajouter l'animation
│     └─ Vérifier : [weak self] est réellement capturé (pas nil avant la fin)
│
├─ Décalage de durée (déclarée != visuelle) ?
│  ├─ layer.speed != 1.0 ?
│  │  └─ Quelque chose a modifié la durée de l'animation. Trouvez et corrigez.
│  ├─ L'animation est encapsulée dans CATransaction ?
│  │  └─ CATransaction.setAnimationDuration() remplace animation.duration
│  └─ La durée visuelle est PLUS LONGUE que la durée déclarée ?
│     └─ Simulateur (60 Hz) vs taux de rafraîchissement de l'appareil (120 Hz). Recalculez pour le matériel réel.
│
├─ Physique du ressort incorrecte sur l'appareil ?
│  ├─ Les valeurs sont codées en dur pour un appareil ?
│  │  └─ Utilisez la classe de performance de l'appareil, pas le modèle
│  ├─ Les paramètres d'amortissement/rigidité sont échangés avec masse/rigidité ?
│  │  └─ Vérifiez la signification des paramètres de CASpringAnimation
│  └─ Fonctionne sur le simulateur mais pas sur l'appareil ?
│     └─ Le simulateur utilise 60 Hz. L'appareil peut utiliser 120 Hz. Recalculez.
│
└─ À-coups geste + animation ?
   ├─ Les animations sont en compétition (même keyPath) ?
   │  └─ Supprimez l'ancienne animation avant d'en ajouter une nouvelle
   ├─ Le geste met à jour la couche pendant que l'animation s'exécute ?
   │  └─ Utilisez CADisplayLink pour des mises à jour synchronisées
   └─ Le geste bloque le thread principal ?
      └─ Profiler avec Instruments > Core Animation

Motifs Courants

Règles de Sélection des Motifs (OBLIGATOIRE)

Appliquez UN motif à la fois, dans cet ordre

  1. Commencez toujours par le Motif 1 (Bases du Gestionnaire de Fin)

    • Si le gestionnaire de fin ne se déclenche JAMAIS → Motif 1
    • Vérifiez que le gestionnaire de fin est défini AVANT add() avec une instruction print (ligne 33)
    • Passez au Motif 2 uniquement si le gestionnaire de fin se DÉCLENCHE mais que le timing est incorrect
  2. Puis Motif 2 (Décalage de durée CATransaction)

    • Uniquement si le gestionnaire de fin se déclenche mais que le temps écoulé != durée déclarée
    • Vérifiez les logs des Premières Étapes Obligatoires (ligne 40-47)
  3. Puis Motif 3 (isRemovedOnCompletion)

    • Uniquement si l'animation se termine mais que l'état visuel revient en arrière
  4. Motifs 4-7 Appliquez en fonction du symptôme spécifique (voir Arbre de Décision ligne 91+)

INTERDIT

  • ❌ Appliquer plusieurs motifs à la fois ("laissez-moi essayer le Motif 2 ET le Motif 4 ensemble")
  • ❌ Sauter le Motif 1 parce que "je sais déjà que ce n'est pas ça"
  • ❌ Combiner des motifs sans comprendre pourquoi chacun est nécessaire
  • ❌ Essayer des motifs au hasard en espérant que l'un fonctionne

Motif 1 : Bases du Gestionnaire de Fin

❌ INCORRECT (Gestionnaire défini APRÈS avoir ajouté l'animation)

layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in  // ❌ Trop tard !
    print("Terminé")
}

✅ CORRECT (Gestionnaire défini AVANT d'ajouter)

animation.completion = { [weak self] finished in
    print("🔥 Animation terminée : \(finished)")
    guard let self = self else { return }
    self.doNextStep()
}
layer.add(animation, forKey: "myAnimation")

Pourquoi Le gestionnaire de fin doit être défini avant que l'animation ne soit ajoutée à la couche. Le définir après ne fait rien.


Motif 2 : CATransaction vs animation.duration

❌ INCORRECT (CATransaction remplace la durée de l'animation)

CATransaction.begin()
CATransaction.setAnimationDuration(2.0)  // ❌ Remplace toutes les animations !
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5  // Ceci est ignoré
layer.add(anim, forKey: nil)
CATransaction.commit()  // L'animation prend 2,0 secondes, pas 0,5

✅ CORRECT (Définir la durée sur l'animation, pas sur la transaction)

let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Pas d'encapsulation CATransaction

Pourquoi CATransaction.setAnimationDuration() affecte TOUTES les animations dans le bloc de transaction. Utilisez-le uniquement si vous souhaitez modifier uniformément toutes les animations.


Motif 3 : isRemovedOnCompletion et fillMode

❌ INCORRECT (L'animation disparaît après la fin)

let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// Après 0,5 s, l'animation est supprimée ET la couche revient à son état d'origine

✅ CORRECT (Conserver l'état de l'animation)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // Conserver l'état final après l'animation
layer.add(anim, forKey: nil)
// Après 0,5 s, l'état de l'animation est préservé

Pourquoi Par défaut, les animations sont supprimées et la couche revient en arrière. Pour les changements d'état permanents, définissez isRemovedOnCompletion = false et fillMode = .forwards.


Motif 4 : Weak Self dans le Gestionnaire de Fin (OBLIGATOIRE)

❌ INTERDIT (Strong self crée un cycle de rétention)

anim.completion = { finished in
    self.property = "valeur"  // ❌ Cycle de rétention GARANTI
}

✅ OBLIGATOIRE (Toujours utiliser weak self)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "valeur"  // Sécurisé d'accéder
}

Pourquoi c'est OBLIGATOIRE, pas optionnel

  • CAAnimation garde le gestionnaire de fin actif jusqu'à la fin de l'animation
  • Le gestionnaire de fin capture self fortement (sauf si explicitement weak)
  • Crée un cycle de rétention : self → animation → complétion → self
  • La fuite mémoire se produit même si l'animation est de courte durée (0,3 s ne l'empêche pas)

Rationalisations INTERDITES

  • ❌ "L'animation est courte, donc pas de risque de cycle de rétention"
  • ❌ "Je vais supprimer l'animation manuellement, donc ça va"
  • ❌ "Ce chemin de code ne s'exécute qu'une seule fois"

Utilisez TOUJOURS [weak self] dans les gestionnaires de fin. Aucune exception.


Motif 5 : Animations Multiples (Même keyPath)

❌ INCORRECT (Les animations entrent en conflit)

// Ajouter l'animation 1
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")

// Plus tard, ajouter l'animation 2
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")  // ❌ Même clé, remplace anim1 !

✅ CORRECT (Supprimer avant d'ajouter)

layer.removeAnimation(forKey: "slide")  // Supprimer d'abord l'ancienne

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

Ou utilisez des clés uniques :

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

let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2")  // Clé différente

Pourquoi Ajouter une animation avec la même clé remplace l'animation précédente. Soit supprimez l'ancienne animation, soit utilisez des clés uniques.


Motif 6 : CADisplayLink pour la Synchronisation Geste + Animation

❌ INCORRECT (Le geste met à jour directement, l'animation met à jour à un taux différent)

func handlePan(_ gesture: UIPanGestureRecognizer) {
    let translation = gesture.translation(in: view)
    view.layer.position.x = translation.x  // ❌ Problème de synchronisation
}

// Séparément :
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // À-coups dus à la désynchronisation

✅ CORRECT (Utiliser CADisplayLink pour la synchronisation)

var displayLink: CADisplayLink?

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

@objc func updateAnimation() {
    // Mettre à jour le geste ET l'animation dans la même trame
    let gesture = currentGesture
    let position = calculatePosition(from: gesture)
    layer.position = position  // Mise à jour synchronisée
}

Pourquoi Le reconnaisseur de geste et CAAnimation peuvent s'exécuter à des taux de rafraîchissement différents. CADisplayLink synchronise les deux avec le taux de rafraîchissement de l'écran.


Motif 7 : Différences d'Animation Ressort selon l'Appareil

❌ INCORRECT (Codé en dur pour un appareil)

let springAnim = CASpringAnimation()
springAnim.damping = 0.7  // Codé en dur pour iPhone 15 Pro
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil)  // Saccadé sur iPhone 12

✅ CORRECT (Adapter à la performance de l'appareil)

let springAnim = CASpringAnimation()

// Utiliser la classe de performance de l'appareil, pas le modèle
if ProcessInfo.processInfo.processorCount >= 6 {
    // Série A moderne (A14+)
    springAnim.damping = 0.7
    springAnim.stiffness = 100
} else {
    // Série A plus ancienne
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

Pourquoi La physique du ressort se sent différente à 60 Hz vs 120 Hz. Utilisez la classe de l'appareil (nombre de cœurs, GPU) pas le modèle.


Tableau de Référence Rapide

ProblèmeVérifierCorriger
Le gestionnaire de fin ne se déclenche jamaisDéfinir le gestionnaire AVANT add()Déplacer completion = avant add()
Décalage de duréeEncapsulation CATransaction ?Supprimer CATransaction ou retirer l'animation de celle-ci
À-coups sur les anciens appareilsValeur codée en dur ?Utiliser ProcessInfo pour la classe de l'appareil
L'animation disparaîtisRemovedOnCompletion ?Définir sur false, utiliser fillMode = .forwards
À-coups geste + animationMises à jour synchronisées ?Utiliser CADisplayLink
Conflit d'animations multiplesMême clé ?Utiliser des clés uniques ou removeAnimation() d'abord
Weak self dans le gestionnaireGestionnaire de fin capturé correctement ?Toujours utiliser [weak self] dans le gestionnaire de fin

Quand Vous Êtes Bloqué Après 30 Minutes

Si vous avez passé >30 minutes et que l'animation est toujours cassée :

ARRÊTEZ. Soit vous

  1. Avez sauté une étape obligatoire (le plus courant)
  2. Avez mal interprété la sortie de diagnostic
  3. Avez appliqué le mauvais motif pour votre symptôme
  4. Êtes dans le cas limite de 5 % nécessitant un profilage avec Instruments

Checklist OBLIGATOIRE avant de prétendre "la compétence n'a pas fonctionné"

  • J'ai exécuté TOUS les 4 blocs de diagnostic des Premières Étapes Obligatoires (lignes 28-63)
  • J'ai collé la sortie EXACTE des diagnostics (logs, instructions print)
  • J'ai identifié UNE cause racine à partir de "Ce que cela vous indique" (lignes 66-72)
  • J'ai appliqué le PREMIER motif correspondant de l'Arbre de Décision (lignes 91+)
  • J'ai testé le motif sur un APPAREIL RÉEL, pas seulement le simulateur
  • J'ai vérifié le motif avec des instructions print/logs montrant que la correction fonctionne

Si TOUTES les cases sont cochées et toujours cassé

  • Vous DEVEZ profiler avec Instruments > Core Animation
  • Coût en temps : 30 à 60 minutes (inévitable pour les cas limites)
  • Coder en dur, asyncAfter, ou "publier et espérer" sont INTERDITS
  • Demandez des conseils avant d'ajouter des solutions de contournement

Transparence du coût en temps

  • Motif 1 : 2-5 min

… [le reste du contenu est tronqué pour la traduction]

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 associés