SwiftUI Screen Skill

Expert guidance for implementing native iOS SwiftUI screens backed by shared Kotlin Multiplatform ViewModels. Focus on SwiftUI integration, StateFlow bridging, and iOS lifecycle management.

When to Use

Use this skill when:

• •Implementing SwiftUI screens consuming KMP ViewModels
• •Bridging StateFlow to SwiftUI with @State properties
• •Setting up iOS lifecycle management (onAppear/onDisappear)
• •Creating SwiftUI Previews with mock ViewModels
• •Working with parametric ViewModels (pokemonId, userId)
• •Using SKIE for Kotlin-Swift interop
• •Deciding between Direct Integration vs Wrapper pattern

Do NOT use this skill for:

• •Shared ViewModel implementation → switch to KMP Mobile Expert Mode
• •Compose UI implementation → switch to Compose Screen Implementation Mode
• •Product/PRD decisions → switch to Product Design Mode
• •Visual design/animations → switch to UI/UX Design Mode

Mode Detection

Essential Workflows

Workflow 1: Direct Integration (Current Pattern)

Use Direct Integration for simple to medium complexity apps with linear navigation:

1. •

   Create SwiftUI View with Direct ViewModel Access

   swift

   import SwiftUI
   import Shared
   
   struct PokemonListView: View {
       // Direct ViewModel access from Koin
       private var viewModel = KoinIosKt.getPokemonListViewModel()
   
       // @State bridges StateFlow to SwiftUI
       @State private var uiState: PokemonListUiState = PokemonListUiStateLoading()
   
       var body: some View {
           content
               .onAppear {
                   // Load data on first appear
                   if case is PokemonListUiStateLoading = uiState {
                       viewModel.loadInitialPage()
                   }
               }
               .task {
                   // Observe StateFlow - auto-cancels on view disappear
                   for await state in viewModel.uiState {
                       self.uiState = state
                   }
               }
       }
   }
   

2. •

   Handle UI States with Switch

   swift

   @ViewBuilder
   private var content: some View {
       switch uiState {
       case is PokemonListUiStateLoading:
           ProgressView("Loading...")
   
       case let error as PokemonListUiStateError:
           ErrorView(message: error.message) {
               viewModel.loadInitialPage() // Retry
           }
   
       case let content as PokemonListUiStateContent:
           PokemonListGrid(
               pokemons: content.pokemons,
               onLoadMore: { viewModel.loadNextPage() }
           )
   
       default:
           EmptyView()
       }
   }
   

3. •

   Test and Validate

   • •Verify StateFlow updates SwiftUI @State correctly
   • •Test loading, error, and content states
   • •Confirm .task cancels on view disappear (no memory leaks)
   • •Run iOS build in Xcode: open iosApp/iosApp.xcodeproj

Workflow 2: Parametric ViewModels

Use when ViewModels require constructor parameters (e.g., pokemonId, userId):

1. •

   Create Koin Helper with Parameters

   kotlin

   // shared/src/iosMain/kotlin/KoinIos.kt
   fun getPokemonDetailViewModel(pokemonId: Int): PokemonDetailViewModel {
       return KoinPlatform.getKoin().get { parametersOf(pokemonId) }
   }
   

2. •

   Create SwiftUI View with Initialization

   swift

   import SwiftUI
   import Shared
   
   struct PokemonDetailView: View {
       let pokemonId: Int
       private var viewModel: PokemonDetailViewModel
   
       @State private var uiState: PokemonDetailUiState = PokemonDetailUiStateLoading()
   
       init(pokemonId: Int) {
           self.pokemonId = pokemonId
           // Get parametric ViewModel from Koin
           // Cast Swift Int to Kotlin Int32
           viewModel = KoinIosKt.getPokemonDetailViewModel(pokemonId: Int32(pokemonId))
       }
   
       var body: some View {
           content
               .task {
                   for await state in viewModel.uiState {
                       self.uiState = state
                   }
               }
       }
   }
   

3. •

   Handle Type Conversions

   swift

   // Kotlin Int32 → Swift Int conversion required
   String(format: "#%03d", Int(pokemon.id))  // pokemon.id is Int32
   String(format: "%.1f m", Double(pokemon.height) / 10.0)
   

Workflow 3: SwiftUI Previews with Mock Data

Create previews for all UI states to enable visual testing:

1. •

   Create Mock ViewModel Helper

   swift

   // iosApp/Previews/MockViewModels.swift
   import SwiftUI
   import Shared
   
   class MockPokemonListViewModel: ObservableObject {
       @Published var uiState: PokemonListUiState = PokemonListUiStateLoading()
   
       init(state: PokemonListUiState) {
           self.uiState = state
       }
   }
   

2. •

   Create Preview Variants

   swift

   #Preview("Loading") {
       PokemonListView_Previews.LoadingPreview()
   }
   
   #Preview("Error") {
       PokemonListView_Previews.ErrorPreview()
   }
   
   #Preview("Content") {
       PokemonListView_Previews.ContentPreview()
   }
   
   extension PokemonListView_Previews {
       static func LoadingPreview() -> some View {
           PokemonListView()
               .environment(\.mockViewModel, MockPokemonListViewModel(
                   state: PokemonListUiStateLoading()
               ))
       }
   
       static func ErrorPreview() -> some View {
           PokemonListView()
               .environment(\.mockViewModel, MockPokemonListViewModel(
                   state: PokemonListUiStateError(message: "Network error")
               ))
       }
   
       static func ContentPreview() -> some View {
           PokemonListView()
               .environment(\.mockViewModel, MockPokemonListViewModel(
                   state: PokemonListUiStateContent(
                       pokemons: persistentListOf(
                           Pokemon(name: "Bulbasaur", detailUrl: "..."),
                           Pokemon(name: "Charmander", detailUrl: "...")
                       ),
                       hasMore: true
                   )
               ))
       }
   }
   

3. •

   Validate Previews in Xcode

   • •Open Xcode: open iosApp/iosApp.xcodeproj
   • •Navigate to the SwiftUI file
   • •Verify all preview states render correctly
   • •Check for layout issues at different device sizes

Critical Guardrails

Quick Reference

Key Patterns

Type Conversion Cheat Sheet

Common SKIE Renamed Types

Validation Commands

Cross-References

Documentation Links

Related Skills

Reference Implementations

Decision Guides

When to Use Direct Integration vs Wrapper Pattern:

See ios_integration.md for complete comparison and migration guide.