Communitygithub.com

ComeOnOliver/skillshub

Úsalo al implementar animaciones de SwiftUI, entender VectorArithmetic, usar la macro @Animatable, transiciones de zoom, puente de animación UIKit/AppKit, elegir entre animaciones spring y de curva temporal, o depurar el comportamiento de animaciones: referencia completa de animaciones desde iOS 13 hasta iOS 26.

¿Qué es skillshub?

Esta habilidad proporciona una guía exhaustiva del sistema de animación de SwiftUI, desde conceptos fundamentales como la interpolación y el protocolo VectorArithmetic, hasta técnicas avanzadas como la macro @Animatable (iOS 26+), animaciones spring y de curva temporal, el sistema de transacciones, y temas avanzados como el protocolo CustomAnimation y las transiciones de zoom (iOS 18+). Es especialmente útil para desarrolladores de iOS que buscan comprender a fondo cómo funcionan las animaciones en SwiftUI, por qué ciertos tipos (como Int) no se pueden animar directamente, y cómo optimizar el rendimiento evitando recreaciones innecesarias de vistas. La habilidad cubre desde iOS 13 hasta iOS 26, incluyendo cambios importantes como la animación spring por defecto desde iOS 17 y las nuevas capacidades de la macro @Animatable que reduce significativamente el código repetitivo. Funciona con SwiftUI y puede integrarse en herramientas como Claude Code, Cursor o Codex, proporcionando ejemplos prácticos y explicaciones detalladas de cada concepto.

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

Preguntar en tu IA favorita

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

Documentación

Animación en SwiftUI

Descripción general

Guía completa del sistema de animación de SwiftUI, desde conceptos fundamentales hasta técnicas avanzadas. Esta habilidad cubre el protocolo Animatable, la macro @Animatable de iOS 26, los tipos de animación y el sistema de transacciones.

Principio fundamental: La animación en SwiftUI es interpolación matemática a lo largo del tiempo, impulsada por el protocolo VectorArithmetic. Comprender esta base desbloquea todo el poder del sistema de animación declarativo de SwiftUI.

Requisitos del sistema

  • iOS 13+: Protocolo Animatable, animaciones de tiempo/spring
  • iOS 17+: Animaciones spring por defecto, animaciones con ámbito, PhaseAnimator, KeyframeAnimator
  • iOS 18+: Transiciones de zoom, puente de animación UIKit/AppKit
  • iOS 26+: Macro @Animatable

Parte 1: Entendiendo la animación

¿Qué es la interpolación?

La animación es el proceso de generar valores intermedios entre un estado inicial y uno final.

Ejemplo: Animación de opacidad

.opacity(0) → .opacity(1)

Mientras esta animación se ejecuta, SwiftUI calcula valores intermedios:

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

Cómo se distribuyen los valores

  • Determinados por la curva temporal o función de velocidad de la animación
  • Las animaciones spring utilizan simulación física
  • Las curvas temporales usan curvas bezier
  • Cada tipo de animación calcula los valores de manera diferente

Protocolo VectorArithmetic

SwiftUI requiere que los datos animados se ajusten a VectorArithmetic, proporcionando resta, escalado, suma y un valor cero. Esto permite a SwiftUI interpolar entre dos valores cualesquiera.

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

Información clave: La aritmética vectorial abstrae sobre la dimensionalidad. SwiftUI anima todos estos tipos con una única implementación genérica.

Por qué Int no se puede animar

Int no cumple con VectorArithmetic: no existen intermedios fraccionarios entre 3 y 4. SwiftUI simplemente salta al valor.

Solución: Usa Float/Double y muéstralo como Int:

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

Valores de modelo vs. de presentación

Los atributos animables tienen conceptualmente dos valores:

Valor de modelo

  • El valor objetivo establecido por tu código
  • Se actualiza inmediatamente cuando cambia el estado
  • Lo que escribes en el cuerpo de tu vista

Valor de presentación

  • El valor interpolado actual que se está renderizando
  • Se actualiza cuadro por cuadro durante la animación
  • Lo que el usuario ve realmente

Ejemplo

.scaleEffect(selected ? 1.5 : 1.0)

Cuando selected se vuelve true:

  • Valor de modelo: Inmediatamente se convierte en 1.5
  • Valor de presentación: Interpola 1.0 → 1.1 → 1.2 → 1.3 → 1.4 → 1.5 a lo largo del tiempo

Parte 2: Protocolo Animatable

Descripción general

El protocolo Animatable permite que las vistas animen sus propiedades definiendo qué datos deben ser interpolados.

protocol Animatable {
    associatedtype AnimatableData: VectorArithmetic

    var animatableData: AnimatableData { get set }
}

SwiftUI construye un atributo animable para cualquier vista que cumpla con este protocolo.

Vistas animables incorporadas

Muchos modificadores de SwiftUI cumplen con Animatable:

Efectos visuales

  • .scaleEffect() — Anima la transformación de escala
  • .rotationEffect() — Anima la rotación
  • .offset() — Anima el desplazamiento de posición
  • .opacity() — Anima la transparencia
  • .blur() — Anima el radio de desenfoque
  • .shadow() — Anima las propiedades de sombra

Todos los tipos de Shape

  • Circle, Rectangle, RoundedRectangle
  • Capsule, Ellipse, Path
  • Implementaciones personalizadas de Shape

AnimatablePair para datos multidimensionales

Al animar múltiples propiedades, usa AnimatablePair para combinar vectores. Por ejemplo, scaleEffect combina CGSize (2D) y UnitPoint (2D) en un vector 4D mediante AnimatablePair<CGSize.AnimatableData, UnitPoint.AnimatableData>. Accede a los componentes mediante .first y .second. La macro @Animatable (iOS 26+) elimina por completo este código repetitivo.

Conformidad Animatable personalizada

Cuándo usarla

  • Animar un diseño personalizado (como RadialLayout)
  • Animar código de dibujo personalizado
  • Animar propiedades que afectan a trazados de formas

Ejemplo: Vista 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)

Cómo funciona

  1. number cambia de 0 a 100
  2. SwiftUI llama a body para cada cuadro de la animación
  3. Cada cuadro recibe un nuevo valor de number: 0 → 5 → 15 → 30 → 55 → 80 → 100
  4. El texto se actualiza para mostrar el entero interpolado

Advertencia de rendimiento

La conformidad Animatable personalizada es costosa: SwiftUI llama a body para cada cuadro en el hilo principal. Los efectos incorporados (.scaleEffect(), .opacity()) se ejecutan fuera del hilo principal y no llaman a body. Usa conformidad personalizada solo cuando los modificadores incorporados no puedan lograr el efecto (por ejemplo, animar un Layout personalizado que reposiciona subvistas por cuadro).


Parte 3: Macro @Animatable (iOS 26+)

Descripción general

La macro @Animatable elimina el código repetitivo de la conformidad manual con el protocolo Animatable.

Antes de iOS 26, tenías que:

  1. Cumplir manualmente con Animatable
  2. Escribir el getter y setter de animatableData
  3. Usar AnimatablePair para múltiples propiedades
  4. Excluir propiedades no animables manualmente

iOS 26+, solo añades @Animatable:

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

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

La macro automáticamente:

  • Genera la conformidad con Animatable
  • Inspecciona todas las propiedades almacenadas
  • Crea animatableData a partir de propiedades que cumplen con VectorArithmetic
  • Maneja datos multidimensionales con AnimatablePair

Comparación antes/después

Antes de la macro @Animatable

struct HikingRouteShape: Shape {
    var startPoint: CGPoint
    var endPoint: CGPoint
    var elevation: Double
    var drawingDirection: Bool // No quieres animar esto

    // Declaración tediosa y manual de 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 {
        // Código de dibujo
    }
}

Después de la macro @Animatable

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

    @AnimatableIgnored
    var drawingDirection: Bool // Excluido de la animación

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

Líneas de código: 20 → 12 (40% de reducción)

@AnimatableIgnored

Usa @AnimatableIgnored para excluir propiedades de la animación.

Cuándo usarlo

  • Valores de depuración: Banderas solo para desarrollo
  • IDs: Identificadores que no deberían animarse
  • Marcas de tiempo: Cuándo se creó/actualizó la vista
  • Estado interno: Contabilidad no visual
  • Tipos que no son VectorArithmetic: Colores, cadenas, booleanos

Ejemplo

@MainActor
@Animatable
struct ProgressView: View {
    var progress: Double // Animado
    var totalItems: Int // Animado (si es Float, no si es Int)

    @AnimatableIgnored
    var title: String // No animado

    @AnimatableIgnored
    var startTime: Date // No animado

    @AnimatableIgnored
    var debugEnabled: Bool // No animado

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

Caso de uso real

@Animatable funciona para cualquier visualización numérica: precios de acciones, frecuencia cardíaca, puntuaciones, temporizadores, barras de progreso:

@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: "Precio")
    .animation(.spring(duration: 0.8), value: currentPrice)

Parte 4: Tipos de animación

Animaciones de curva temporal

Las animaciones de curva temporal usan curvas bezier para controlar la velocidad de la animación a lo largo del tiempo.

Valores preestablecidos incorporados

.animation(.linear)          // Velocidad constante
.animation(.easeIn)          // Comienza lento, termina rápido
.animation(.easeOut)         // Comienza rápido, termina lento
.animation(.easeInOut)       // Inicio y final lentos, medio rápido

Curvas temporales personalizadas

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

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

Duración

Todas las animaciones de curva temporal aceptan una duración opcional:

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

Valor predeterminado: 0.35 segundos

Animaciones Spring

Las animaciones spring utilizan simulación física para crear movimiento natural y orgánico.

Valores preestablecidos incorporados

.animation(.smooth)     // Sin rebote (predeterminado desde iOS 17)
.animation(.snappy)     // Pequeña cantidad de rebote
.animation(.bouncy)     // Mayor cantidad de rebote

Springs personalizados

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

Parámetros

  • duration — Duración de la animación percibida
  • bounce — Cantidad de rebote (0 = sin rebote, 1 = muy rebotado)

Mucho más intuitivo que los parámetros spring tradicionales (masa, rigidez, amortiguación).

Animaciones de orden superior

Modifica animaciones base para crear efectos complejos.

Retardo

.animation(.spring.delay(0.5))

Espera 0.5 segundos antes de iniciar la animación.

Repetición

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

Repite la animación varias veces o infinitamente.

Velocidad

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

Multiplica la velocidad de la animación.

Cambios en la animación predeterminada (iOS 17+)

Antes de iOS 17

withAnimation {
    // Usaba curva temporal por defecto
}

iOS 17+

withAnimation {
    // Usa .smooth spring por defecto
}

Por qué el cambio: Las animaciones spring se sienten más naturales y conservan la velocidad cuando se interrumpen.

Recomendación: Adopta los springs. Hacen que tu interfaz de usuario se sienta más receptiva y pulida.


Parte 5: Sistema de transacciones

withAnimation

La forma más común de activar una animación.

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

Cómo funciona

  1. withAnimation abre una transacción
  2. Establece la animación en el diccionario de la transacción
  3. Ejecuta el bloque (cambios de estado)
  4. La transacción se propaga hacia abajo en la jerarquía de vistas
  5. Los atributos animables verifican la animación e interpolan

Animación explícita

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

Sin animación

withAnimation(nil) {
    // Los cambios ocurren inmediatamente, sin animación
    resetState()
}

Modificador de vista animation()

Aplica animaciones a valores específicos dentro de una vista.

Uso básico

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

Cómo funciona: La animación solo se aplica cuando cambia isActive. Otros cambios de estado no activarán esta animación.

Múltiples animaciones en la misma vista

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

Diferentes animaciones para diferentes propiedades.

Animaciones con ámbito (iOS 17+)

Limita estrechamente las animaciones a atributos animables específicos.

Problema con el enfoque anterior

struct AvatarView: View {
    var selected: Bool

    var body: some View {
        Image("avatar")
            .scaleEffect(selected ? 1.5 : 1.0)
            .animation(.spring, value: selected)
            // ⚠️ Si la imagen también cambia cuando selected cambia,
            //    la transición de imagen también se anima (accidental)
    }
}

Solución: Animación con ámbito

struct AvatarView: View {
    var selected: Bool

    var body: some View {
        Image("avatar")
            .animation(.spring, value: selected) {
                $0.scaleEffect(selected ? 1.5 : 1.0)
            }
            // ✅ Solo scaleEffect se anima, la transición de imagen no
    }
}

Cómo funciona

  • La animación solo se aplica a los atributos en el bloque
  • Otros atributos no se ven afectados
  • Previene animaciones accidentales

Claves de transacción personalizadas

Define tipos TransactionKey personalizados para propagar contexto a través del sistema de transacciones. Usa withTransaction para establecer valores y el modificador .transaction para leerlos. Esto permite aplicar diferentes animaciones según cómo se activó un cambio de estado (toque vs. programático).


Parte 6: Temas avanzados

Protocolo CustomAnimation

Implementa tu propio motor de animación para efectos personalizados. Puedes crear interpoladores cuadro por cuadro (por ejemplo, mecánica de rebote suave y realista), compatibles con el sistema de transacciones de SwiftUI.

Efectos visuales y GeometryEffect

El protocolo GeometryEffect (ahora obsoleto en iOS 18) te permitía modificar el layout y la posición durante la animación. Los efectos visuales modernos (visualEffect) superan esta funcionalidad con mejor rendimiento y seguridad de tipos. Úsalos para:

  • Transformaciones de parallax animadas
  • Distorsiones de cuadrícula
  • Efectos de lente de aumento

Animaciones de Layout y Grid

Anima la disposición espacial de las subvistas. Perfecto para diseños de cuadrícula que se reordenan dinámicamente, álbumes de fotos con transiciones suaves y dashboards adaptativos.

Transiciones de zoom (iOS 18+)

El modificador .zoomTransition() proporciona animaciones suaves de zoom entre vistas. Ideal para transiciones a pantalla completa en galerías de fotos, expansión de tarjetas de detalle de productos y animaciones de tarjetas de perfil. Se integra con NavigationTransition y proporciona gestos interactivos.

Puente de animación UIKit/AppKit (iOS 18+)

Nota: Las animaciones de UIView/CALayer no se pueden anidar dentro del cuerpo de una vista de SwiftUI. Si se requiere animación basada en CALayer, consulta las alternativas de efectos visuales de iOS 18.

Animación basada en el estado de carga

Controla las animaciones según el estado de las operaciones asíncronas. Esto te permite:

  • Animar la transición de cargando a contenido
  • Usar diferentes curvas de animación para los estados de error
  • Aplicar velocidades de animación variables dependiendo de la duración de la operación

Temporizadores animados y animaciones para wearables

Crea animaciones precisas y adaptables para seguidores de fitness, cronómetros y pantallas de watchOS. Consideraciones clave:

  • Usar Canvas en lugar de vistas para renderizado eficiente de 60 FPS en watchOS
  • Desactivar actualizaciones de animación cuando la corona digital esté activa
  • Preferir animaciones con valores preestablecidos (.smooth, .snappy) sobre curvas personalizadas para wearables debido a limitaciones de rendimiento

Notas de la versión

iOS 26

  • Macro @Animatable
  • Elimina código repetitivo manual de Animatable
  • @AnimatableIgnored para propiedades excluidas

iOS 18

  • Transiciones de zoom (.zoomTransition())
  • Efectos visuales (visualEffect) reemplazan a GeometryEffect
  • Puente de animación UIKit/AppKit

iOS 17

  • Animación spring por defecto en withAnimation
  • Animaciones con ámbito (sintaxis de bloque)
  • PhaseAnimator para animaciones por fases
  • KeyframeAnimator para animaciones basadas en fotogramas clave

iOS 16

  • Animaciones basadas en Layout
  • Mejoras de Layout con animación

iOS 15

  • Efecto de sombra animable
  • Mejoras en ControlGroup

iOS 14

  • Mejoras en LazyHStack/LazyVStack

iOS 13

  • Lanzamiento de SwiftUI
  • Sistema de animación fundamental
  • Animaciones de curva temporal

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