Communitygithub.com

ComeOnOliver/skillshub

CAAnimationの完了ハンドラが発火しない、スプリング物理がデバイス上でおかしく見える、アニメーション時間が実時間と一致しない、ジェスチャーとアニメーションの相互作用でカクつく、シミュレータと実機でタイミングが異なる場合などに、CATransactionパターン、フレームレート認識、デバイス固有の動作を用いて体系的なCAAnimation診断を行います。

skillshub とは?

このスキルは、iOS開発におけるCAAnimation関連の問題を体系的に診断し解決するためのものです。CAAnimationの問題の90%はCore Animationのバグではなく、CATransactionのタイミング、レイヤーの状態、またはフレームレートの誤った前提に起因するという原則に基づいています。ユーザーはまず、完了ハンドラの動作確認、実際の経過時間と宣言された時間の比較、アクティブなアニメーションのリスト、レイヤーの速度とタイムオフセットをチェックする4つの必須診断手順を実行します。これらの診断結果をもとに、アニメーション特有の症状に合わせて7つのパターン(完了ハンドラの基本設定、CATransactionとアニメーション時間の競合、isRemovedOnCompletionとfillMode、弱い参照の自己キャプチャ、同一キーパスでの複数アニメーション、ジェスチャーとアニメーションの同期、スプリングアニメーションのデバイス間差)から1つを選択して適用します。シミュレータでは60Hz固定で動作するためタイミング問題が隠蔽されることが多い一方、実機では可変フレームレートやCPUスロットリングによる問題が顕在化するため、出荷前には必ず実機(サポート対象中最も古いモデル)でのテストが必須です。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

UIKitアニメーションデバッグ

概要

CAAnimationの問題は、完了ハンドラの欠落、タイミングの誤差、特定条件下でのカクつきとして現れます。基本原則: CAAnimationの問題の90%は、CATransactionのタイミング、レイヤーの状態、またはフレームレートの誤った前提に起因し、Core Animationのバグではありません。

警告サイン — CAAnimationの問題を疑う

以下のいずれかが見られた場合、デバイスの動作ではなくアニメーションロジックを疑ってください:

  • 完了ハンドラがシミュレータでは発火するが、デバイスでは発火しない
  • アニメーション時間(0.5秒)が実際の見た目の時間(1.2秒)と一致しない
  • スプリングアニメーションがiPhone 15 Proでは正しく見えるが、古いデバイスではカクつく
  • ジェスチャーとアニメーションを同時に行うとスタッターが発生する(個別では問題ない)
  • 完了ハンドラ内で [weak self] を使っているが、その理由がわからない
  • ❌ 禁止: 「実際に起こること」に合わせて時間や値をハードコーディングすること
    • これにより、異なるハードウェアを使用するユーザーにデバイス固有のバグを出荷することになります
    • これを「一時的な修正」や「十分に良い」と合理化してはいけません

重要な区別: シミュレータはタイミング問題を隠蔽することがよくあります(60Hz固定、スロットリングなし)。実機ではそれらが露呈します(可変フレームレート、CPUスロットリング、バックグラウンドプレッシャー)。必須: 出荷前に、サポート対象中最も古いモデルの実機でテストしてください。

必須の最初のステップ

常にこれらを最初に実行してください(コードを変更する前):

// 1. 完了が発火しているか確認
animation.completion = { [weak self] finished in
    print("🔥 COMPLETION FIRED: finished=\(finished)")
    guard let self = self else {
        print("🔥 SELF WAS NIL")
        return
    }
    // 元のコード
}

// 2. 実際の時間と宣言された時間を比較
let startTime = Date()
let anim = CABasicAnimation(keyPath: "position.x")
anim.duration = 0.5  // 宣言
layer.add(anim, forKey: "test")

DispatchQueue.main.asyncAfter(deadline: .now() + 0.51) {
    print("経過時間: \(Date().timeIntervalSince(startTime))")  // 実際
}

// 3. アクティブなアニメーションを確認
if let keys = layer.animationKeys() {
    print("アクティブなアニメーション: \(keys)")
    for key in keys {
        if let anim = layer.animation(forKey: key) {
            print("\(key): duration=\(anim.duration), removed=\(anim.isRemovedOnCompletion)")
        }
    }
}

// 4. レイヤーの状態を確認
print("Layer speed: \(layer.speed)")  // != 1.0 はタイミングが変更されていることを示す
print("Layer timeOffset: \(layer.timeOffset)")  // != 0 はアニメーションがオフセットされていることを示す

これからわかること

  • 完了プリントが表示される → ハンドラは発火している。問題はコールバックコードにある
  • 完了プリントが表示されない → ハンドラが発火していない。CATransaction/レイヤーの状態を確認
  • 経過時間 == 宣言時間 → 時間は正しい。見た目のカクつきはフレームの問題
  • 経過時間 != 宣言時間 → CATransactionのラップが時間を変更している
  • layer.speed != 1.0 → 何かがアニメーションを遅くしている
  • アクティブなアニメーションリストが長い → 複数のアニメーションが競合している

必須の解釈

コードを変更する前に、どの1つの診断が根本原因かを特定する必要があります:

  1. 完了が発火するが経過時間 != 宣言時間の場合 → パターン2(CATransaction)を適用
  2. 完了が発火しないかつ isRemovedOnCompletion が true の場合 → パターン3を適用
  3. 完了は発火するが見た目がカクつく場合 → 最初にInstrumentsでプロファイリングする必要があります
    • 「たぶんフレームの問題だ」と推測してはいけません。データで証明してください
    • プロファイル > Core Animation インストゥルメントでフレームドロップを確実に特定できます
    • Instrumentsをスキップするなら、それは推測です

診断結果が矛盾している、または不明瞭な場合

  • 停止してください。まだパターンに進まないでください
  • 原因を絞り込むために、さらにprint文を追加してください
  • 自問してください: 「診断結果はXとYを示しているが、Zが一致しない。何を見落としているのか?」
  • 不明な場合は、Instruments > Core Animationでプロファイリングしてください

決定木

CAAnimationの問題?
├─ 完了ハンドラが発火しない?
│  ├─ シミュレータのみ?
│  │  └─ シミュレータのタイミングは異なる(60Hz)。実機でテストしてください。
│  ├─ 実機のみ?
│  │  ├─ 確認: isRemovedOnCompletion と fillMode
│  │  ├─ 確認: CATransactionのラップ
│  │  └─ 確認: アニメーション中にアプリがバックグラウンドに移動していないか
│  └─ シミュレータと実機の両方?
│     ├─ 確認: 完了ハンドラがアニメーションの追加**前**に設定されているか
│     └─ 確認: [weak self] が実際にキャプチャされているか(完了前にnilになっていないか)
│
├─ 時間の不一致(宣言 != 見た目)?
│  ├─ layer.speed != 1.0 か?
│  │  └─ 何かがアニメーション時間を変更した。見つけて修正してください。
│  ├─ アニメーションがCATransactionでラップされているか?
│  │  └─ CATransaction.setAnimationDuration() は animation.duration を上書きします
│  └─ 見た目の時間が宣言よりも**長い**か?
│     └─ シミュレータ(60Hz)とデバイスのフレームレート(120Hz)の違い。実機用に再計算してください。
│
├─ スプリング物理がデバイスでおかしい?
│  ├─ 値が1つのデバイス用にハードコーディングされているか?
│  │  └─ モデルではなく、デバイスのパフォーマンスクラスを使用してください
│  ├─ damping/stiffness の値が mass/stiffness と入れ替わっていないか?
│  │  └─ CASpringAnimationパラメータの意味を確認
│  └─ シミュレータでは動作するがデバイスでは動作しないか?
│     └─ シミュレータは60Hzを使用。デバイスは120Hzを使用する可能性がある。再計算してください。
│
└─ ジェスチャー + アニメーションのカクつき?
   ├─ アニメーションが競合しているか(同じkeyPath)?
   │  └─ 新しいアニメーションを追加する前に古いアニメーションを削除
   ├─ ジェスチャーがアニメーション実行中にレイヤーを更新しているか?
   │  └─ CADisplayLinkを使用して同期更新を行う
   └─ ジェスチャーがメインスレッドをブロックしているか?
      └─ Instruments > Core Animationでプロファイリング

共通パターン

パターン選択ルール(必須)

1度に1つのパターンを、この順序で適用してください

  1. 常にパターン1から始める(完了ハンドラの基本)

    • 完了が決して発火しない場合 → パターン1
    • print文で完了が add() の前に設定されていることを確認(33行目)
    • 完了は発火するがタイミングがおかしい場合のみ、パターン2に進む
  2. 次にパターン2(CATransactionの時間不一致)

    • 完了は発火するが経過時間 != 宣言時間の場合のみ
    • 必須の最初のステップ(40-47行目)のログを確認
  3. 次にパターン3(isRemovedOnCompletion)

    • アニメーションは完了するが見た目の状態が元に戻る場合のみ
  4. パターン4-7 特定の症状に基づいて適用(上の決定木91+行目を参照)

禁止事項

  • ❌ 複数のパターンを同時に適用すること(「パターン2とパターン4を一緒に試してみよう」)
  • ❌ 「もうそうじゃないとわかっている」という理由でパターン1をスキップすること
  • ❌ なぜ各パターンが必要なのか理解せずに組み合わせること
  • ❌ パターンをランダムに試してどれかがうまくいくことを期待すること

パターン1: 完了ハンドラの基本

❌ 間違い(アニメーション追加後にハンドラ設定)

layer.add(animation, forKey: "myAnimation")
animation.completion = { finished in  // ❌ 遅すぎる!
    print("Done")
}

✅ 正しい(ハンドラを追加前に設定)

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

理由: 完了ハンドラは、アニメーションがレイヤーに追加される前に設定されなければなりません。後から設定しても何も起こりません。


パターン2: CATransaction vs animation.duration

❌ 間違い(CATransactionがアニメーション時間を上書き)

CATransaction.begin()
CATransaction.setAnimationDuration(2.0)  // ❌ すべてのアニメーションを上書き!
let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5  // これは無視される
layer.add(anim, forKey: nil)
CATransaction.commit()  // アニメーションには2.0秒かかる。0.5秒ではない

✅ 正しい(アニメーションに時間を設定し、トランザクションには設定しない)

let anim = CABasicAnimation(keyPath: "position")
anim.duration = 0.5
layer.add(anim, forKey: nil)
// CATransactionでラップしない

理由: CATransaction.setAnimationDuration() はトランザクションブロック内のすべてのアニメーションに影響します。すべてのアニメーションを一律に変更したい場合にのみ使用してください。


パターン3: isRemovedOnCompletion & fillMode

❌ 間違い(アニメーションが完了後に消える)

let anim = CABasicAnimation(keyPath: "opacity")
anim.fromValue = 1.0
anim.toValue = 0.0
anim.duration = 0.5
layer.add(anim, forKey: nil)
// 0.5秒後、アニメーションは削除され、レイヤーは元の状態に戻る

✅ 正しい(アニメーション状態を保持)

anim.isRemovedOnCompletion = false
anim.fillMode = .forwards  // アニメーション完了後に最終状態を保持
layer.add(anim, forKey: nil)
// 0.5秒後、アニメーション状態は保持される

理由: デフォルトでは、アニメーションは削除されレイヤーは元に戻ります。永続的な状態変更には、isRemovedOnCompletion = false と fillMode = .forwards を設定してください。


パターン4: 完了ハンドラ内の弱い自己参照(必須)

❌ 禁止(強い自己参照は循環参照を引き起こす)

anim.completion = { finished in
    self.property = "value"  // ❌ 循環参照が確実に発生
}

✅ 必須(常に弱い自己参照を使用)

anim.completion = { [weak self] finished in
    guard let self = self else { return }
    self.property = "value"  // 安全にアクセス可能
}

これが必須であり、オプションではない理由

  • CAAnimationは、アニメーションが完了するまで完了ハンドラを生かし続ける
  • 完了ハンドラは明示的に弱くしない限り、selfを強くキャプチャする
  • 循環参照が発生する: self → アニメーション → 完了 → self
  • アニメーションが短命であってもメモリリークは発生する(0.3秒だからといって防げるわけではない)

禁止される正当化

  • ❌ 「アニメーションは短いので循環参照のリスクはない」
  • ❌ 「手動でアニメーションを削除するので問題ない」
  • ❌ 「このコードパスは1回しか実行されない」

完了ハンドラでは常に [weak self] を使用してください。例外はありません。


パターン5: 複数のアニメーション(同じkeyPath)

❌ 間違い(アニメーションが競合)

// アニメーション1を追加
let anim1 = CABasicAnimation(keyPath: "position.x")
anim1.toValue = 100
layer.add(anim1, forKey: "slide")

// 後で、アニメーション2を追加
let anim2 = CABasicAnimation(keyPath: "position.x")
anim2.toValue = 200
layer.add(anim2, forKey: "slide")  // ❌ 同じキー、anim1を置き換える!

✅ 正しい(追加前に削除)

layer.removeAnimation(forKey: "slide")  // 最初に古いものを削除

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

または、一意のキーを使用:

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

let anim2 = CABasicAnimation(keyPath: "position.x")
layer.add(anim2, forKey: "slide_2")  // 異なるキー

理由: 同じキーでアニメーションを追加すると、以前のアニメーションが置き換えられます。古いアニメーションを削除するか、一意のキーを使用してください。


パターン6: ジェスチャー + アニメーション同期のためのCADisplayLink

❌ 間違い(ジェスチャーは直接更新、アニメーションは異なるレートで更新)

func handlePan(_ gesture: UIPanGestureRecognizer) {
    let translation = gesture.translation(in: view)
    view.layer.position.x = translation.x  // ❌ 同期の問題
}

// 別途:
let anim = CABasicAnimation(keyPath: "position.x")
view.layer.add(anim, forKey: nil)  // 非同期によるカクつき

✅ 正しい(CADisplayLinkを同期に使用)

var displayLink: CADisplayLink?

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

@objc func updateAnimation() {
    // 同じフレーム内でジェスチャーとアニメーションの両方を更新
    let gesture = currentGesture
    let position = calculatePosition(from: gesture)
    layer.position = position  // 同期された更新
}

理由: ジェスチャーレコグナイザーとCAAnimationは異なるフレームレートで動作する可能性があります。CADisplayLinkは両方を画面のリフレッシュレートに同期します。


パターン7: スプリングアニメーションのデバイス間差異

❌ 間違い(1つのデバイス用にハードコーディング)

let springAnim = CASpringAnimation()
springAnim.damping = 0.7  // iPhone 15 Pro 用にハードコーディング
springAnim.stiffness = 100
layer.add(springAnim, forKey: nil)  // iPhone 12 ではカクつく

✅ 正しい(デバイスのパフォーマンスに適応)

let springAnim = CASpringAnimation()

// モデルではなく、デバイスのパフォーマンスクラスを使用
if ProcessInfo.processInfo.processorCount >= 6 {
    // モダンAシリーズ(A14+)
    springAnim.damping = 0.7
    springAnim.stiffness = 100
} else {
    // 古いAシリーズ
    springAnim.damping = 0.85
    springAnim.stiffness = 80
}

layer.add(springAnim, forKey: nil)

理由: スプリング物理の感触は60Hzと120Hzで異なります。モデルではなくデバイスクラス(コア数、GPU)を使用してください。


クイックリファレンス表

問題確認事項修正方法
完了が発火しないadd()の前にハンドラを設定completion = を add() の前に移動
時間の不一致CATransactionでラップしているか?CATransactionを削除するか、アニメーションをそこから取り除く
古いデバイスでカクつく値がハードコーディングされているか?ProcessInfo でデバイスクラスを判断
アニメーションが消えるisRemovedOnCompletion か?false に設定し、fillMode = .forwards を使用
ジェスチャー + アニメーションのカクつき更新は同期されているか?CADisplayLink を使用
複数のアニメーションが競合同じキーか?一意のキーを使用するか、最初に removeAnimation()
ハンドラ内の弱い参照完了が正しくキャプチャされているか?完了では常に [weak self] を使用

30分経っても行き詰まった場合

30分経ってもアニメーションがまだ壊れている場合:

停止してください。次のいずれかです:

  1. 必須の手順をスキップした(最も一般的)
  2. 診断出力を誤って解釈した
  3. 症状に合わないパターンを適用した
  4. Instrumentsによるプロファイリングが必要な5%のエッジケースに該当する

「スキルが機能しなかった」と主張する前の必須チェックリスト

  • 必須の最初のステップ(28-63行目)の4つの診断ブロックすべてを実行した
  • 診断結果の正確な出力(ログ、print文)を貼り付けた
  • 「これからわかること」(66-72行目)から1つの根本原因を特定した
  • 決定木(91+行目)から最初に一致するパターンを適用した
  • シミュレータだけでなく、実機でパターンをテストした
  • print文/ログで修正が機能したことを確認した

すべてのチェックボックスがオンになっているが、まだ壊れている場合

  • Instruments > Core Animationでプロファイリングする必要があります
  • 所要時間: 30-60分(エッジケースでは避けられない)
  • ハードコーディング、asyncAfter、または「出荷して期待する」ことは禁止されています
  • 回避策を追加する前にガイダンスを求めてください

想定時間コスト

  • パターン1: 2-5分
  • パターン2: 5-10分
  • パターン3: 5-10分
  • パターン4: 2-5分
  • パターン5: 5-10分
  • パターン6: 10-15分
  • パターン7: 10-15分
  • Instrumentsプロファイリング: 30-60分

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

関連スキル