dot-skills — Airbnb iOS SwiftUI Animations Best Practices
Guía de animaciones estricta y pragmática para aplicaciones SwiftUI iOS 26 / Swift 6.2. Contiene 50 reglas distribuidas en 8 categorías, priorizadas por impacto. Derivada de patrones de motion de Airbnb Engineering, sesiones de Apple WWDC y las guías de interfaz humana de Apple. Exige el uso de @Equatable en cada vista animada, tokens de motion para todos los valores de spring y timing, y tokens del sistema de diseño para el layout.
Alineación Arquitectónica Obligatoria
Este skill está diseñado para trabajar junto a swift-ui-architect e ios-design-system. Todos los ejemplos de código siguen las mismas restricciones no negociables:
- Macro
@Equatableen cada vista (Airbnb midió una reducción del 15% en el hitch de desplazamiento) @Observablepara estados de animación complejos que involucran disparadores de lógica de negocio@Statepara estados de animación propiedad de la vista (booleanos de toggle, offsets de arrastre)- Tokens del sistema de diseño:
Spacing.xs/sm/md/lg,Radius.sm/md/lg— cero números de layout hardcodeados - Tokens de motion:
Motion.standard/responsive/playful— cero literales de spring dispersos - Colores semánticos:
.backgroundSurface,.accentPrimary— sin literales de Color crudos en las vistas - Las animaciones de características son solo de presentación; las preocupaciones de datos/red permanecen en el paquete Data
Alcance y Relación con Skills Hermanos
Este skill es la capa de motion — enseña cómo CONSTRUIR animaciones fluidas y con buen rendimiento. Cuando se carga junto a skills hermanos:
| Skill Hermano | Su Enfoque | Enfoque de Este Skill |
|---|---|---|
swift-ui-architect | Arquitectura (MVVM-C modular, shells de ruta, límites de protocolo) | Arquitectura de animación (tokens de motion, selección de spring, orquestación) |
ios-design-system | Infraestructura del sistema de diseño (tokens, estilos, gobierno) | Tokens de motion y patrones de componentes animados |
ios-hig | Cumplimiento de HIG | HIG específico de motion (reduce motion, continuidad espacial) |
Fuera de alcance: Animaciones vectoriales creadas por diseñadores (usar Lottie para exportaciones de After Effects). Controladores de transición complejos de UIKit (ver el marco de transición declarativa de Airbnb). Este skill cubre solo animaciones programáticas en SwiftUI.
Contrato de Arquitectura de Clínica (iOS 26 / Swift 6.2)
Toda la guía en este skill asume la arquitectura modular MVVM-C de clínica:
- Los módulos de características importan solo
Domain+DesignSystem(nuncaData, nunca características hermanas) - El target App es el punto de convergencia y posee
DependencyContainer, coordinadores concretos y el cableado del Route Shell Domainpermanece puro Swift y define modelos más repositorio, contratos*Coordinating,ErrorRoutingyAppErrorDataposee SwiftData/red/sincronización/reintento/E/S en segundo plano e implementa los protocolos de Domain- El flujo de lectura/escritura por defecto es lecturas stale-while-revalidate y escrituras en cola optimistas
- Los ViewModels llaman directamente a los protocolos de repositorio (sin capa de casos de uso/interactores por defecto)
Cuándo Aplicar
Consulte estas pautas al:
- Agregar animaciones a vistas o transiciones de SwiftUI
- Construir interacciones basadas en gestos (arrastrar, deslizar, mover)
- Conectar vistas con transiciones espaciales (expandir/contraer, morphs de navegación)
- Diseñar micro-interacciones (presión de botón, toggle, estados de carga)
- Hacer que los cambios de contenido se sientan físicos (ruedas de números, reemplazos de símbolos)
- Coreografiar secuencias de animación de múltiples elementos (KeyframeAnimator, PhaseAnimator)
- Definir tokens de motion para un sistema de diseño
- Revisar código de animación en cuanto a rendimiento, accesibilidad y cumplimiento arquitectónico
Categorías de Reglas por Prioridad
| Prioridad | Categoría | Impacto | Prefijo | Reglas |
|---|---|---|---|---|
| 1 | Física de Spring | CRÍTICO | spring- | 8 |
| 2 | Timing y Sensación | CRÍTICO | feel- | 6 |
| 3 | Continuidad de Gestos | ALTO | gesture- | 7 |
| 4 | Transiciones Espaciales | ALTO | spatial- | 6 |
| 5 | Micro-interacciones | ALTO | micro- | 6 |
| 6 | Orquestación | ALTO | orch- | 5 |
| 7 | Artesanía y Pulido | ALTO | craft- | 5 |
| 8 | Movimiento de Contenido | MEDIO-ALTO | content- | 5 |
Referencia Rápida
1. Física de Spring (CRÍTICO)
spring-motion-tokens— Definir tokens de motion como un enum sin casos para todos los presets de springspring-smooth-default— Usar .smooth spring por defecto para todas las transiciones de UIspring-snappy-responsive— Usar .snappy spring para interacciones responsivasspring-bouncy-celebration— Usar .bouncy spring para momentos lúdicos y de celebraciónspring-custom-parameters— Ajustar springs personalizados con response y dampingFractionspring-velocity-preservation— Los springs preservan la velocidad al ser interrumpidosspring-never-linear— Nunca usar linear o easeInOut para UI interactivaspring-completion-chaining— Usar withAnimation completion para secuencias encadenadas
2. Timing y Sensación (CRÍTICO)
feel-250ms-max— Mantener las animaciones de UI por debajo de 250msfeel-faster-better— Las animaciones más rápidas casi siempre se sienten mejorfeel-asymmetric-enter-exit— Usar timing asimétrico para entrada y salidafeel-distance-proportional— Igualar la duración a la distancia recorridafeel-haptic-sync— Sincronizar la retroalimentación háptica con los fotogramas clave de la animación visualfeel-stagger-timing— Escalonar las revelaciones en intervalos de 30-50ms
3. Continuidad de Gestos (ALTO)
gesture-rubber-band— Banda elástica en los límites de arrastregesture-momentum-dismiss— Descartar al alcanzar un umbral de velocidad O distanciagesture-snap-points— Usar puntos de ajuste conscientes de la velocidadgesture-interruptible— Hacer que todas las animaciones de gestos sean interrumpiblesgesture-scroll-drag-conflict— Resolver conflictos entre gestos de desplazamiento y arrastregesture-state-transient— Usar GestureState para estados de arrastre transitoriosgesture-projected-landing— Proyectar la velocidad del gesto para una posición de aterrizaje natural
4. Transiciones Espaciales (ALTO)
spatial-matched-geometry— Usar matchedGeometryEffect para morphs de expandir/contraerspatial-zoom-navigation— Usar transición de navegación con zoom para detalle de colección (iOS 18)spatial-transition-origin— Anclar las transiciones a su ubicación de disparospatial-hero-shared-element— Compartir múltiples IDs de elemento para animaciones hero ricasspatial-sheet-morph— Usar matchedGeometryEffect para presentaciones de hojasspatial-tab-continuity— Mantener la dirección espacial en transiciones de pestañas
5. Micro-interacciones (ALTO)
micro-button-press-scale— Escalar botones a 0.97 al presionar para retroalimentación táctilmicro-haptic-pairing— Emparejar cada cambio de estado visual con retroalimentación hápticamicro-symbol-effect— Usar symbolEffect para animaciones de SF Symbolmicro-toggle-bounce— Agregar rebote a los cambios de estado de togglemicro-long-press-fill— Animar el llenado progresivo para acciones de presión prolongadamicro-loading-phase— Usar spring repetitivo para estados de carga orgánicos
6. Orquestación (ALTO)
orch-phase-animator— Usar PhaseAnimator para secuencias de múltiples pasosorch-keyframe-animator— Usar KeyframeAnimator para movimiento preciso en la línea de tiempoorch-stagger-children— Escalonar elementos hijos para revelaciones orquestadasorch-coordinated-entrance— Coordinar entradas de múltiples elementos con un disparador compartidoorch-timeline-view— Usar TimelineView para animaciones repetitivas continuas
7. Artesanía y Pulido (ALTO)
craft-reduce-motion— Respetar accessibilityReduceMotion con un fallback de crossfadecraft-blur-bridge— Usar blur para puentear estados de transición imperfectoscraft-drawing-group— Usar drawingGroup() para animaciones complejas respaldadas por Metalcraft-geometry-group— Usar geometryGroup() para aislar la propagación de animaciones de layoutcraft-transaction-debug— Usar Transaction para depurar y sobrescribir el comportamiento de animaciones
8. Movimiento de Contenido (MEDIO-ALTO)
content-numeric-text— Usar contentTransition(.numericText) para cambios numéricoscontent-scroll-transition— Usar scrollTransition para efectos basados en la posición de desplazamientocontent-visual-effect— Usar visualEffect para animaciones conscientes de la posicióncontent-symbol-replace— Animar el reemplazo de símbolos con contentTransitioncontent-text-renderer— Usar Text Renderer para animación a nivel de caracteres (iOS 18)
Cómo Usar
Lea los archivos de referencia individuales para obtener explicaciones detalladas con ejemplos de código incorrecto/correcto:
- Definiciones de secciones — Estructura de categorías y niveles de impacto
- Plantilla de reglas — Plantilla para agregar nuevas reglas
Archivos de Referencia
| Archivo | Descripción |
|---|---|
| references/_sections.md | Definiciones de categorías y ordenamiento |
| assets/templates/_template.md | Plantilla para nuevas reglas |
| metadata.json | Información de versión y referencia |