Communitygithub.com

ComeOnOliver/skillshub

Use ao implementar animações SwiftUI, entender VectorArithmetic, usar a macro @Animatable, transições de zoom, ponte de animação UIKit/AppKit, escolher entre animações spring e timing curve, ou depurar comportamento de animação — referência abrangente de animações do iOS 13 ao iOS 26

O que é skillshub?

Este skill é um guia completo e detalhado sobre o sistema de animação do SwiftUI, cobrindo desde conceitos fundamentais até técnicas avançadas. Ele explica o protocolo Animatable, a nova macro @Animatable introduzida no iOS 26, os diferentes tipos de animação (timing curve e spring), e o sistema de Transactions. A referência é útil para desenvolvedores que trabalham com SwiftUI em qualquer versão do iOS, do 13 ao 26, e destaca as mudanças introduzidas no iOS 17, como animações spring padrão e animações escopo. O skill também aborda tópicos avançados como o protocolo CustomAnimation e transições de zoom no iOS 18+. O conteúdo é apresentado de forma educacional, com exemplos de código e explicações claras, sendo uma referência essencial para qualquer desenvolvedor iOS que deseja dominar animações declarativas no SwiftUI.

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

Perguntar na sua IA favorita

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

Documentação

Animação SwiftUI

Visão Geral

Guia abrangente do sistema de animação do SwiftUI, desde conceitos fundamentais até técnicas avançadas. Este skill cobre o protocolo Animatable, a macro @Animatable do iOS 26, tipos de animação e o sistema de Transações.

Princípio central Animação no SwiftUI é interpolação matemática ao longo do tempo, alimentada pelo protocolo VectorArithmetic. Entender essa base libera todo o poder do sistema de animação declarativo do SwiftUI.

Requisitos de Sistema

  • iOS 13+: Protocolo Animatable, animações timing/spring
  • iOS 17+: Animações spring padrão, animações escopo, PhaseAnimator, KeyframeAnimator
  • iOS 18+: Transições de zoom, ponte de animação UIKit/AppKit
  • iOS 26+: Macro @Animatable

Parte 1: Entendendo Animação

O que é Interpolação

Animação é o processo de gerar valores intermediários entre um estado inicial e final.

Exemplo: Animação de opacidade

.opacity(0) → .opacity(1)

Enquanto esta animação é executada, o SwiftUI calcula valores intermediários:

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

Como os valores são distribuídos

  • Determinado pela curva de tempo ou função de velocidade da animação
  • Animações spring usam simulação física
  • Curvas de tempo usam curvas bezier
  • Cada tipo de animação calcula os valores de forma diferente

Protocolo VectorArithmetic

O SwiftUI requer que os dados animados estejam em conformidade com VectorArithmetic — fornecendo subtração, escalonamento, adição e um valor zero. Isso permite que o SwiftUI interpole entre quaisquer dois valores.

Tipos conformes embutidos: CGFloat, Double, Float, Angle (1D), CGPoint, CGSize (2D), CGRect (4D).

Insight chave A aritmética vetorial abstrai sobre a dimensionalidade. O SwiftUI anima todos esses tipos com uma única implementação genérica.

Por que Int Não Pode Ser Animado

Int não está em conformidade com VectorArithmetic — não existem intermediários fracionários entre 3 e 4. O SwiftUI simplesmente define o valor instantaneamente.

Solução: Use Float/Double e exiba como Int:

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

Valores de Modelo vs. Apresentação

Atributos animáveis têm conceitualmente dois valores:

Valor de Modelo

  • O valor alvo definido pelo seu código
  • Atualizado imediatamente quando o estado muda
  • O que você escreve no corpo da sua view

Valor de Apresentação

  • O valor interpolado atual que está sendo renderizado
  • Atualiza quadro a quadro durante a animação
  • O que o usuário realmente vê

Exemplo

.scaleEffect(selected ? 1.5 : 1.0)

Quando selected se torna true:

  • Valor de modelo: Imediatamente se torna 1.5
  • Valor de apresentação: Interpola 1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5 ao longo do tempo

Parte 2: Protocolo Animatable

Visão Geral

O protocolo Animatable permite que views animem suas propriedades definindo quais dados devem ser interpolados.

protocol Animatable {
    associatedtype AnimatableData: VectorArithmetic

    var animatableData: AnimatableData { get set }
}

O SwiftUI constrói um atributo animável para qualquer view em conformidade com este protocolo.

Views Animáveis Embutidas

Muitos modificadores do SwiftUI estão em conformidade com Animatable:

Efeitos Visuais

  • .scaleEffect() — Anima transformação de escala
  • .rotationEffect() — Anima rotação
  • .offset() — Anima deslocamento de posição
  • .opacity() — Anima transparência
  • .blur() — Anima raio de desfoque
  • .shadow() — Anima propriedades de sombra

Todos os tipos Shape

  • Circle, Rectangle, RoundedRectangle
  • Capsule, Ellipse, Path
  • Implementações customizadas de Shape

AnimatablePair para Dados Multidimensionais

Ao animar múltiplas propriedades, use AnimatablePair para combinar vetores. Por exemplo, scaleEffect combina CGSize (2D) e UnitPoint (2D) em um vetor 4D via AnimatablePair<CGSize.AnimatableData, UnitPoint.AnimatableData>. Acesse componentes via .first e .second. A macro @Animatable (iOS 26+) elimina completamente essa burocracia.

Conformidade Animatable Customizada

Quando usar

  • Animando layout customizado (como RadialLayout)
  • Animando código de desenho customizado
  • Animando propriedades que afetam caminhos de formas (paths)

Exemplo: Visualização de número animado

struct AnimatableNumberView: View, Animatable {
    var number: Double

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

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

// Uso
AnimatableNumberView(number: value)
    .animation(.spring, value: value)

Como funciona

  1. number muda de 0 para 100
  2. O SwiftUI chama body para cada quadro da animação
  3. Cada quadro recebe um novo valor number: 0 → 5 → 15 → 30 → 55 → 80 → 100
  4. O Text é atualizado para mostrar o inteiro interpolado

Aviso de Performance

A conformidade Animatable customizada é cara — O SwiftUI chama body para cada quadro na thread principal. Efeitos embutidos (.scaleEffect(), .opacity()) são executados fora da thread principal e não chamam body. Use conformidade customizada apenas quando modificadores embutidos não conseguem atingir o efeito (ex.: animar um Layout customizado que reposiciona subviews por quadro).


Parte 3: Macro @Animatable (iOS 26+)

Visão Geral

A macro @Animatable elimina a burocracia de conformar manualmente ao protocolo Animatable.

Antes do iOS 26, você tinha que:

  1. Conformar manualmente a Animatable
  2. Escrever getter e setter animatableData
  3. Usar AnimatablePair para múltiplas propriedades
  4. Excluir propriedades não animáveis manualmente

iOS 26+, você apenas adiciona @Animatable:

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

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

A macro automaticamente:

  • Gera conformidade com Animatable
  • Inspeciona todas as propriedades armazenadas
  • Cria animatableData a partir de propriedades conformes a VectorArithmetic
  • Lida com dados multidimensionais usando AnimatablePair

Comparação Antes/Depois

Antes da macro @Animatable

struct HikingRouteShape: Shape {
    var startPoint: CGPoint
    var endPoint: CGPoint
    var elevation: Double
    var drawingDirection: Bool // Não quero animar isso

    // Declaração tediosa de animatableData manual
    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 {
        // Código de desenho
    }
}

Depois da macro @Animatable

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

    @AnimatableIgnored
    var drawingDirection: Bool // Excluída da animação

    func path(in rect: CGRect) -> Path {
        // Código de desenho
    }
}

Linhas de código: 20 → 12 (redução de 40%)

@AnimatableIgnored

Use @AnimatableIgnored para excluir propriedades da animação.

Quando usar

  • Valores de depuração — Flags apenas para desenvolvimento
  • IDs — Identificadores que não devem ser animados
  • Timestamps — Quando a view foi criada/atualizada
  • Estado interno — Contabilidade não visual
  • Tipos não VectorArithmetic — Cores, strings, booleanos

Exemplo

@MainActor
@Animatable
struct ProgressView: View {
    var progress: Double // Animado
    var totalItems: Int // Animado (se Float, não se Int)

    @AnimatableIgnored
    var title: String // Não animado

    @AnimatableIgnored
    var startTime: Date // Não animado

    @AnimatableIgnored
    var debugEnabled: Bool // Não animado

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

Caso de Uso no Mundo Real

@Animatable funciona para qualquer exibição numérica — preços de ações, frequência cardíaca, pontuações, temporizadores, barras de progresso:

@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)
        }
    }
}

// Uso
AnimatedValueView(value: currentPrice, changePercent: 0.025, label: "Preço")
    .animation(.spring(duration: 0.8), value: currentPrice)

Parte 4: Tipos de Animação

Animações de Curva de Tempo (Timing Curve)

Animações de curva de tempo usam curvas bezier para controlar a velocidade da animação ao longo do tempo.

Predefinições embutidas

.animation(.linear)          // Velocidade constante
.animation(.easeIn)          // Começa devagar, termina rápido
.animation(.easeOut)         // Começa rápido, termina devagar
.animation(.easeInOut)       // Começo e fim lentos, meio rápido

Curvas de tempo customizadas

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

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

Duração

Todas as animações de curva de tempo aceitam uma duração opcional:

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

Padrão: 0,35 segundos

Animações Spring

Animações spring usam simulação física para criar movimento natural e orgânico.

Predefinições embutidas

.animation(.smooth)     // Sem bounce (padrão desde iOS 17)
.animation(.snappy)     // Pequena quantidade de bounce
.animation(.bouncy)     // Maior quantidade de bounce

Springs customizadas

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

Parâmetros

  • duration — Duração percebida da animação
  • bounce — Quantidade de bounce (0 = sem bounce, 1 = muito elástico)

Muito mais intuitivo que os parâmetros tradicionais de spring (massa, rigidez, amortecimento).

Animações de Ordem Superior

Modifique animações base para criar efeitos complexos.

Atraso (Delay)

.animation(.spring.delay(0.5))

Aguarda 0,5 segundos antes de iniciar a animação.

Repetição

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

Repete a animação várias vezes ou infinitamente.

Velocidade

.animation(.spring.speed(2.0))  // 2x mais rápido
.animation(.spring.speed(0.5))  // 2x mais lento

Multiplica a velocidade da animação.

Mudanças na Animação Padrão (iOS 17+)

Antes do iOS 17

withAnimation {
    // Usava curva de tempo por padrão
}

iOS 17+

withAnimation {
    // Usa .smooth spring por padrão
}

Por que a mudança: Animações spring parecem mais naturais e preservam a velocidade quando interrompidas.

Recomendação: Adote springs. Elas fazem sua UI parecer mais responsiva e polida.


Parte 5: Sistema de Transações (Transaction)

withAnimation

A maneira mais comum de acionar uma animação.

Button("Aumentar Escala") {
    withAnimation(.spring) {
        scale = 1.5
    }
}

Como funciona

  1. withAnimation abre uma transação
  2. Define a animação no dicionário da transação
  3. Executa a closure (mudanças de estado)
  4. A transação se propaga para baixo na hierarquia de views
  5. Atributos animáveis verificam a animação e interpolam

Animação explícita

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

Sem animação

withAnimation(nil) {
    // As mudanças acontecem imediatamente, sem animação
    resetState()
}

Modificador animation()

Aplique animações a valores específicos dentro de uma view.

Uso básico

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

Como funciona: A animação só se aplica quando isActive muda. Outras mudanças de estado não acionarão esta animação.

Múltiplas animações na mesma view

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

Animações diferentes para propriedades diferentes.

Animações Escopo (iOS 17+)

Escopo restrito de animações para atributos animáveis específicos.

Problema com a abordagem antiga

struct AvatarView: View {
    var selected: Bool

    var body: some View {
        Image("avatar")
            .scaleEffect(selected ? 1.5 : 1.0)
            .animation(.spring, value: selected)
            // ⚠️ Se a imagem também muda quando selecionado muda,
            //    a transição da imagem também é animada (acidental)
    }
}

Solução: Animação escopo

struct AvatarView: View {
    var selected: Bool

    var body: some View {
        Image("avatar")
            .animation(.spring, value: selected) {
                $0.scaleEffect(selected ? 1.5 : 1.0)
            }
            // ✅ Apenas scaleEffect anima, a transição da imagem não
    }
}

Como funciona

  • A animação só se aplica aos atributos dentro da closure
  • Outros atributos não são afetados
  • Previne animações acidentais

Chaves de Transação Customizadas

Defina tipos TransactionKey customizados para propagar contexto através do sistema de transações. Use withTransaction para definir valores e o modificador .transaction para lê-los. Isso permite aplicar diferentes animações com base em como uma mudança de estado foi acionada (toque vs. programática).


Parte 6: Tópicos Avançados

Protocolo CustomAnimation

Implemente animações personalizadas substituindo CustomAnimation e definindo lógica de interpolação e velocidade. Exemplo: Animação de batida cardíaca ou animação de salto.


Fim do Guia

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