Apple Development Best Practices

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

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