Communitygithub.com

ComeOnOliver/skillshub

Referencia — Guía completa de la API de diseño adaptable de SwiftUI que cubre ViewThatFits, AnyLayout, el protocolo Layout, onGeometryChange, GeometryReader, clases de tamaño y las APIs de ventanas de iOS 26

¿Qué es skillshub?

Este skill proporciona una referencia completa y detallada de todas las APIs de diseño adaptable de SwiftUI, diseñada para desarrolladores que construyen interfaces de usuario adaptables en iOS, iPadOS y macOS. Cubre desde APIs fundamentales como `ViewThatFits` y `AnyLayout` (iOS 16+) hasta el protocolo `Layout` para algoritmos de diseño personalizados, así como herramientas eficientes de lectura de geometría como `onGeometryChange` y `GeometryReader`. También incluye guías prácticas sobre el manejo de áreas seguras con `.safeAreaPadding()` y clases de tamaño, además de las nuevas APIs de ventanas de iOS 26 para ventanas de forma libre y barras de menú. El skill es una referencia técnica ideal para consultar patrones de uso, comparativas entre APIs y ejemplos de código Swift listos para implementar, ayudando a los desarrolladores a evitar antipatrones y a elegir la herramienta de diseño correcta para cada escenario. Está diseñado para ser utilizado como complemento de otros skills de decisión sobre diseño en SwiftUI.

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

Preguntar en tu IA favorita

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

Documentación

Referencia de la API de Diseño de SwiftUI

Referencia completa de la API para herramientas de diseño adaptable en SwiftUI. Para orientación sobre decisiones y antipatrones, consulta el skill axiom-swiftui-layout.

Resumen

Esta referencia cubre todas las APIs de diseño de SwiftUI para construir interfaces adaptables:

  • ViewThatFits — Selección automática de variantes (iOS 16+)
  • AnyLayout — Cambio de diseño animado con borrado de tipo (iOS 16+)
  • Protocolo Layout — Algoritmos de diseño personalizados (iOS 16+)
  • onGeometryChange — Lectura eficiente de geometría (iOS 16+ retroportado)
  • GeometryReader — Acceso a geometría en la fase de diseño (iOS 13+)
  • Relleno de Área Segura — .safeAreaPadding() vs .padding() (iOS 17+)
  • Clases de Tamaño — Adaptación basada en rasgos
  • APIs de Ventanas de iOS 26 — Ventanas de forma libre, barra de menú, anclas de redimensionamiento

ViewThatFits

Evalúa las vistas hijas en orden y muestra la primera que quepa en el espacio disponible.

Uso Básico

ViewThatFits {
    // Primera opción
    HStack {
        icon
        title
        Spacer()
        button
    }

    // Segunda opción
    HStack {
        icon
        title
        button
    }

    // Opción de respaldo
    VStack {
        HStack { icon; title }
        button
    }
}

Con Restricción de Eje

// Considera solo el ajuste horizontal
ViewThatFits(in: .horizontal) {
    wideVersion
    narrowVersion
}

// Considera solo el ajuste vertical
ViewThatFits(in: .vertical) {
    tallVersion
    shortVersion
}

Cómo Funciona

  1. Aplica fixedSize() a cada hija
  2. Mide el tamaño ideal contra el espacio disponible
  3. Devuelve la primera hija que quepa
  4. Usa la última hija como respaldo si ninguna cabe

Limitaciones

  • No expone qué variante fue seleccionada
  • No puede animar entre variantes (usa AnyLayout en su lugar)
  • Mide todas las variantes (consideración de rendimiento para vistas complejas)

AnyLayout

Contenedor de diseño con borrado de tipo que permite transiciones animadas entre diseños.

Uso Básico

struct AdaptiveView: View {
    @Environment(\.horizontalSizeClass) var sizeClass

    var layout: AnyLayout {
        sizeClass == .compact
            ? AnyLayout(VStackLayout(spacing: 12))
            : AnyLayout(HStackLayout(spacing: 20))
    }

    var body: some View {
        layout {
            ForEach(items) { item in
                ItemView(item: item)
            }
        }
        .animation(.default, value: sizeClass)
    }
}

Tipos de Diseño Disponibles

AnyLayout(HStackLayout(alignment: .top, spacing: 10))
AnyLayout(VStackLayout(alignment: .leading, spacing: 8))
AnyLayout(ZStackLayout(alignment: .center))
AnyLayout(GridLayout(alignment: .leading, horizontalSpacing: 10, verticalSpacing: 10))

Condiciones Personalizadas

// Basado en Dynamic Type
@Environment(\.dynamicTypeSize) var typeSize

var layout: AnyLayout {
    typeSize.isAccessibilitySize
        ? AnyLayout(VStackLayout())
        : AnyLayout(HStackLayout())
}

// Basado en geometría
@State private var isWide = true

var layout: AnyLayout {
    isWide
        ? AnyLayout(HStackLayout())
        : AnyLayout(VStackLayout())
}

Por Qué Usarlo en Lugar de Vistas Condicionales

// ❌ Pierde la identidad de la vista, sin animación
if isCompact {
    VStack { content }
} else {
    HStack { content }
}

// ✅ Conserva la identidad, animación suave
let layout = isCompact ? AnyLayout(VStackLayout()) : AnyLayout(HStackLayout())
layout { content }

Protocolo Layout

Crea contenedores de diseño personalizados con control total sobre el posicionamiento.

Diseño Personalizado Básico

struct FlowLayout: Layout {
    var spacing: CGFloat = 8

    func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) -> CGSize {
        let sizes = subviews.map { $0.sizeThatFits(.unspecified) }
        return calculateSize(for: sizes, in: proposal.width ?? .infinity)
    }

    func placeSubviews(in bounds: CGRect, proposal: ProposedViewSize, subviews: Subviews, cache: inout ()) {
        var point = bounds.origin
        var lineHeight: CGFloat = 0

        for subview in subviews {
            let size = subview.sizeThatFits(.unspecified)

            if point.x + size.width > bounds.maxX {
                point.x = bounds.origin.x
                point.y += lineHeight + spacing
                lineHeight = 0
            }

            subview.place(at: point, proposal: .unspecified)
            point.x += size.width + spacing
            lineHeight = max(lineHeight, size.height)
        }
    }
}

// Uso
FlowLayout(spacing: 12) {
    ForEach(tags) { tag in
        TagView(tag: tag)
    }
}

Con Caché

struct CachedLayout: Layout {
    struct CacheData {
        var sizes: [CGSize] = []
    }

    func makeCache(subviews: Subviews) -> CacheData {
        CacheData(sizes: subviews.map { $0.sizeThatFits(.unspecified) })
    }

    func sizeThatFits(proposal: ProposedViewSize, subviews: Subviews, cache: inout CacheData) -> CGSize {
        // Usa cache.sizes en lugar de medir de nuevo
    }
}

Valores de Diseño

// Define un valor de diseño personalizado
struct Rank: LayoutValueKey {
    static let defaultValue: Int = 0
}

extension View {
    func rank(_ value: Int) -> some View {
        layoutValue(key: Rank.self, value: value)
    }
}

// Lectura en el diseño
func placeSubviews(...) {
    let sorted = subviews.sorted { $0[Rank.self] < $1[Rank.self] }
}

onGeometryChange

Lectura eficiente de geometría sin efectos secundarios en el diseño. Retroportado a iOS 16+.

Uso Básico

@State private var size: CGSize = .zero

var body: some View {
    content
        .onGeometryChange(for: CGSize.self) { proxy in
            proxy.size
        } action: { newSize in
            size = newSize
        }
}

Lectura de Valores Específicos

// Solo ancho
.onGeometryChange(for: CGFloat.self) { proxy in
    proxy.size.width
} action: { width in
    columnCount = max(1, Int(width / 150))
}

// Marco en espacio de coordenadas
.onGeometryChange(for: CGRect.self) { proxy in
    proxy.frame(in: .global)
} action: { frame in
    globalFrame = frame
}

// Relación de aspecto
.onGeometryChange(for: Bool.self) { proxy in
    proxy.size.width > proxy.size.height
} action: { isWide in
    self.isWide = isWide
}

Espacios de Coordenadas

// Espacio de coordenadas nombrado
ScrollView {
    content
        .onGeometryChange(for: CGFloat.self) { proxy in
            proxy.frame(in: .named("scroll")).minY
        } action: { offset in
            scrollOffset = offset
        }
}
.coordinateSpace(name: "scroll")

Comparación con GeometryReader

AspectoonGeometryChangeGeometryReader
Impacto en el diseñoNingunoCodicioso (ocupa espacio)
Cuándo se evalúaDespués del diseñoDurante el diseño
Caso de usoEfectos secundariosCálculos de diseño
Versión de iOS16+ (retroportado)13+

GeometryReader

Proporciona información de geometría durante la fase de diseño. Úsalo con moderación debido a su tamaño codicioso.

Uso Básico (Restringido)

// ✅ Siempre restringe GeometryReader
GeometryReader { proxy in
    let width = proxy.size.width
    HStack(spacing: 0) {
        Rectangle().frame(width: width * 0.3)
        Rectangle().frame(width: width * 0.7)
    }
}
.frame(height: 100)  // Restricción necesaria

Propiedades de GeometryProxy

GeometryReader { proxy in
    // Tamaño del contenedor
    let size = proxy.size  // CGSize

    // Inserciones de área segura
    let insets = proxy.safeAreaInsets  // EdgeInsets

    // Marco en espacio de coordenadas
    let globalFrame = proxy.frame(in: .global)
    let localFrame = proxy.frame(in: .local)
    let namedFrame = proxy.frame(in: .named("container"))
}

Patrones Comunes

// Tamaño proporcional
GeometryReader { geo in
    VStack {
        header.frame(height: geo.size.height * 0.2)
        content.frame(height: geo.size.height * 0.8)
    }
}

// Centrado con desplazamiento
GeometryReader { geo in
    content
        .position(x: geo.size.width / 2, y: geo.size.height / 2)
}

Evitando Errores Comunes

// ❌ Sin restricción en VStack
VStack {
    GeometryReader { ... }  // Ocupa TODO el espacio
    Button("Siguiente") { }       // Invisible
}

// ✅ Restringido
VStack {
    GeometryReader { ... }
        .frame(height: 200)
    Button("Siguiente") { }
}

// ❌ Causando bucles de diseño
GeometryReader { geo in
    content
        .frame(width: geo.size.width)  // Puede causar bucle infinito
}

Relleno de Área Segura

SwiftUI ofrece dos enfoques principales para manejar el espaciado alrededor del contenido: .padding() y .safeAreaPadding(). Entender cuándo usar cada uno es crucial para un diseño adecuado en dispositivos con áreas seguras (notch, Dynamic Island, indicador de inicio).

La Diferencia Crítica

// ❌ INCORRECTO - Ignora áreas seguras, el contenido choca con el notch/indicador
ScrollView {
    content
}
.padding(.horizontal, 20)

// ✅ CORRECTO - Respeta áreas seguras, añade padding más allá de ellas
ScrollView {
    content
}
.safeAreaPadding(.horizontal, 20)

Insight clave: .padding() añade espaciado fijo desde los bordes de la vista. .safeAreaPadding() añade espaciado más allá de las inserciones de área segura.

Cuándo Usar Cada Uno

Usa .padding() cuando

  • Añadas espaciado entre vistas hermanas dentro de un contenedor
  • Crear espaciado interno que debe ser consistente en todas partes
  • Trabajar con vistas que ya respetan áreas seguras (como List, Form)
  • Añadir espaciado decorativo en macOS (sin preocupaciones de área segura)
VStack(spacing: 0) {
    header
        .padding(.horizontal, 16)  // ✅ Espaciado interno

    Divider()

    content
        .padding(.horizontal, 16)  // ✅ Espaciado interno
}

Usa .safeAreaPadding() cuando (iOS 17+)

  • Añadir margen a contenido de ancho completo que se extiende hasta los bordes de la pantalla
  • Implementar desplazamiento de borde a borde con inserciones adecuadas
  • Crear contenedores personalizados que necesiten conocimiento del área segura
  • Trabajar con Liquid Glass o materiales de pantalla completa
// ✅ Lista de borde a borde con padding personalizado
List(items) { item in
    ItemRow(item)
}
.listStyle(.plain)
.safeAreaPadding(.horizontal, 20)  // Añade 20pt más allá de áreas seguras

// ✅ Contenido de pantalla completa con márgenes adecuados
ZStack {
    Color.blue.ignoresSafeArea()

    VStack {
        content
    }
    .safeAreaPadding(.all, 16)  // Respeta notch, indicador de inicio
}

Disponibilidad en Plataformas

iOS 17+, iPadOS 17+, macOS 14+, axiom-visionOS 1.0+

Para versiones anteriores de iOS, usa manejo manual del área segura:

// iOS 13-16 como respaldo
GeometryReader { geo in
    content
        .padding(.horizontal, 20 + geo.safeAreaInsets.leading)
}

O compilación condicional:

if #available(iOS 17, *) {
    content.safeAreaPadding(.horizontal, 20)
} else {
    content.padding(.horizontal, 20)
        .padding(.leading, safeAreaInsets.leading)
}

Uso Específico por Borde

// Solo superior (debajo de la barra de estado/notch)
.safeAreaPadding(.top, 8)

// Solo inferior (encima del indicador de inicio)
.safeAreaPadding(.bottom, 16)

// Horizontal (izquierda/derecha de áreas seguras)
.safeAreaPadding(.horizontal, 20)

// Todos los bordes
.safeAreaPadding(.all, 16)

// Bordes individuales
.safeAreaPadding(EdgeInsets(top: 8, leading: 20, bottom: 16, trailing: 20))

Patrones Comunes

ScrollView de Borde a Borde

ScrollView {
    LazyVStack(spacing: 12) {
        ForEach(items) { item in
            ItemCard(item)
        }
    }
}
.safeAreaPadding(.horizontal, 16)  // Inserción de contenido desde bordes + áreas seguras
.safeAreaPadding(.vertical, 8)

Fondo de Pantalla Completa con Contenido Seguro

ZStack {
    // El fondo se extiende de borde a borde
    LinearGradient(...)
        .ignoresSafeArea()

    // El contenido respeta áreas seguras + padding personalizado
    VStack {
        header
        Spacer()
        content
        Spacer()
        footer
    }
    .safeAreaPadding(.all, 20)
}

Padding Anidado (Enfoque Combinado)

// Externo: Padding de área segura para inserciones del dispositivo
VStack(spacing: 0) {
    content
}
.safeAreaPadding(.horizontal, 16)  // Más allá de áreas seguras

// Interno: Padding regular para espaciado interno
VStack {
    Text("Título")
        .padding(.bottom, 8)  // Espaciado interno
    Text("Subtítulo")
}

Árbol de Decisión

¿Tu contenido se extiende hasta los bordes de la pantalla?
├─ SÍ → Usa .safeAreaPadding()
│   ├─ ¿Es desplazable? → .safeAreaPadding(.horizontal/.vertical)
│   └─ ¿Es de pantalla completa? → .safeAreaPadding(.all)
│
└─ NO (contenido dentro de un contenedor seguro como List/Form)
    └─ Usa .padding() para espaciado interno

Depuración Visual

// Visualiza el padding de área segura (iOS 17+)
content
    .safeAreaPadding(.horizontal, 20)
    .background(.red.opacity(0.2))  // Muestra el área de padding
    .border(.blue)  // Muestra los límites del contenido

Migración desde Manejo Manual de Área Segura

// ❌ ANTIGUO: Cálculo manual (iOS 13-16)
GeometryReader { geo in
    content
        .padding(.top, geo.safeAreaInsets.top + 16)
        .padding(.bottom, geo.safeAreaInsets.bottom + 16)
        .padding(.horizontal, 20)
}

// ✅ NUEVO: .safeAreaPadding() (iOS 17+)
content
    .safeAreaPadding(.vertical, 16)
    .safeAreaPadding(.horizontal, 20)

APIs Relacionadas

.safeAreaInset(edge:) - Añade contenido persistente que reduce el área segura:

ScrollView {
    content
}
.safeAreaInset(edge: .bottom) {
    // Esto REDUCE el área segura, el contenido se desplaza debajo
    toolbarButtons
        .padding()
        .background(.ultraThinMaterial)
}

.ignoresSafeArea() - Opta por salir completamente del área segura:

Color.blue
    .ignoresSafeArea()  // Se extiende hasta los bordes absolutos de la pantalla

Por Qué es Importante

Antes de iOS 17: Los desarrolladores tenían que calcular manualmente las inserciones de área segura con GeometryReader, lo que conllevaba:

  • Código verboso
  • Sobrecarga de rendimiento (GeometryReader fuerza un pase de diseño extra)
  • Errores fáciles (olvidar verificar todos los bordes)

iOS 17+: .safeAreaPadding() proporciona:

  • API declarativa (coincide con la filosofía de SwiftUI)
  • Conocimiento automático del área segura
  • Mejor rendimiento (sin pases de diseño extra)
  • Especificación de bordes con seguridad de tipos

Impacto en el mundo real

...

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