Communitygithub.com

ComeOnOliver/skillshub

SwiftUI 애니메이션 구현, VectorArithmetic 이해, @Animatable 매크로 사용, 줌 전환, UIKit/AppKit 애니메이션 브리징, 스프링과 타이밍 곡선 애니메이션 선택, 애니메이션 동작 디버깅 시 활용하세요. iOS 13부터 iOS 26까지의 포괄적인 애니메이션 레퍼런스입니다.

skillshub란 무엇인가요?

이 스킬은 SwiftUI의 애니메이션 시스템을 기초부터 고급 기술까지 포괄적으로 다루는 레퍼런스입니다. VectorArithmetic 프로토콜을 기반으로 한 수학적 보간(interpolation)이 핵심 원리이며, iOS 13부터 iOS 26까지의 API를 지원합니다. 주요 내용으로는 Animatable 프로토콜, iOS 26에서 도입된 @Animatable 매크로(상용구 코드 제거), 스프링 및 타이밍 곡선 애니메이션 유형, Transaction 시스템, 고급 주제(CustomAnimation 프로토콜, PhaseAnimator, KeyframeAnimator, UIKit/AppKit 브리징, 줌 전환)를 포함합니다. 개발자는 이 스킬을 통해 SwiftUI 애니메이션의 내부 동작 방식(모델 값과 표현 값의 구분, 보간 과정)을 이해하고, @Animatable 매크로를 사용하여 AnimatablePair의 복잡성을 줄이며, 스프링 애니메이션의 물리 시뮬레이션 특성을 활용하여 더 자연스러운 UI를 구현할 수 있습니다. 또한 iOS 17+의 범위 지정 애니메이션(Scoped Animations)과 iOS 18+의 새로운 전환 및 브리징 기능을 효과적으로 사용할 수 있습니다. 각 애니메이션 유형의 적절한 사용 사례와 성능 경고도 함께 제공되어 실무에서의 의사 결정을 지원합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/CharlesWiltgen/Axiom/axiom-swiftui-animation-ref

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

SwiftUI 애니메이션

개요

SwiftUI 애니메이션 시스템을 기초 개념부터 고급 기술까지 포괄적으로 다루는 가이드입니다. 이 스킬은 Animatable 프로토콜, iOS 26의 @Animatable 매크로, 애니메이션 유형, Transaction 시스템을 다룹니다.

핵심 원리 SwiftUI의 애니메이션은 시간에 따른 수학적 보간(interpolation)이며, VectorArithmetic 프로토콜을 기반으로 합니다. 이 기초를 이해하면 SwiftUI의 선언형 애니메이션 시스템의 모든 기능을 활용할 수 있습니다.

시스템 요구 사항

  • iOS 13+: Animatable 프로토콜, 타이밍/스프링 애니메이션
  • iOS 17+: 기본 스프링 애니메이션, 범위 지정 애니메이션, PhaseAnimator, KeyframeAnimator
  • iOS 18+: 줌 전환, UIKit/AppKit 애니메이션 브리징
  • iOS 26+: @Animatable 매크로

파트 1: 애니메이션 이해하기

보간이란 무엇인가

애니메이션은 시작 상태와 끝 상태 사이의 중간 값을 생성하는 과정입니다.

예시: 불투명도 애니메이션

.opacity(0) → .opacity(1)

이 애니메이션이 실행되는 동안 SwiftUI는 중간 값을 계산합니다:

0.0 → 0.02 → 0.05 → 0.1 → 0.25 → 0.4 → 0.6 → 0.8 → 1.0

값이 분포되는 방식

  • 애니메이션의 타이밍 곡선 또는 속도 함수에 의해 결정됩니다.
  • 스프링 애니메이션은 물리 시뮬레이션을 사용합니다.
  • 타이밍 곡선은 베지어 곡선을 사용합니다.
  • 각 애니메이션 유형은 값을 다르게 계산합니다.

VectorArithmetic 프로토콜

SwiftUI는 애니메이션 되는 데이터가 VectorArithmetic를 준수해야 합니다. 이는 뺄셈, 스케일링, 덧셈 및 0값을 제공합니다. 이를 통해 SwiftUI는 임의의 두 값 사이를 보간할 수 있습니다.

내장 준수 유형: CGFloat, Double, Float, Angle (1D), CGPoint, CGSize (2D), CGRect (4D).

핵심 통찰 벡터 산술은 차원을 추상화합니다. SwiftUI는 단일 일반 구현으로 이러한 모든 유형을 애니메이션 합니다.

Int를 애니메이션 할 수 없는 이유

Int는 VectorArithmetic를 준수하지 않습니다. 3과 4 사이에 분수 중간 값이 존재하지 않기 때문입니다. SwiftUI는 값을 단순히 스냅합니다.

해결책: Float/Double을 사용하고 Int로 표시합니다:

@State private var count: Float = 0
// ...
Text("\(Int(count))")
    .animation(.spring, value: count)

모델 값 vs 표현 값

애니메이션 가능 속성은 개념적으로 두 가지 값을 가집니다:

모델 값

  • 코드에서 설정한 대상 값입니다.
  • 상태가 변경될 때 즉시 업데이트됩니다.
  • 뷰의 body에 작성하는 값입니다.

표현 값

  • 현재 렌더링되는 보간 값입니다.
  • 애니메이션 중 프레임 단위로 업데이트됩니다.
  • 사용자가 실제로 보는 값입니다.

예시

.scaleEffect(selected ? 1.5 : 1.0)

selected가 true가 되면:

  • 모델 값: 즉시 1.5가 됩니다.
  • 표현 값: 시간에 따라 1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5로 보간됩니다.

파트 2: Animatable 프로토콜

개요

Animatable 프로토콜을 사용하면 보간되어야 할 데이터를 정의하여 뷰가 자체 속성을 애니메이션 할 수 있습니다.

protocol Animatable {
    associatedtype AnimatableData: VectorArithmetic

    var animatableData: AnimatableData { get set }
}

SwiftUI는 이 프로토콜을 준수하는 모든 뷰에 대해 애니메이션 가능 속성을 구축합니다.

내장 애니메이션 가능 뷰

많은 SwiftUI 수정자가 Animatable을 준수합니다:

시각 효과

  • .scaleEffect() — 스케일 변환 애니메이션
  • .rotationEffect() — 회전 애니메이션
  • .offset() — 위치 오프셋 애니메이션
  • .opacity() — 투명도 애니메이션
  • .blur() — 흐림 반경 애니메이션
  • .shadow() — 그림자 속성 애니메이션

모든 Shape 유형

  • Circle, Rectangle, RoundedRectangle
  • Capsule, Ellipse, Path
  • 사용자 지정 Shape 구현

다차원 데이터를 위한 AnimatablePair

여러 속성을 애니메이션 할 때는 AnimatablePair를 사용하여 벡터를 결합합니다. 예를 들어, scaleEffect는 CGSize(2D)와 UnitPoint(2D)를 AnimatablePair<CGSize.AnimatableData, UnitPoint.AnimatableData>를 통해 4D 벡터로 결합합니다. .first와 .second를 사용하여 구성 요소에 액세스합니다. @Animatable 매크로(iOS 26+)는 이 상용구를 완전히 제거합니다.

사용자 지정 Animatable 준수

사용 시기

  • 사용자 지정 레이아웃(예: RadialLayout) 애니메이션
  • 사용자 지정 드로잉 코드 애니메이션
  • 모양 경로에 영향을 미치는 속성 애니메이션

예시: 애니메이션 숫자 뷰

struct AnimatableNumberView: View, Animatable {
    var number: Double

    var animatableData: Double {
        get { number }
        set { number = newValue }
    }

    var body: some View {
        Text("\(Int(number))")
            .font(.largeTitle)
    }
}

// 사용법
AnimatableNumberView(number: value)
    .animation(.spring, value: value)

작동 방식

  1. number가 0에서 100으로 변경됩니다.
  2. SwiftUI는 애니메이션의 모든 프레임에 대해 body를 호출합니다.
  3. 각 프레임은 새로운 number 값을 받습니다: 0 → 5 → 15 → 30 → 55 → 80 → 100
  4. Text가 보간된 정수를 표시하도록 업데이트됩니다.

성능 경고

사용자 지정 Animatable 준수는 비용이 많이 듭니다 — SwiftUI는 모든 프레임에 대해 메인 스레드에서 body를 호출합니다. 내장 효과(.scaleEffect(), .opacity())는 메인 스레드 밖에서 실행되며 body를 호출하지 않습니다. 내장 수정자로 효과를 구현할 수 없을 때만 사용자 지정 준수를 사용하세요(예: 프레임마다 하위 뷰 위치를 변경하는 사용자 지정 Layout 애니메이션).


파트 3: @Animatable 매크로 (iOS 26+)

개요

@Animatable 매크로는 Animatable 프로토콜을 수동으로 준수할 때 필요한 상용구 코드를 제거합니다.

iOS 26 이전에는 다음을 수행해야 했습니다:

  1. Animatable을 수동으로 준수
  2. animatableData getter 및 setter 작성
  3. 여러 속성에 대해 AnimatablePair 사용
  4. 애니메이션 불가능한 속성 수동 제외

**iOS 26+**에서는 @Animatable만 추가하면 됩니다:

@MainActor
@Animatable
struct MyView: View {
    var scale: CGFloat
    var opacity: Double

    var body: some View {
        // ...
    }
}

매크로는 자동으로:

  • Animatable 준수 생성
  • 모든 저장 속성 검사
  • VectorArithmetic를 준수하는 속성에서 animatableData 생성
  • AnimatablePair로 다차원 데이터 처리

전후 비교

@Animatable 매크로 이전

struct HikingRouteShape: Shape {
    var startPoint: CGPoint
    var endPoint: CGPoint
    var elevation: Double
    var drawingDirection: Bool // 이 속성은 애니메이션하지 않음

    // 지루한 수동 animatableData 선언
    var animatableData: AnimatablePair<AnimatablePair<CGFloat, CGFloat>,
                        AnimatablePair<Double, AnimatablePair<CGFloat, CGFloat>>> {
        get {
            AnimatablePair(
                AnimatablePair(startPoint.x, startPoint.y),
                AnimatablePair(elevation, AnimatablePair(endPoint.x, endPoint.y))
            )
        }
        set {
            startPoint = CGPoint(x: newValue.first.first, y: newValue.first.second)
            elevation = newValue.second.first
            endPoint = CGPoint(x: newValue.second.second.first, y: newValue.second.second.second)
        }
    }

    func path(in rect: CGRect) -> Path {
        // 드로잉 코드
    }
}

@Animatable 매크로 이후

@Animatable
struct HikingRouteShape: Shape {
    var startPoint: CGPoint
    var endPoint: CGPoint
    var elevation: Double

    @AnimatableIgnored
    var drawingDirection: Bool // 애니메이션에서 제외

    func path(in rect: CGRect) -> Path {
        // 드로잉 코드
    }
}

코드 줄 수: 20 → 12 (40% 감소)

@AnimatableIgnored

@AnimatableIgnored를 사용하여 속성을 애니메이션에서 제외합니다.

사용 시기

  • 디버그 값 — 개발 전용 플래그
  • ID — 애니메이션되지 않아야 하는 식별자
  • 타임스탬프 — 뷰가 생성/업데이트된 시간
  • 내부 상태 — 비시각적 부기
  • 비 VectorArithmetic 유형 — 색상, 문자열, 부울

예시

@MainActor
@Animatable
struct ProgressView: View {
    var progress: Double // 애니메이션 됨
    var totalItems: Int // 애니메이션 됨 (Float인 경우, Int인 경우 아님)

    @AnimatableIgnored
    var title: String // 애니메이션 안 됨

    @AnimatableIgnored
    var startTime: Date // 애니메이션 안 됨

    @AnimatableIgnored
    var debugEnabled: Bool // 애니메이션 안 됨

    var body: some View {
        VStack {
            Text(title)
            ProgressBar(value: progress)
            if debugEnabled {
                Text("시작됨: \(startTime.formatted())")
            }
        }
    }
}

실제 사용 사례

@Animatable은 모든 숫자 표시(주가, 심박수, 점수, 타이머, 진행률 표시줄)에 적용됩니다:

@MainActor
@Animatable
struct AnimatedValueView: View {
    var value: Double
    var changePercent: Double

    @AnimatableIgnored
    var label: String

    var body: some View {
        VStack(alignment: .trailing) {
            Text("\(value, format: .number.precision(.fractionLength(2)))")
                .font(.title)
            Text("\(changePercent > 0 ? "+" : "")\(changePercent, format: .percent)")
                .foregroundStyle(changePercent > 0 ? .green : .red)
        }
    }
}

// 사용법
AnimatedValueView(value: currentPrice, changePercent: 0.025, label: "가격")
    .animation(.spring(duration: 0.8), value: currentPrice)

파트 4: 애니메이션 유형

타이밍 곡선 애니메이션

타이밍 곡선 애니메이션은 베지어 곡선을 사용하여 시간에 따른 애니메이션 속도를 제어합니다.

내장 프리셋

.animation(.linear)          // 일정한 속도
.animation(.easeIn)          // 느리게 시작, 빠르게 종료
.animation(.easeOut)         // 빠르게 시작, 느리게 종료
.animation(.easeInOut)       // 시작과 끝은 느리고, 중간은 빠름

사용자 지정 타이밍 곡선

let customCurve = UnitCurve(
    startControlPoint: CGPoint(x: 0.2, y: 0),
    endControlPoint: CGPoint(x: 0.8, y: 1)
)

.animation(.timingCurve(customCurve, duration: 0.5))

지속 시간

모든 타이밍 곡선 애니메이션은 선택적 지속 시간을 허용합니다:

.animation(.easeInOut(duration: 0.3))
.animation(.linear(duration: 1.0))

기본값: 0.35초

스프링 애니메이션

스프링 애니메이션은 물리 시뮬레이션을 사용하여 자연스럽고 유기적인 움직임을 만듭니다.

내장 프리셋

.animation(.smooth)     // 바운스 없음 (iOS 17 이후 기본값)
.animation(.snappy)     // 약간의 바운스
.animation(.bouncy)     // 더 많은 바운스

사용자 지정 스프링

.animation(.spring(duration: 0.6, bounce: 0.3))

매개변수

  • duration — 인지되는 애니메이션 지속 시간
  • bounce — 바운스 양 (0 = 바운스 없음, 1 = 매우 탄력적)

훨씬 직관적입니다. 기존 스프링 매개변수(질량, 강성, 감쇠)보다.

고차 애니메이션

기본 애니메이션을 수정하여 복잡한 효과를 만듭니다.

지연

.animation(.spring.delay(0.5))

애니메이션을 시작하기 전에 0.5초를 기다립니다.

반복

.animation(.easeInOut.repeatCount(3, autoreverses: true))
.animation(.linear.repeatForever(autoreverses: false))

애니메이션을 여러 번 또는 무한히 반복합니다.

속도

.animation(.spring.speed(2.0))  // 2배 빠름
.animation(.spring.speed(0.5))  // 2배 느림

애니메이션 속도를 곱합니다.

기본 애니메이션 변경 사항 (iOS 17+)

iOS 17 이전

withAnimation {
    // 기본적으로 타이밍 곡선 사용
}

iOS 17+

withAnimation {
    // 기본적으로 .smooth 스프링 사용
}

변경 이유: 스프링 애니메이션은 더 자연스럽게 느껴지고 중단 시 속도를 유지합니다.

권장 사항: 스프링을 사용하세요. UI를 더 반응적이고 세련되게 만듭니다.


파트 5: Transaction 시스템

withAnimation

애니메이션을 트리거하는 가장 일반적인 방법입니다.

Button("확대") {
    withAnimation(.spring) {
        scale = 1.5
    }
}

작동 방식

  1. withAnimation이 트랜잭션을 엽니다.
  2. 트랜잭션 사전에 애니메이션을 설정합니다.
  3. 클로저를 실행합니다(상태 변경).
  4. 트랜잭션이 뷰 계층 구조 아래로 전파됩니다.
  5. 애니메이션 가능 속성이 애니메이션을 확인하고 보간합니다.

명시적 애니메이션

withAnimation(.spring(duration: 0.6, bounce: 0.4)) {
    isExpanded.toggle()
}

애니메이션 없음

withAnimation(nil) {
    // 변경 사항이 즉시 발생, 애니메이션 없음
    resetState()
}

animation() 뷰 수정자

뷰 내에서 특정 값에 애니메이션을 적용합니다.

기본 사용법

Circle()
    .fill(isActive ? .blue : .gray)
    .animation(.spring, value: isActive)

작동 방식: isActive가 변경될 때만 애니메이션이 적용됩니다. 다른 상태 변경은 이 애니메이션을 트리거하지 않습니다.

동일한 뷰에 여러 애니메이션

Circle()
    .scaleEffect(scale)
    .animation(.bouncy, value: scale)
    .opacity(opacity)
    .animation(.easeInOut, value: opacity)

속성마다 다른 애니메이션.

범위 지정 애니메이션 (iOS 17+)

애니메이션을 특정 애니메이션 가능 속성으로 좁게 범위를 지정합니다.

이전 방식의 문제점

struct AvatarView: View {
    var selected: Bool

    var body: some View {
        Image("avatar")
            .scaleEffect(selected ? 1.5 : 1.0)
            .animation(.spring, value: selected)
            // ⚠️ 선택됨이 변경될 때 이미지도 변경되면,
            //    이미지 전환도 의도치 않게 애니메이션 됨
    }
}

해결책: 범위 지정 애니메이션

struct AvatarView: View {
    var selected: Bool

    var body: some View {
        Image("avatar")
            .animation(.spring, value: selected) {
                $0.scaleEffect(selected ? 1.5 : 1.0)
            }
            // ✅ scaleEffect만 애니메이션 됨, 이미지 전환은 안 됨
    }
}

작동 방식

  • 애니메이션은 클로저 내의 속성에만 적용됩니다.
  • 다른 속성은 영향을 받지 않습니다.
  • 우발적인 애니메이션을 방지합니다.

사용자 지정 Transaction Key

사용자 지정 TransactionKey 유형을 정의하여 트랜잭션 시스템을 통해 컨텍스트를 전파합니다. withTransaction을 사용하여 값을 설정하고 .transaction 수정자를 사용하여 읽습니다. 이를 통해 상태 변경이 트리거된 방식(탭 대 프로그래매틱)에 따라 다른 애니메이션을 적용할 수 있습니다.


파트 6: 고급 주제

CustomAnimation 프로토콜

...

Imp

[잘림] - 번역됨

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

관련 스킬