frostist/swift-human-guidelines

Swift and SwiftUI Development Guidelines

Overview

Build production-ready Swift and SwiftUI applications for all Apple platforms following Apple's Human Interface Guidelines, modern Swift best practices, and performance optimization techniques. This skill provides comprehensive guidance for creating new apps, architecting cross-platform solutions, and implementing efficient, maintainable code.

When to Use This Skill

Use this skill when:

• Building new iOS, iPadOS, macOS, watchOS, or tvOS apps from scratch
• Implementing SwiftUI views and navigation patterns
• Optimizing app performance and memory usage
• Following Apple Human Interface Guidelines
• Creating cross-platform Swift applications
• Implementing modern Swift concurrency with async/await
• Architecting MVVM or other SwiftUI-appropriate patterns
• Setting up proper state management
• Implementing accessibility features

Quick Start: Building a New App

1. Choose Your Platform(s)

Single Platform:

• iOS: Mobile-first, touch-based, portrait/landscape
• macOS: Desktop, pointer-based, window management
• watchOS: Glanceable, quick interactions
• tvOS: Cinematic, focus-based navigation

Multi-Platform:

• iOS + iPadOS: Adaptive layouts with size classes
• iOS + macOS: Shared business logic, platform-specific UI
• Universal: All platforms with maximum code sharing

2. Use App Templates

Start with production-ready templates in assets/:

• ios-app-template.swift: Modern iOS app with TabView navigation, MVVM architecture, async/await
• macos-app-template.swift: macOS app with NavigationSplitView, Settings, window management

Templates include:

• Proper app structure with @main entry point
• MVVM architecture with ObservableObject ViewModels
• Repository pattern for data access
• Async/await for network operations
• Navigation patterns (TabView for iOS, NavigationSplitView for macOS)
• Reusable components and proper state management

3. Project Structure

Organize code for maintainability and cross-platform sharing:

MyApp/
├── Shared/                    # 100% shared code
│   ├── Models/               # Data structures
│   ├── ViewModels/           # Business logic
│   ├── Services/             # Networking, persistence
│   └── Views/Shared/         # Reusable components
├── iOS/                      # iOS-specific
│   ├── Views/
│   └── iOSApp.swift
├── macOS/                    # macOS-specific
│   ├── Views/
│   └── macOSApp.swift
└── Tests/

4. Follow Core Principles

Architecture:

• MVVM pattern: Models, Views, ViewModels
• Unidirectional data flow: State down, events up
• Dependency injection for testability
• Repository pattern for data access

State Management:

• @State: Local view state
• @StateObject: View owns the lifecycle
• @ObservedObject: View observes external object
• @EnvironmentObject: Shared across hierarchy
• @Binding: Two-way connection

Performance:

• Use lazy stacks for large lists
• Provide stable identifiers for ForEach
• Minimize view body recalculations
• Use async/await for all async operations
• Profile with Instruments regularly

Core Development Workflows

Building a New View

1. Define the model (if needed)
2. Create the ViewModel with business logic
3. Build the View using SwiftUI components
4. Extract reusable components for complex views
5. Add navigation if needed
6. Test the ViewModel with unit tests

Example:

// 1. Model
struct Article: Identifiable, Codable {
    let id: UUID
    let title: String
    let content: String
}

// 2. ViewModel
@MainActor
class ArticleListViewModel: ObservableObject {
    @Published var articles: [Article] = []
    @Published var isLoading = false
    
    func loadArticles() async {
        isLoading = true
        defer { isLoading = false }
        articles = await fetchArticles()
    }
}

// 3. View
struct ArticleListView: View {
    @StateObject private var viewModel = ArticleListViewModel()
    
    var body: some View {
        List(viewModel.articles) { article in
            ArticleRow(article: article)
        }
        .task {
            await viewModel.loadArticles()
        }
    }
}

Implementing Navigation

iOS: NavigationStack

NavigationStack(path: $path) {
    List(items) { item in
        NavigationLink(value: item) {
            ItemRow(item: item)
        }
    }
    .navigationDestination(for: Item.self) { item in
        ItemDetailView(item: item)
    }
}

macOS: NavigationSplitView

NavigationSplitView {
    List(items, selection: $selectedItem) { item in
        ItemRow(item: item)
    }
} detail: {
    if let item = selectedItem {
        ItemDetailView(item: item)
    }
}

Performance Optimization

Key strategies:

1. Use LazyVStack/LazyHStack for large lists
2. Provide stable IDs with Identifiable
3. Extract subviews to minimize recalculations
4. Use @Published selectively
5. Cache expensive computations
6. Profile with Instruments

See references/performance-optimization.md for detailed patterns and examples.

Cross-Platform Development

Maximize code sharing:

• 100% shared: Models, business logic, networking
• 95% shared: ViewModels, repositories
• 70% shared: Reusable view components
• Platform-specific: Navigation, window management, input

Use conditional compilation:

#if os(iOS)
// iOS-specific code
#elseif os(macOS)
// macOS-specific code
#endif

See references/cross-platform-development.md for comprehensive patterns.

Build and Testing

Build Command

Use the standard Xcode build command with analysis:

xcodebuild -project MyApp.xcodeproj -scheme MyApp -configuration Debug clean build analyze

Testing Strategy

Unit Tests: Test ViewModels and business logic

@MainActor
class ViewModelTests: XCTestCase {
    func testLoadData() async throws {
        let viewModel = ViewModel(repository: MockRepository())
        await viewModel.loadData()
        XCTAssertFalse(viewModel.items.isEmpty)
    }
}

UI Tests: Test user flows with SwiftUI previews

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
            .previewDisplayName("Light Mode")
        ContentView()
            .preferredColorScheme(.dark)
            .previewDisplayName("Dark Mode")
    }
}

Reference Documentation

This skill includes comprehensive reference documentation:

references/human-interface-guidelines.md

Complete Apple HIG coverage:

• Core principles (Clarity, Deference, Depth)
• Liquid Glass design system (iOS 26+)
• Platform-specific guidelines (iOS, macOS, watchOS, tvOS, visionOS)
• Typography and Dynamic Type
• Color and Dark Mode
• Accessibility (VoiceOver, Dynamic Type, Reduce Motion)
• App architecture and settings patterns
• System integration features

When to read: Designing UI, ensuring HIG compliance, implementing Liquid Glass materials, choosing navigation patterns

references/swiftui-best-practices.md

Modern SwiftUI patterns:

• MVVM architecture with examples
• State management patterns
• View composition and extraction
• Navigation patterns for all platforms
• Data flow and dependency injection
• Custom modifiers and styling
• Testing strategies
• Common patterns (loading states, search, pull-to-refresh)
• iOS 18: SwiftUI/UIKit animation interoperability
• iOS 18: Zoom transitions and unified gestures
• iOS 26: UIKit/SwiftUI scene mixing
• iOS 18: DocumentGroupLaunchScene

When to read: Architecting new features, implementing state management, using iOS 18/26 APIs, creating reusable components

references/performance-optimization.md

Performance techniques:

• View performance optimization
• State management efficiency
• List and collection performance
• Memory management
• Async operations best practices
• Build performance tips
• Profiling with Instruments

When to read: Optimizing slow views, reducing memory usage, improving list scrolling, debugging performance issues

references/swift-language-features.md

Modern Swift features:

• Property wrappers and result builders
• Async/await and structured concurrency
• Actors and MainActor
• Error handling patterns
• Optionals and collections
• Protocols and generics
• Memory management (ARC, weak/unowned)
• Swift 6: Data-race safety and Sendable protocol
• Swift 6: Typed throws
• Swift 6.2: Single-threaded by default (implicit @MainActor)
• Swift 6.2: Observable async sequences
• Swift 6: Embedded Swift subset
• Swift 6: 128-bit integer support

When to read: Using Swift 6 features, implementing concurrency, ensuring data-race safety, migrating to Swift 6

references/foundation-models-api.md

Apple Intelligence integration (iOS 26+):

• Foundation Models framework overview
• Text summarization APIs
• Text extraction and entity recognition
• Content classification
• On-device processing
• Performance optimization
• Privacy considerations

When to read: Implementing Apple Intelligence features, adding summarization, extracting information from text

references/background-processing-ios26.md

Advanced background execution (iOS 26+):

• BGContinuedProcessingTask API
• Background GPU access
• Task continuation patterns
• System limits and best practices
• Handling expiration
• Resource management

When to read: Implementing background processing, finishing user-initiated tasks, using GPU in background

references/call-translation-api.md

Real-time translation (iOS 26+):

• Call Translation API overview
• Live audio translation
• Supported language pairs
• Streaming translation
• Privacy and permissions
• Performance optimization

When to read: Implementing translation features, building communication apps, adding multilingual support

references/swift-synchronization.md

Low-level concurrency primitives (Swift 6+):

• Atomic operations
• Mutex API
• Lock-free data structures
• Memory ordering semantics
• Integration with Swift concurrency

When to read: Implementing thread-safe primitives, building custom synchronization, optimizing performance-critical code

When to read: Using modern Swift features, implementing concurrency, managing memory, working with generics

references/cross-platform-development.md

Multi-platform strategies:

• Platform detection and conditional compilation
• Shared code architecture
• Platform-specific UI patterns
• Input method handling (touch vs pointer)
• Navigation patterns per platform
• Window management
• Code organization for maximum sharing

When to read: Building cross-platform apps, adapting UI for different platforms, maximizing code reuse

Assets

assets/ios-app-template.swift

Production-ready iOS app template with:

• TabView navigation
• MVVM architecture
• Async/await networking
• Authentication flow
• List with pull-to-refresh
• Proper error handling

assets/macos-app-template.swift

Production-ready macOS app template with:

• NavigationSplitView with sidebar
• Settings window
• Toolbar and menu commands
• Window management
• Keyboard shortcuts
• Edit sheets and forms

Best Practices Summary

Architecture:

• Use MVVM pattern
• Separate concerns clearly
• Inject dependencies
• Keep ViewModels testable

State Management:

• Choose the right property wrapper
• Minimize @Published properties
• Use unidirectional data flow
• Avoid retain cycles

Performance:

• Use lazy stacks for lists
• Provide stable IDs
• Extract subviews
• Profile regularly
• Test on real devices

Code Quality:

• Follow Swift naming conventions
• Use value types when possible
• Handle all error cases
• Write unit tests for ViewModels
• Use SwiftUI previews

Platform Integration:

• Follow Human Interface Guidelines
• Support Dynamic Type
• Implement proper accessibility
• Respect system settings (Dark Mode, Reduce Motion)
• Use SF Symbols for icons

Cross-Platform:

• Maximize code sharing (models, ViewModels, services)
• Use conditional compilation for platform differences
• Design adaptive layouts
• Respect platform conventions