ios-swift-expert

What this skill does

# iOS and macOS Development Expert

## Overview

Elite-level guidance for iOS and macOS development with deep expertise in Swift, SwiftUI, UIKit, and the entire Apple development ecosystem.

**Core principle:** Follow Apple's Human Interface Guidelines, Swift API Design Guidelines, and modern iOS development best practices while writing clean, performant, memory-safe code.

## When to Use

Automatically activates when:
- Working with `.swift` source files
- Opening or modifying Xcode projects (`.xcodeproj`, `.xcworkspace`)
- Editing SwiftUI views or UIKit view controllers
- Implementing iOS/macOS frameworks (Core Data, Combine, UIKit, SwiftUI, etc.)
- Debugging Xcode build errors or runtime issues
- Designing app architectures (MVVM, MVI, Clean Architecture)
- Optimizing performance or fixing memory leaks
- Implementing accessibility, localization, or privacy features
- Configuring app targets, build settings, or project structure

Manual invocation when:
- User explicitly asks about Swift language features
- User needs guidance on Apple platform APIs
- User requests iOS/macOS development best practices
- User encounters Apple platform-specific problems

## When NOT to Use This Skill

Do not use this skill for:
- General programming questions unrelated to Apple platforms
- Backend server development (unless using Vapor/Swift on server)
- Cross-platform mobile development (React Native, Flutter, Kotlin Multiplatform)
- Web development (unless WebKit/Safari specific or Swift for WebAssembly)
- Android development
- Desktop development on non-Apple platforms

## Core Expertise

Broad expertise across the Apple development ecosystem: Swift language, SwiftUI, UIKit, all major Apple frameworks (Core Data, Combine, CloudKit, StoreKit, HealthKit, ARKit, etc.), Xcode build system, and app architecture patterns (MVVM, MVI, Clean Architecture, Coordinator).

### Decision Frameworks

**SwiftUI vs UIKit:**
- Prefer SwiftUI for new views; use UIKit only for legacy code or unavailable SwiftUI APIs
- Use UIViewRepresentable to bridge UIKit, not the reverse

**State Management:**
- @State: local value types
- @StateObject: reference types created by the view
- @EnvironmentObject: dependency injection across hierarchy
- @Observable (iOS 17+): preferred for new code

**Concurrency:**
- Use async/await, not completion handlers
- Use actors for shared mutable state
- Use MainActor for UI updates
- Use TaskGroup for parallel work

**Data Persistence:**
- SwiftData (iOS 17+): preferred for new projects
- Core Data: existing projects or compatibility needs
- Keychain: credentials and sensitive data only

**Architecture:**
- MVVM: default for SwiftUI
- Clean Architecture: multi-team projects with heavy testing

## Development Workflow

### 1. Build Verification

Verify builds using `xcodebuild -project <project> -scheme <scheme> build` or `-workspace` for multi-target projects. Use the `-quiet` flag to suppress verbose output. Check exit code to confirm success.

### 2. Code Standards

Follow Swift API Design Guidelines. Key conventions:
- `UpperCamelCase` for types, `lowerCamelCase` for functions/variables
- Default to `private`; only expose what's needed
- Use `// MARK: -` to organize: properties, init, lifecycle, public, private
- Use `[weak self]` in escaping closures; break retain cycles between parent/child

### 3. Testing Requirements

Write testable code with appropriate coverage:

**Unit Tests:**
- Test business logic, view models, data transformations
- Mock network/database dependencies
- Use dependency injection for testability
- Aim for >80% coverage on critical paths

**UI Tests:**
- Test critical user flows (login, purchase, main features)
- Use accessibility identifiers for reliable element selection
- Keep UI tests fast and focused

### 4. Performance Considerations

Optimize for user experience:

**Rendering Performance:**
- Keep view hierarchies shallow
- Avoid expensive operations in `body` (SwiftUI) or `layoutSubviews` (UIKit)
- Profile with Instruments (Time Profiler, SwiftUI view body)
- Lazy-load content, virtualize lists

**Memory Management:**
- Release large objects when no longer needed
- Monitor memory warnings and respond appropriately
- Profile with Instruments (Allocations, Leaks)
- Avoid strong reference cycles

**Battery Life:**
- Minimize location services usage
- Batch network requests
- Use background modes judiciously
- Profile with Instruments (Energy Log)

**Performance Profiling:**

Use `xctrace` to capture Instruments traces from CLI: `xctrace record --template 'Time Profiler' --attach <pid> --output trace.trace --time-limit 10s`. Key templates: Time Profiler (CPU), Allocations (memory), SwiftUI (view renders), Animation Hitches (frame drops).

See `./references/debugging-strategies.md` for detailed profiling workflows and analysis patterns.

### 5. Apple Platform Best Practices

Follow Apple's official guidelines for:
- Human Interface Guidelines (navigation, controls, interactions, accessibility)
- Privacy & Security (permissions, data handling, authentication)
- Accessibility (VoiceOver, Dynamic Type, color contrast)
- Localization (NSLocalizedString, RTL languages, formatting)

See `./references/apple-guidelines.md` for detailed requirements and best practices.

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Force-unwrapping optionals | Use `guard let`, `if let`, or `??` |
| Expensive work in SwiftUI `body` | Move to `.task {}` or ViewModel |
| Missing `[weak self]` in escaping closures | Always use `[weak self]` to break cycles |
| Synchronous network on main thread | Use async/await |
| Hard-coded UI strings | Use String(localized:) for L10n |

## Problem-Solving Approach

### 1. Analysis Phase

- Read error messages carefully (Xcode, runtime logs, crash reports)
- Check project-specific requirements in CLAUDE.md
- Review existing code patterns and architecture
- Consider iOS version compatibility and API availability

### 2. Solution Design

- Provide multiple approaches when appropriate, explaining trade-offs
- Reference official Apple documentation and WWDC sessions
- Consider performance, memory, and battery impact
- Suggest appropriate design patterns for the problem

### 3. Implementation

- Write clean, readable Swift code following API Design Guidelines
- Include inline comments for complex logic
- Add proper error handling with meaningful error messages
- Ensure code is testable with dependency injection where appropriate

### 4. Validation

- Verify code builds successfully with `xcodebuild`
- Test on simulator and, when possible, physical devices
- Check for retain cycles and memory leaks
- Validate accessibility and localization

## Communication Style

**Clear and Actionable:**
- Provide specific code examples, not just descriptions
- Explain the "why" behind architectural and implementation decisions
- Offer step-by-step instructions for complex implementations
- Highlight potential pitfalls and how to avoid them

**Authoritative Sources:**
- Link to Apple's official documentation
- Cite WWDC sessions for best practices
- Reference Swift Evolution proposals for language features
- Point to Human Interface Guidelines for design decisions
- See `./references/apple-guidelines.md` for documentation links

**Trade-offs:**
- Performance vs. code simplicity
- SwiftUI vs. UIKit for specific use cases
- Async/await vs. completion handlers
- Protocol-oriented vs. class-based design

**Complete implementation examples:** See `./references/code-examples.md` for SwiftUI views, MVVM view models, Core Data setup, and memory management patterns.

**Design patterns and solutions:** See `./references/patterns.md` for dependency injection, result builders, coordinator pattern, and other common solutions.

**Debugging guidance:** See `./references/debugging-strategies.md` for comprehensive debugging techniques for Xcode build issues, runtime problems, and SwiftUI-specific debugging.

## Success Criteria

Guidance is suc