Kapilmhr Ios26 Swiftui Skills IOS

iOS SwiftUI MVVM Skill

Description

This skill defines the architecture, conventions, patterns, and templates for iOS application development using SwiftUI + MVVM + async/await. It enforces scope-based feature isolation, mandatory preview stubs, extension-heavy code style, and protocol-based dependency injection.

Activates when: The task involves SwiftUI views, iOS app features, MVVM architecture, Swift models, ViewModels, repositories, networking, navigation, or any iOS-specific development.

Target: iOS 17+ · SwiftUI · Swift 5.9+ · @Observable macro · Swift Concurrency · Swift Testing

References

Project Structure — Mandatory Layout

ProjectName/
├── App/
│   ├── ProjectNameApp.swift              # @main, .environment() setup
│   ├── AppState.swift                    # @Observable shared app state
│   ├── Launch/
│   │   └── SplashScreen.swift            # Splash / launch animation screen
│   └── DI/
│       └── DependencyContainer.swift     # Core service registration
│
├── Network/
│   ├── NetworkService.swift              # Protocol + URLSession implementation
│   ├── Endpoint.swift                    # Enum-based API endpoint definitions
│   ├── HTTPMethod.swift                  # HTTP method enum
│   └── NetworkError.swift                # Network-layer error types
│
├── Core/
│   ├── Storage/
│   │   ├── SessionService.swift
│   │   └── KeychainService.swift
│   ├── Extensions/
│   │   ├── ViewModifiers.swift
│   │   ├── DateFormatting.swift
│   │   ├── StringValidation.swift
│   │   ├── ColorTheme.swift
│   │   └── URLRequestBuilder.swift
│   ├── Components/
│   │   ├── AppButton.swift
│   │   ├── AppTextField.swift
│   │   ├── LoadingView.swift
│   │   └── ErrorView.swift
│   ├── Theme/
│   │   ├── AppTheme.swift
│   │   ├── AppSpacing.swift
│   │   └── AppRadius.swift
│   ├── Utils/
│   │   ├── AppError.swift
│   │   └── ResultExtensions.swift
│   └── Constants/
│       ├── AppConstants.swift
│       ├── ApiEndpoints.swift
│       └── AppStrings.swift              # Shared localized string keys
│
├── Features/
│   └── {Feature}/
│       ├── Model/
│       │   ├── {Feature}Model.swift
│       │   └── {Feature}ModelStub.swift
│       ├── View/
│       │   ├── {Feature}Screen.swift
│       │   ├── {Feature}View.swift
│       │   └── {Feature}Row.swift        # Feature-specific components (flat, no subfolder)
│       ├── ViewModel/
│       │   ├── {Feature}ViewModel.swift
│       │   └── {Feature}ViewModelStub.swift
│       └── Repository/
│           ├── {Feature}Repository.swift
│           └── {Feature}RepositoryImpl.swift
│
├── Shared/
│   ├── Models/
│   ├── Views/
│   └── Modifiers/
│
├── Navigation/
│   ├── AppRouter.swift
│   ├── Route.swift
│   ├── MainTabView.swift
│   └── DeepLinkHandler.swift
│
└── Resources/
    ├── Assets.xcassets
    └── Localizable.xcstrings

Naming Conventions

CRITICAL: No + character in ANY filename. Use TypePurpose.swift not Type+Purpose.swift.

MVVM Architecture

View Layer          →  ViewModel Layer       →  Data Layer
(SwiftUI Views)       (@Observable classes)     (Repository + NetworkService)

- Renders UI          - Holds state            - Fetches data
- Dispatches actions  - Async business logic   - Maps responses
- Observes state      - Calls repository       - Returns Result<T, AppError>

Architecture Rules

1. Views never call NetworkService directly — always through ViewModel → Repository
2. ViewModels never import SwiftUI — only Foundation and domain types
3. Repositories never hold UI state — they return data, ViewModels manage state
4. NetworkService is generic — it doesn't know about specific models
5. Each layer depends only on the layer below it — no circular dependencies

State Management Rules

• All ViewModels use @Observable @MainActor — no @Published, no ObservableObject
• No @StateObject, @ObservedObject for new code (iOS 17+)
• ObservableObject only as fallback when supporting pre-iOS 17

See references/architecture-examples.md for full state management examples and anti-patterns.

Model Rules

1. Conform to Codable + Identifiable + Hashable (implies Equatable)
2. Use CodingKeys when API field names differ from Swift property names
3. All properties are let unless mutation is required
4. Use optionals for truly optional API fields — don't default to empty strings
5. One model per file — named {Feature}Model.swift
6. No logic in models — pure data containers
7. Every model must have a companion {Feature}ModelStub.swift
8. Components MUST accept model types — never pass decomposed primitives (String, Int, URL?) as separate parameters when a model exists
9. ModelStub is the ONLY data source for previews — no inline literals, no hardcoded values, no "example" strings anywhere in #Preview blocks

Stub Requirements

• Wrapped in #if DEBUG
• Provide static var stub: Self — single instance with realistic data
• Provide static var stubs: [Self] — array with 3+ items showing variety
• Provide named edge-case variants for preview coverage:
  • static var stubLongText: Self — maximum-length strings to test truncation
  • static var stubNilOptionals: Self — all optional fields set to nil
  • static var stubEmpty: Self — empty collections, blank strings
• Include boundary values: dates at epoch, zero counts, maximum IDs

See references/mvvm-templates.md for Model and ModelStub templates.

ViewModel Rules

1. Always use @Observable macro
2. Always annotate with @MainActor — ensures all state mutations are main-thread-safe
3. Never import SwiftUI
4. Receive repository via init (protocol-typed)
5. All data methods are async — no callbacks, no Combine
6. Use defer { isLoading = false } for loading state cleanup
7. Handle both .success and .failure from repository results
8. Expose var errorMessage: String? for error display
9. Methods are imperative verbs: fetchProducts(), deleteProduct(), submitForm()
10. Every ViewModel must have a companion {Feature}ViewModelStub.swift

ViewModel Stub Requirements

• Wrapped in #if DEBUG
• Provide static func stub(...) with default parameters for all observable state
• Include a private StubRepository class that returns model stubs
• stub() works with zero arguments using ModelStub defaults

See references/mvvm-templates.md for ViewModel and ViewModelStub templates.

View Rules

Screen vs View Pattern

View Requirements

1. Every view and component file must have #Preview blocks covering all relevant states:
   • #Preview — default / populated state
   • #Preview("Loading") — loading indicator visible
   • #Preview("Empty") — empty state messaging
   • #Preview("Error") — error state with message
   • #Preview("Edge Case") — long text, nil optionals, boundary data (use ModelStub edge variants)
   • #Preview("Dark Mode") — with .preferredColorScheme(.dark)
2. Use #Preview("StateName") labels to clearly identify each variant
3. CRITICAL — No inline data in previews. Previews MUST use ViewModelStub.stub() or ModelStub.stub exclusively. NEVER pass hardcoded strings, numbers, or literal values as preview parameters.

// ❌ NEVER — inline data in preview
#Preview {
    HomeScreen(title: "Welcome", userName: "John", itemCount: 5)
}

// ✅ ALWAYS — stub-driven preview
#Preview {
    HomeScreen(viewModel: .stub())
}

4. Components accept Model types, not primitives — a row takes ProductModel, not (title: String, price: Double). If a component needs data, pass the model struct.
5. Use .task { } for async work on appear — never onAppear with Task
6. Use .refreshable { } for pull-to-refresh
7. Keep body concise — extract subviews as computed properties or separate structs (see Component Decomposition Rules)
8. No business logic in body — all logic lives in ViewModel
9. Use AppSpacing constants — no magic numbers
10. Use AppRadius constants — no raw corner radius values
11. Use semantic system colors (.primary, .secondary) or AppTheme

See references/architecture-examples.md for Screen, View, and Component examples. See references/mvvm-templates.md for scaffolding templates.

Component Decomposition Rules

CRITICAL — Decompose During Initial Generation

DO NOT write a monolithic Screen. When creating a new feature, plan and create separate component files UPFRONT — not as a later refactoring step.

• A Screen's body should be ≤50 lines — it orchestrates components, not renders UI directly
• Every distinct UI section (header, card, row, list, banner, stat block) MUST be its own struct in a separate file under View/
• Each extracted component MUST have its own #Preview with ModelStub.stub data

// ❌ NEVER — everything in one Screen file
struct HomeScreen: View {
    var body: some View {
        ScrollView {
            // 200+ lines of header, cards, lists, banners...
        }
    }
}

// ✅ ALWAYS — Screen orchestrates, components render
struct HomeScreen: View {
    @State private var viewModel: HomeViewModel

    var body: some View {
        ScrollView {
            HomeHeaderView(user: viewModel.user)
            HomeFeaturedCard(item: viewModel.featuredItem)
            HomeRecentList(items: viewModel.recentItems)
        }
        .task { await viewModel.fetch() }
    }
}
// Each component lives in its own file with its own #Preview

When to Extract a Component

Extract a piece of UI into its own file when any of these triggers apply:

Placement Rules

Requirements

1. One component per file — named {Feature}{Component}.swift (feature) or App{Component}.swift (shared)
2. Every component file must have its own #Preview with stub data — no exceptions
3. Components accept model structs — never raw primitives as parameters. Pass ProductModel not (title: String, price: Double, imageURL: URL?)
4. NEVER use inline literals in component previews — always ModelStub.stub or ModelStub.stubs. If a stub doesn't exist, create {Feature}ModelStub.swift FIRST before writing the preview
5. Before writing ANY #Preview block, verify the corresponding {Feature}ModelStub.swift exists. If it doesn't — stop and create it
6. No nested Components/ subfolder inside feature View/ directories — keep flat
7. Inline private structs are allowed only if <20 lines with zero @State — otherwise extract to own file

// ❌ NEVER — component with loose parameters
struct HomeItemRow: View {
    let title: String
    let subtitle: String
    let imageURL: URL?
}

// ✅ ALWAYS — component accepts model
struct HomeItemRow: View {
    let item: HomeItemModel
}

// ❌ NEVER — inline preview data
#Preview {
    HomeItemRow(title: "Hello", subtitle: "World", imageURL: nil)
}

// ✅ ALWAYS — stub data
#Preview {
    HomeItemRow(item: .stub)
}

Migration Note

Existing features with nested Components/ subfolders should be flattened to View/ during refactoring.

See references/architecture-examples.md for Component examples.

Repository Rules

1. Always define a protocol (abstract interface)
2. Always create a separate Impl class (concrete)
3. Return Result<T, AppError> — never throw from public methods
4. Repository is stateless — no held state
5. Takes NetworkService via init (protocol-typed)
6. ViewModel depends on the protocol — enables mock injection

See references/architecture-examples.md for Repository protocol + implementation examples.

NetworkService Rules

1. Protocol-defined — enables mock injection
2. Returns Result<T, AppError> — never throws from public interface
3. Token injection via SessionService automatically
4. 401 responses auto-clear session
5. Endpoint enum is single source of truth for API paths
6. JSON decoding uses .iso8601 date strategy

See references/routing-and-networking.md for full NetworkService, Endpoint, and HTTPMethod implementations.

Extension Rules

1. Naming: TypePurpose.swift in Core/Extensions/ — no + in filename
2. Stubs: {Feature}ModelStub.swift in feature Model/ folder
3. Extensions must be pure — no stored state, no side effects
4. Group related extensions in one file
5. Prefer extensions over global functions

See references/architecture-examples.md for ViewModifiers, DateFormatting, StringValidation examples.

Error Handling Rules

1. All repositories return Result<T, AppError> — never throw
2. ViewModels switch on Result and surface errorMessage
3. Views display errors via .alert or ErrorView component
4. No silent failures — every error shows to user or is logged
5. Network errors are human-readable — never raw error strings
6. Use defer { isLoading = false } to guarantee cleanup

See references/architecture-examples.md for AppError + NetworkErrorReason implementations.

Navigation Rules

1. All routes defined in Route enum — no string-based navigation
2. Use NavigationStack with NavigationPath — not NavigationView
3. AppRouter injected via .environment()
4. Associated values for route parameters
5. Sheets and full-screen covers managed through AppRouter
6. Deep links convert URLs to Route enum values

See references/routing-and-networking.md for Route, AppRouter, MainTabView, and DeepLinkHandler.

App Root Structure

Flow: Splash → Auth Check → Main App (TabView) or Login

1. SplashScreen is the first view — handles auth gate
2. Each tab has its own NavigationStack
3. Splash performs startup: token validation, cache warm-up, version check
4. AppState.isAuthenticated drives root-level conditional rendering
5. Use withAnimation for smooth splash → main transition

See references/architecture-examples.md for SplashScreen template.

Environment Configuration Rules

1. Use #if DEBUG for compile-time environment switching
2. For staging: Xcode scheme + custom build flags (-D STAGING)
3. AppConfig.baseURL is the single source for API host
4. No secrets in source code — use .xcconfig files
5. Feature flags as static properties in AppConfig

See references/architecture-examples.md for AppConfig implementation.

DI & Environment Rules

1. DependencyContainer is @Observable — injected at App root via .environment()
2. All services are protocol-typed
3. Repositories are lazy var — created on first access
4. Views access container via @Environment(DependencyContainer.self)
5. For previews, mock repos live in ViewModelStub — no need to mock container
6. AppState holds auth status and shared user data
7. AppRouter holds navigation state

See references/architecture-examples.md for DependencyContainer, AppState, and App entry point.

Persistence Rules

1. All storage access wrapped behind protocols
2. Keys in private enum — no scattered string literals
3. NEVER store tokens in UserDefaults — it is plaintext on disk. Use Keychain for all sensitive data (access tokens, refresh tokens, credentials)
4. Non-sensitive preferences (flags, theme, last-viewed IDs) use UserDefaults wrapped in SessionService
5. clearSession() removes all auth data atomically
6. For structured local data (offline cache, drafts), use SwiftData with @Model — see SwiftData rules below

See references/architecture-examples.md for SessionService protocol + implementation.

Theming Rules

1. Never hard-coded spacing — always AppSpacing.md, AppSpacing.lg, etc.
2. Never hard-coded colors — system colors (.primary, .secondary) or AppTheme
3. Never hard-coded corner radii — always AppRadius.sm, AppRadius.md, AppRadius.lg, etc.
4. Color assets must define light, dark, and tinted variants in the asset catalog
5. Contrast ratios documented as comments next to every color definition in AppTheme
6. Typography must use scalable system fonts (.body, .headline) or .custom(..., relativeTo:) — no fixed size: values
7. Prefer system semantic colors for accessibility and dark mode
8. All design tokens are value types — CGFloat constants in AppSpacing, AppRadius, AppTheme

AppRadius Constants

// Core/Theme/AppRadius.swift
import SwiftUI

enum AppRadius {
    static let xs: CGFloat = 4
    static let sm: CGFloat = 8
    static let md: CGFloat = 12
    static let lg: CGFloat = 16
    static let xl: CGFloat = 24
    static let full: CGFloat = .infinity  // Capsule
}

// Usage
.clipShape(RoundedRectangle(cornerRadius: AppRadius.md))
.background(Color.appSurface, in: RoundedRectangle(cornerRadius: AppRadius.lg))

See references/architecture-examples.md for AppSpacing, AppRadius, and AppTheme.

Accessibility Rules — WCAG AA

WCAG AA is the enforced baseline. AAA (7:1 contrast) is aspirational.

Mandatory Requirements

Testing Requirements

• Test with VoiceOver enabled — verify reading order and labels
• Test at AX5 (largest Dynamic Type) — no truncation of critical content
• Test with Reduce Motion — disable spring animations, use crossfade
• Test with Increase Contrast — verify all elements remain visible
• Test with Bold Text — verify layout doesn't break

Anti-Patterns

// ❌ No label — VoiceOver reads "button"
Button(action: delete) {
    Image(systemName: "trash")
}

// ✅ Accessible
Button(action: delete) {
    Image(systemName: "trash")
}
.accessibilityLabel("Delete item")
.accessibilityHint("Removes this item permanently")

// ❌ Colour-only status
Circle().fill(isActive ? .green : .red)

// ✅ Colour + icon
HStack {
    Image(systemName: isActive ? "checkmark.circle.fill" : "xmark.circle.fill")
    Text(isActive ? "Active" : "Inactive")
}
.foregroundStyle(isActive ? .green : .red)

// ❌ Fixed font size
Text("Title").font(.system(size: 24))

// ✅ Scalable
Text("Title").font(.title)

Localisation Rules

String Handling

1. All user-facing strings must use LocalizedStringKey constants — never hardcode strings in views
2. Shared strings live in Core/Constants/AppStrings.swift
3. Feature-specific strings live in Features/{Feature}/Strings{Feature}.swift
4. Every key must exist in Localizable.xcstrings with English as the default language
5. Adding a new string = adding the key constant + English value to the catalog in the same commit
6. Use String(localized:) for non-view contexts (ViewModels, services)
7. Never concatenate localized strings — use interpolation: "Hello, \(name)" inside LocalizedStringKey
8. Plurals and grammar rules use String Catalog plural variants

Pattern

// Core/Constants/AppStrings.swift
import SwiftUI

enum AppStrings {
    enum General {
        static let ok: LocalizedStringKey = "general_ok"
        static let cancel: LocalizedStringKey = "general_cancel"
        static let error: LocalizedStringKey = "general_error"
        static let retry: LocalizedStringKey = "general_retry"
    }
    
    enum Product {
        static let title: LocalizedStringKey = "product_title"
        static let emptyState: LocalizedStringKey = "product_empty_state"
        static func itemCount(_ count: Int) -> LocalizedStringKey {
            "product_item_count \(count)"
        }
    }
}

// Usage in View
Text(AppStrings.Product.title)
Button(AppStrings.General.retry) { await viewModel.fetch() }

// Usage in ViewModel (non-view context)
errorMessage = String(localized: "network_error_no_connection")

Anti-Patterns

// ❌ Hardcoded string in view
Text("No products found")

// ❌ Concatenation
Text("Hello, " + username + "!")

// ❌ Key without catalog entry
Text("some_key_that_doesnt_exist_in_xcstrings")

// ✅ Correct
Text(AppStrings.Product.emptyState)

Liquid Glass & iOS 26 Design Rules

Liquid Glass is the primary design material in iOS 26. It forms a distinct functional layer for controls and navigation elements that floats above content.

Core Principles

1. Use standard components — NavigationStack, TabView, toolbars, sheets, popovers auto-adopt Liquid Glass
2. Don't apply Liquid Glass in the content layer — it's for navigation/controls only, not content views
3. Use sparingly on custom views — limit .glassEffect() to the most important functional elements
4. Remove custom bar backgrounds — let the system handle toolbar, tab bar, and navigation bar appearance
5. Don't layer Liquid Glass on Liquid Glass — avoid overcrowding or stacking glass elements
6. Use .scrollEdgeEffectStyle() for content beneath bars — maintains legibility automatically
7. Prefer system button styles — use .buttonStyle(.glass) or .buttonStyle(.glassProminent) instead of custom glass
8. Test with accessibility settings — reduced transparency, increased contrast, preferred Liquid Glass look

Liquid Glass Variants

SwiftUI APIs

// Basic glass effect on custom control
Text("Label")
    .padding()
    .glassEffect(in: .capsule)

// Rounded rectangle shape
Text("Label")
    .padding()
    .glassEffect(in: .rect(cornerRadius: 16))

// Tinted + interactive (reacts to touch)
Image(systemName: "play.fill")
    .padding()
    .glassEffect(.regular.tint(.blue).interactive())

// Button styles
Button("Action") { }
    .buttonStyle(.glass)

Button("Primary") { }
    .buttonStyle(.glassProminent)

// Container for multiple glass elements (performance + morphing)
GlassEffectContainer(spacing: 20) {
    HStack(spacing: 20) {
        ForEach(items) { item in
            ItemView(item: item)
                .glassEffect()
                .glassEffectID(item.id, in: namespace)
        }
    }
}

// Tab bar minimization on scroll
TabView { /* ... */ }
    .tabBarMinimizeBehavior(.onScrollDown)

// Scroll edge effect for custom bars
CustomBar()
    .safeAreaBar(edge: .bottom) { content }

Layout & Controls Changes (iOS 26)

1. Lists/forms have larger row height and padding — don't fight system metrics
2. Section corners are more rounded — concentric with hardware
3. Section headers use title-style capitalization — not all caps
4. Controls (sliders, toggles) adopt glass on interaction — no custom glass needed
5. Action sheets originate from source element — always specify source view/item
6. Sheets have increased corner radius and are inset from display edge
7. Use ConcentricRectangle / .rect(corners:isUniform:) for shapes matching hardware curvature

What NOT to Do

// ❌ Applying glass to content layer
List { ... }
    .glassEffect() // WRONG — glass is for controls/nav, not content

// ❌ Custom toolbar backgrounds that override system
.toolbar { ... }
.toolbarBackground(.visible, for: .navigationBar)
.toolbarBackground(Color.blue, for: .navigationBar)  // Remove this

// ❌ Stacking glass on glass
VStack {
    Text("Item").glassEffect()
    Text("Another").glassEffect()  // Too many — use GlassEffectContainer or reduce
}

// ✅ Let system handle it — standard components get glass automatically
NavigationStack { ... }  // Tab bars, toolbars get glass free

See references/architecture-examples.md for full Liquid Glass code patterns.

Assets & Fonts Rules

1. SF Symbols are the primary icon system — use Image(systemName:) first
2. Custom assets go in Assets.xcassets with proper organization (image sets, color sets)
3. Support light/dark/tinted variants for all color assets
4. Custom fonts registered in Info.plist — access via type-safe Font extension
5. Prefer system Dynamic Type styles (.headline, .body) — custom fonts only when brand requires
6. All custom images must include @2x and @3x variants
7. Use Symbol Effects for animated SF Symbols (.symbolEffect(.bounce), .symbolEffect(.pulse))
8. App icons must provide layered assets for Liquid Glass icon effects (foreground, middle, background layers)

Font Extension Pattern

// Core/Extensions/AppFonts.swift
import SwiftUI

extension Font {
    static func appFont(_ style: AppFontStyle, size: CGFloat) -> Font {
        .custom(style.rawValue, size: size, relativeTo: style.textStyle)
    }
}

enum AppFontStyle: String {
    case regular = "BrandFont-Regular"
    case medium = "BrandFont-Medium"
    case bold = "BrandFont-Bold"
    
    var textStyle: Font.TextStyle {
        switch self {
        case .regular: return .body
        case .medium: return .headline
        case .bold: return .title
        }
    }
}

See references/architecture-examples.md for asset organization and SF Symbol patterns.

Testing Rules

1. Use Swift Testing (@Test, #expect, #require, @Suite) — not XCTest
2. Mock via protocol conformance — no third-party frameworks
3. Reuse Model.stub / .stubs — same data as previews
4. Test success and failure paths for every async method
5. ViewModel tests are highest priority
6. Use configurable stub repositories
7. Use #require for unwrapping optionals — fails test immediately if nil
8. @Suite runs tests in parallel by default — keep tests independent

See references/architecture-examples.md for full test suite example. See references/mvvm-templates.md for test suite template.

Concurrency & Sendable Rules

Swift 6 strict concurrency is the target. Prepare all new code for full compliance.

1. ViewModels — @MainActor @Observable handles thread safety automatically
2. Models — Codable + Hashable structs with let properties are implicitly Sendable
3. Repositories — mark final class implementations as Sendable when they hold no mutable state (only let dependencies)
4. NetworkService — mark protocol methods as sending where applicable; implementation is Sendable (stateless URLSession wrapper)
5. Never use @unchecked Sendable unless wrapping a proven-safe third-party type — document why
6. Closures crossing actor boundaries must be @Sendable — captured values must be Sendable
7. Enable -strict-concurrency=complete in build settings for new projects

Common Patterns

// ✅ Repository is Sendable — all dependencies are let + Sendable
final class ProductRepositoryImpl: ProductRepository, Sendable {
    private let networkService: NetworkService  // protocol is Sendable
    
    init(networkService: NetworkService) {
        self.networkService = networkService
    }
}

// ✅ Model structs with let properties are implicitly Sendable
struct ProductModel: Codable, Identifiable, Hashable, Sendable {
    let id: String
    let name: String
}

// ❌ WRONG — mutable state makes this non-Sendable
class BadRepository {
    var cachedItems: [ProductModel] = []  // Not safe across actors
}

Import Organization Rules

Imports are organized in groups, separated by a blank line, alphabetically within each group:

// 1. Foundation / system frameworks
import Foundation
import SwiftUI      // Only in Views — never in ViewModels

// 2. Third-party packages (if any)
import Kingfisher

// 3. Project modules (for multi-module projects)
import NetworkKit
import SharedModels

Rules

1. ViewModels import only Foundation (and domain module if multi-module)
2. Views import SwiftUI — which re-exports Foundation
3. Repositories import only Foundation
4. Never import UIKit unless wrapping a UIKit component in UIViewRepresentable
5. Remove unused imports — Xcode warns about these
6. No @testable import outside of test targets

Task Cancellation Rules

1. Prefer .task { } modifier — SwiftUI automatically cancels when view disappears
2. Manual Task {} blocks in event handlers are NOT auto-cancelled — store and cancel explicitly if needed
3. Check cancellation in long loops: try Task.checkCancellation() or guard !Task.isCancelled
4. Never ignore cancellation — let CancellationError propagate or handle gracefully

Patterns

// ✅ .task handles cancellation automatically — preferred
struct ProductScreen: View {
    var body: some View {
        ProductListView(viewModel: viewModel)
            .task { await viewModel.fetchProducts() }       // Cancelled on disappear
            .task(id: searchQuery) { await viewModel.search(searchQuery) }  // Re-runs + cancels previous
    }
}

// ✅ Manual cancellation for user-triggered Tasks
@Observable @MainActor
class SearchViewModel {
    private var searchTask: Task<Void, Never>?
    
    func search(_ query: String) {
        searchTask?.cancel()  // Cancel previous search
        searchTask = Task {
            try? await Task.sleep(for: .milliseconds(300))  // Debounce
            guard !Task.isCancelled else { return }
            await performSearch(query)
        }
    }
}

// ❌ WRONG — Task leaks, never cancelled
Button("Load") {
    Task { await viewModel.fetchProducts() }  // OK for one-shot actions
    // But DON'T do this for repeating/cancellable work
}

ViewModel Cancellation

• One-shot actions (fetch, delete, submit) — no manual cancellation needed; .task or short-lived
• Ongoing/repeating work (search-as-you-type, polling) — store Task reference + cancel on new input
• Long operations (file upload, multi-page sync) — check Task.isCancelled between steps

Pagination Pattern

For paginated / infinite scroll lists:

State

@Observable @MainActor
class ProductViewModel {
    var products: [ProductModel] = []
    var isLoading = false
    var isLoadingMore = false
    var hasMore = true
    var errorMessage: String?
    
    private var currentPage = 1
    private let pageSize = 20
    private let repository: ProductRepository
    
    init(repository: ProductRepository) {
        self.repository = repository
    }
    
    func fetchProducts() async {
        isLoading = true
        defer { isLoading = false }
        currentPage = 1
        
        let result = await repository.getProducts(page: 1, size: pageSize)
        switch result {
        case .success(let data):
            products = data
            hasMore = data.count >= pageSize
            errorMessage = nil
        case .failure(let error):
            errorMessage = error.userMessage
        }
    }
    
    func loadMore() async {
        guard hasMore, !isLoadingMore else { return }
        isLoadingMore = true
        defer { isLoadingMore = false }
        
        let nextPage = currentPage + 1
        let result = await repository.getProducts(page: nextPage, size: pageSize)
        switch result {
        case .success(let data):
            products.append(contentsOf: data)
            currentPage = nextPage
            hasMore = data.count >= pageSize
        case .failure(let error):
            errorMessage = error.userMessage
        }
    }
}

View Trigger

List(viewModel.products) { product in
    ProductRow(product: product)
        .onAppear {
            if product.id == viewModel.products.last?.id {
                Task { await viewModel.loadMore() }
            }
        }
}

Form Handling Pattern

Rules

1. One ViewModel per form — holds field values + validation state
2. Validate on submit by default. Real-time validation only for critical fields (email format, password strength)
3. FocusState lives in the View — not the ViewModel
4. ViewModel exposes isFormValid: Bool computed property for submit button state

Form ViewModel

@Observable @MainActor
class CreateProductViewModel {
    // Field values
    var name = ""
    var description = ""
    var price = ""
    
    // Validation errors
    var nameError: String?
    var priceError: String?
    
    // Submit state
    var isSubmitting = false
    var errorMessage: String?
    var didSubmitSuccessfully = false
    
    var isFormValid: Bool {
        name.trimmed.isNotEmpty && Double(price) != nil
    }
    
    private let repository: ProductRepository
    
    init(repository: ProductRepository) {
        self.repository = repository
    }
    
    func submit() async {
        // Validate
        nameError = name.trimmed.isEmpty ? "Name is required" : nil
        priceError = Double(price) == nil ? "Enter a valid price" : nil
        guard nameError == nil, priceError == nil else { return }
        
        // Submit
        isSubmitting = true
        defer { isSubmitting = false }
        
        let product = ProductModel(
            id: UUID().uuidString,
            name: name.trimmed,
            description: description.trimmed,
            price: Double(price) ?? 0,
            imageURL: nil,
            category: "General",
            isAvailable: true,
            createdAt: .now
        )
        
        let result = await repository.createProduct(product)
        switch result {
        case .success:
            didSubmitSuccessfully = true
        case .failure(let error):
            errorMessage = error.userMessage
        }
    }
}

Form View

struct CreateProductScreen: View {
    @State private var viewModel: CreateProductViewModel
    @FocusState private var focusedField: Field?
    @Environment(\.dismiss) private var dismiss
    
    enum Field { case name, description, price }
    
    init(viewModel: CreateProductViewModel) {
        _viewModel = State(initialValue: viewModel)
    }
    
    var body: some View {
        Form {
            Section("Details") {
                TextField("Product Name", text: $viewModel.name)
                    .focused($focusedField, equals: .name)
                if let error = viewModel.nameError {
                    Text(error).font(.caption).foregroundStyle(.red)
                }
                
                TextField("Description", text: $viewModel.description, axis: .vertical)
                    .focused($focusedField, equals: .description)
                    .lineLimit(3...6)
                
                TextField("Price", text: $viewModel.price)
                    .focused($focusedField, equals: .price)
                    .keyboardType(.decimalPad)
                if let error = viewModel.priceError {
                    Text(error).font(.caption).foregroundStyle(.red)
                }
            }
            
            Section {
                AppButton("Create Product", isLoading: viewModel.isSubmitting) {
                    focusedField = nil
                    Task { await viewModel.submit() }
                }
                .disabled(!viewModel.isFormValid)
            }
        }
        .navigationTitle("New Product")
        .onChange(of: viewModel.didSubmitSuccessfully) { _, success in
            if success { dismiss() }
        }
    }
}

Performance Guidelines

View Performance

1. Use LazyVStack / LazyHStack for any list with 10+ items — never VStack with ForEach for large collections
2. Extract subviews — SwiftUI diffs per-view; smaller views = fewer recomputations
3. Use @Observable granularly — properties track individually; only views reading changed properties re-render
4. **Mark child views `Equa

…(truncated)