Apple Development Best Practices

Modern Apple platform development using Swift 6 and SwiftUI as primary frameworks.

When to Use

Use this skill when:

• Building iOS or macOS apps with Swift 6 and SwiftUI
• Designing navigation, state management, or concurrency patterns for Apple platforms
• Working with SwiftData, Core Data, StoreKit, CloudKit, or other Apple frameworks
• Reviewing Swift code or planning Apple platform architecture

When NOT to Use

Do NOT use this skill when:

• Building cross-platform mobile apps (Flutter, React Native, Kotlin Multiplatform) — use a cross-platform mobile persona instead, because Apple-specific patterns like @Observable and NavigationStack don't apply
• Writing server-side Swift (Vapor, Hummingbird) — use a backend engineering persona instead, because server-side Swift has different concurrency, deployment, and architecture concerns

Core Philosophy

Build apps that are previewable, testable, and maintainable. A previewable app is a testable app. A testable app is a maintainable app.

Swift 6 Standards

• Strict concurrency enabled — treat all warnings as errors
• @Observable over ObservableObject (iOS 17+)
• async/await for all asynchronous operations
• Value types (structs) preferred over reference types (classes) unless identity semantics needed
• guard for early exits, never deeply nested if let chains
• Typed errors via LocalizedError conformance — no raw strings
• No force unwrapping (!) without documented justification
• Follow Apple's Swift API Design Guidelines for naming

SwiftUI Architecture

State Management — Single Source of Truth (SSOT)

// Local view state → @State
@State private var isExpanded = false

// Observable model → @State with @Observable class
@State private var viewModel = RecipeViewModel()

// Shared across view tree → @Environment
@Environment(\.recipeStore) private var store

// Bindings to @Observable → @Bindable
@Bindable var viewModel: RecipeViewModel

Rules:

• @State for view-local state only — never shared across views
• @Observable classes for ViewModels (replaces ObservableObject + @Published)
• @Environment for dependency injection (services, stores, settings)
• Never pass view models more than 2 levels deep — use Environment instead

Navigation — NavigationStack with Type-Safe Routing

enum Route: Hashable {
    case recipeDetail(Recipe)
    case settings
    case profile(User)
}

@Observable
final class Router {
    var path = NavigationPath()

    func navigate(to route: Route) {
        path.append(route)
    }
}

Rules:

• NavigationStack only — never deprecated NavigationView
• Type-safe routing via Hashable enum
• Router as @Observable class in @Environment
• Sheet presentation via optional ViewModel on parent

View Composition

• Extract subviews at 50+ lines or when reusable
• Max 100 lines per view file before mandatory extraction
• Custom ViewModifiers for shared styling — not repeated inline styles
• Never use AnyView — destroys diffing performance and identity
• Prefer @ViewBuilder closures over AnyView for type erasure

Performance

• LazyVStack/LazyHStack inside ScrollView — never eager stacks for large lists
• EquatableView wrapper for complex views that rarely change
• Keep view body pure — no side effects, no network calls
• Use .task modifier for async work, not onAppear with Task
• Profile with SwiftUI Performance Instrument (Xcode 16+)

Project Structure

AppName/
├── App/                    # App entry, lifecycle, configuration
│   ├── AppNameApp.swift
│   └── AppDelegate.swift   # Only if needed for UIKit integration
├── Features/               # Feature modules (self-contained)
│   ├── Recipes/
│   │   ├── Views/          # SwiftUI views
│   │   ├── ViewModels/     # @Observable classes
│   │   └── Models/         # Data models (structs)
│   ├── MealPlanning/
│   └── Community/
├── Core/                   # Shared infrastructure
│   ├── Extensions/
│   ├── Services/           # Networking, auth, analytics
│   ├── Persistence/        # SwiftData / Core Data
│   └── Components/         # Reusable UI components
├── Resources/              # Assets, Localizations, Fonts
└── Tests/
    ├── UnitTests/          # ViewModel + Service tests
    └── UITests/            # Critical user flow tests

Rules:

• Features are self-contained — no cross-feature imports
• Shared code lives in Core/ only
• Each feature has its own Views, ViewModels, Models
• Feature folders mirror navigation structure

Concurrency

// Actor for thread-safe shared state
actor RecipeStore {
    private var cache: [UUID: Recipe] = [:]

    func recipe(for id: UUID) -> Recipe? {
        cache[id]
    }
}

// @MainActor for UI-bound classes
@MainActor
@Observable
final class RecipeListViewModel {
    var recipes: [Recipe] = []
    var isLoading = false

    func loadRecipes() async {
        isLoading = true
        defer { isLoading = false }
        recipes = await recipeService.fetchAll()
    }
}

Rules:

• @MainActor on all ViewModels
• actor for shared mutable state
• Sendable conformance for types crossing isolation boundaries
• Never DispatchQueue.main.async — use @MainActor instead
• Task only inside .task modifier or explicit user-initiated actions
• TaskGroup for parallel independent work

Testing

• Swift Testing (@Test, #expect) preferred over XCTest for new code
• Unit tests for all ViewModel logic — 80%+ coverage on business logic
• UI tests for critical user flows only (login, purchase, core CRUD)
• Dependency injection via protocols for testability
• No singletons in production code — inject via @Environment
• Preview-driven development: if a view is hard to preview, it's hard to test

Persistence

SwiftData (iOS 17+) is the default persistence layer:

@Model
final class Recipe {
    var name: String
    var ingredients: [String]
    var instructions: String
    @Relationship(deleteRule: .cascade)
    var steps: [CookingStep]
}

Rules:

• @Model classes for SwiftData — not structs
• Define @Relationship explicitly with delete rules
• Use @Query in views for automatic updates
• ModelContainer configured in App entry point
• Migration strategy documented before schema changes

Networking

protocol RecipeServiceProtocol: Sendable {
    func fetchAll() async throws -> [Recipe]
    func create(_ recipe: Recipe) async throws -> Recipe
}

struct RecipeService: RecipeServiceProtocol {
    private let session: URLSession
    private let decoder: JSONDecoder

    func fetchAll() async throws -> [Recipe] {
        let (data, response) = try await session.data(from: endpoint)
        guard let http = response as? HTTPURLResponse,
              (200...299).contains(http.statusCode) else {
            throw AppError.networkError(statusCode: http.statusCode)
        }
        return try decoder.decode([Recipe].self, from: data)
    }
}

Rules:

• Protocol-based services for testability
• Sendable conformance on all service types
• Typed errors with LocalizedError
• No third-party HTTP libraries unless justified (URLSession is sufficient)
• Certificate pinning for sensitive data

Security

• Keychain for credentials, tokens, secrets — never UserDefaults
• App Transport Security enabled — HTTPS only
• No sensitive data in logs or crash reports
• @AppStorage only for non-sensitive user preferences
• Input validation on all user-provided data
• Privacy manifest (PrivacyInfo.xcprivacy) for App Store compliance

Accessibility

• Every interactive element needs an accessibilityLabel
• Use semantic SwiftUI elements (Button, Toggle, Picker) — not .onTapGesture
• Support Dynamic Type — no hardcoded font sizes
• Minimum tap target 44x44pt
• Test with VoiceOver before shipping

Deep References

See references/ for detailed guidance:

• references/swiftui-patterns.md — Advanced view patterns, custom layouts, animations
• references/concurrency-guide.md — Actor isolation, Sendable, structured concurrency
• references/xcode-claude-integration.md — XcodeBuildMCP setup, hooks, sandbox modes
• references/migration-guide.md — UIKit → SwiftUI, CoreData → SwiftData paths