Swift/SwiftUI Refactor (Modular MVVM-C)

Comprehensive refactoring guide for migrating Swift/SwiftUI code to modular MVVM-C with local SPM package boundaries and App-target composition root wiring.

Mandated Architecture Stack

┌───────────────────────────────────────────────────────────────┐ │ App target: DependencyContainer, Coordinators, Route Shells │ ├───────────────────────────────────────────────────────────────┤ │ Feature modules: View + ViewModel (Domain + DesignSystem deps)│ ├───────────────────────────────────────────────────────────────┤ │ Data package: repositories, remote/local stores, sync, retry │ ├───────────────────────────────────────────────────────────────┤ │ Domain package: models, repository/coordinator/error protocols │ └───────────────────────────────────────────────────────────────┘

Dependency Rule: Feature modules never import Data and never import sibling features.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import Domain

• DesignSystem only (never Data , never sibling features)

• App target is the convergence point and owns DependencyContainer , concrete coordinators, and Route Shell wiring

• Domain stays pure Swift and defines models plus repository, *Coordinating , ErrorRouting , and AppError contracts

• Data owns SwiftData/network/sync/retry/background I/O and implements Domain protocols

• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes

• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Migrating from deprecated SwiftUI APIs (ObservableObject, NavigationView, old onChange)

• Restructuring state management to use @Observable ViewModels

• Adding @Equatable diffing to views for performance

• Decomposing large views into 10-node maximum bodies

• Refactoring navigation to coordinator + route shell pattern

• Refactoring to Domain/Data/Feature/App package boundaries

• Setting up dependency injection through DependencyContainer

• Improving list/collection scroll performance

• Replacing manual Task management with .task(id:) and cancellable loading

Non-Negotiable Constraints (iOS 26 / Swift 6.2)

• @Observable ViewModels/coordinators, ObservableObject / @Published never

• NavigationStack is owned by App-target route shells and coordinators

• @Equatable macro on every view, AnyView never

• Domain defines repository/coordinator/error-routing protocols; no framework-coupled I/O

• No dedicated use-case/interactor layer; ViewModels call repository protocols directly

• Views never access repositories directly

Rule Categories by Priority

Priority Category Impact Prefix Rules

1 View Identity & Diffing CRITICAL diff-

4

2 API Modernization CRITICAL api-

7

3 State Architecture CRITICAL state-

6

4 View Composition HIGH view-

7

5 Navigation & Coordination HIGH nav-

5

6 Layer Architecture HIGH layer-

5

7 Architecture Patterns HIGH arch-

5

8 Dependency Injection MEDIUM-HIGH di-

2

9 Type Safety & Protocols MEDIUM-HIGH type-

4

10 List & Collection Performance MEDIUM list-

4

11 Async & Data Flow MEDIUM data-

3

12 Swift Language Fundamentals MEDIUM swift-

8

Quick Reference

1. View Identity & Diffing (CRITICAL)

• diff-equatable-views

• Add @Equatable macro to every SwiftUI view

• diff-closure-skip

• Use @EquatableIgnored for closure properties

• diff-identity-stability

• Use stable O(1) identifiers in ForEach

• diff-printchanges-debug

• Use _printChanges() to diagnose re-renders

2. API Modernization (CRITICAL)

• api-observable-macro

• Migrate ObservableObject to @Observable macro

• api-navigationstack-migration

• Replace NavigationView with NavigationStack

• api-onchange-signature

• Migrate to new onChange signature

• api-environment-object-removal

• Replace @EnvironmentObject with @Environment

• api-alert-confirmation-dialog

• Migrate Alert to confirmationDialog API

• api-list-foreach-identifiable

• Replace id: .self with Identifiable conformance

• api-toolbar-migration

• Replace navigationBarItems with toolbar modifier

3. State Architecture (CRITICAL)

• state-scope-minimization

• Minimize state scope to nearest consumer

• state-derived-over-stored

• Use computed properties over redundant @State

• state-binding-extraction

• Extract @Binding to isolate child re-renders

• state-remove-observation

• Migrate @ObservedObject to @Observable tracking

• state-onappear-to-task

• Replace onAppear closures with .task modifier

• state-stateobject-placement

• Migrate @StateObject to @State with @Observable

4. View Composition (HIGH)

• view-extract-subviews

• Extract subviews for diffing checkpoints

• view-eliminate-anyview

• Replace AnyView with @ViewBuilder or generics

• view-computed-to-struct

• Convert computed view properties to struct views

• view-modifier-extraction

• Extract repeated modifiers into custom ViewModifiers

• view-conditional-content

• Use Group or conditional modifiers over conditional views

• view-preference-keys

• Replace callback closures with PreferenceKey

• view-body-complexity

• Reduce view body to maximum 10 nodes

5. Navigation & Coordination (HIGH)

• nav-centralize-destinations

• Refactor navigation to coordinator pattern

• nav-value-based-links

• Replace NavigationLink with coordinator routes

• nav-path-state-management

• Use NavigationPath for programmatic navigation

• nav-split-view-adoption

• Use NavigationSplitView for multi-column layouts

• nav-sheet-item-pattern

• Replace boolean sheet triggers with item binding

6. Layer Architecture (HIGH)

• layer-dependency-rule

• Extract domain layer with zero framework imports

• layer-usecase-protocol

• Remove use-case/interactor layer; keep orchestration in ViewModel + repository protocols

• layer-repository-protocol

• Repository protocols in Domain, implementations in Data

• layer-no-view-repository

• Remove direct repository access from views

• layer-viewmodel-boundary

• Refactor ViewModels to expose display-ready state only

7. Architecture Patterns (HIGH)

• arch-viewmodel-elimination

• Restructure inline state into @Observable ViewModel

• arch-protocol-dependencies

• Extract protocol dependencies through ViewModel layer

• arch-environment-key-injection

• Use Environment keys for service injection

• arch-feature-module-extraction

• Extract features into independent modules

• arch-model-view-separation

• Extract business logic into Domain models and repository-backed ViewModels

8. Dependency Injection (MEDIUM-HIGH)

• di-container-composition

• Compose dependency container at app root

• di-mock-testing

• Add mock implementation for every protocol dependency

9. Type Safety & Protocols (MEDIUM-HIGH)

• type-tagged-identifiers

• Replace String IDs with tagged types

• type-result-over-optionals

• Use Result type over optional with error flag

• type-phantom-types

• Use phantom types for compile-time state machines

• type-force-unwrap-elimination

• Eliminate force unwraps with safe alternatives

10. List & Collection Performance (MEDIUM)

• list-constant-viewcount

• Ensure ForEach produces constant view count per element

• list-filter-in-model

• Move filter/sort logic from ForEach into ViewModel

• list-lazy-stacks

• Replace VStack/HStack with Lazy variants for unbounded content

• list-id-keypath

• Provide explicit id keyPath — never rely on implicit identity

11. Async & Data Flow (MEDIUM)

• data-task-modifier

• Replace onAppear async work with .task modifier

• data-error-loadable

• Model loading states as enum instead of boolean flags

• data-cancellation

• Use .task automatic cancellation — never manage Tasks manually

12. Swift Language Fundamentals (MEDIUM)

• swift-let-vs-var

• Use let for constants, var for variables

• swift-structs-vs-classes

• Prefer structs over classes

• swift-camel-case-naming

• Use camelCase naming convention

• swift-string-interpolation

• Use string interpolation for dynamic text

• swift-functions-clear-names

• Name functions and parameters for clarity

• swift-for-in-loops

• Use for-in loops for collections

• swift-optionals

• Handle optionals safely with unwrapping

• swift-closures

• Use closures for inline functions

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

Reference Files

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules