Guide Skill — This is an expert workflow/pattern guide, not API reference documentation.
Originally from Dimillian/Skills by Thomas Ricouard. MIT License.
SwiftUI View Refactor
Overview
Refactor SwiftUI views toward small, explicit, stable view types. Default to vanilla SwiftUI: local state in the view, shared dependencies in the environment, business logic in services/models, and view models only when the request or existing code clearly requires one.
Core Guidelines
1) View ordering (top → bottom)
- Enforce this ordering unless the existing file has a stronger local convention you must preserve.
- Environment
private/public let
@State / other stored properties
- computed
var (non-view)
init
body
- computed view builders / other view helpers
- helper / async functions
2) Default to MV, not MVVM
- Views should be lightweight state expressions and orchestration points, not containers for business logic.
- Favor
@State, @Environment, @Query, .task, .task(id:), and onChange before reaching for a view model.
- Inject services and shared models via
@Environment; keep domain logic in services/models, not in the view body.
- Do not introduce a view model just to mirror local view state or wrap environment dependencies.
- If a screen is getting large, split the UI into subviews before inventing a new view model layer.
3) Strongly prefer dedicated subview types over computed some View helpers
- Flag
body properties that are longer than roughly one screen or contain multiple logical sections.
- Prefer extracting dedicated
View types for non-trivial sections, especially when they have state, async work, branching, or deserve their own preview.
- Keep computed
some View helpers rare and small. Do not build an entire screen out of private var header: some View-style fragments.
- Pass small, explicit inputs (data, bindings, callbacks) into extracted subviews instead of handing down the entire parent state.
- If an extracted subview becomes reusable or independently meaningful, move it to its own file.
Prefer:
var body: some View {
List {
HeaderSection(title: title, subtitle: subtitle)
FilterSection(
filterOptions: filterOptions,
selectedFilter: $selectedFilter
)
ResultsSection(items: filteredItems)
FooterSection()
}
}
private struct HeaderSection: View {
let title: String
let subtitle: String
var body: some View {
VStack(alignment: .leading, spacing: 6) {
Text(title).font(.title2)
Text(subtitle).font(.subheadline)
}
}
}
private struct FilterSection: View {
let filterOptions: [FilterOption]
@Binding var selectedFilter: FilterOption
var body: some View {
ScrollView(.horizontal, showsIndicators: false) {
HStack {
ForEach(filterOptions, id: \.self) { option in
FilterChip(option: option, isSelected: option == selectedFilter)
.onTapGesture { selectedFilter = option }
}
}
}
}
}
Avoid:
var body: some View {
List {
header
filters
results
footer
}
}
private var header: some View {
VStack(alignment: .leading, spacing: 6) {
Text(title).font(.title2)
Text(subtitle).font(.subheadline)
}
}
3b) Extract actions and side effects out of body
- Do not keep non-trivial button actions inline in the view body.
- Do not bury business logic inside
.task, .onAppear, .onChange, or .refreshable.
- Prefer calling small private methods from the view, and move real business logic into services/models.
- The body should read like UI, not like a view controller.
Button("Save", action: save)
.disabled(isSaving)
.task(id: searchText) {
await reload(for: searchText)
}
private func save() {
Task { await saveAsync() }
}
private func reload(for searchText: String) async {
guard !searchText.isEmpty else {
results = []
return
}
await searchService.search(searchText)
}
4) Keep a stable view tree (avoid top-level conditional view swapping)
- Avoid
body or computed views that return completely different root branches via if/else.
- Prefer a single stable base view with conditions inside sections/modifiers (
overlay, opacity, disabled, toolbar, etc.).
- Root-level branch swapping causes identity churn, broader invalidation, and extra recomputation.
Prefer:
var body: some View {
List {
documentsListContent
}
.toolbar {
if canEdit {
editToolbar
}
}
}
Avoid:
var documentsListView: some View {
if canEdit {
editableDocumentsList
} else {
readOnlyDocumentsList
}
}
5) View model handling (only if already present or explicitly requested)
- Treat view models as a legacy or explicit-need pattern, not the default.
- Do not introduce a view model unless the request or existing code clearly calls for one.
- If a view model exists, make it non-optional when possible.
- Pass dependencies to the view via
init, then create the view model in the view's init.
- Avoid
bootstrapIfNeeded patterns and other delayed setup workarounds.
Example (Observation-based):
@State private var viewModel: SomeViewModel
init(dependency: Dependency) {
_viewModel = State(initialValue: SomeViewModel(dependency: dependency))
}
6) Observation usage
- For
@Observable reference types on iOS 17+, store them as @State in the owning view.
- Pass observables down explicitly; avoid optional state unless the UI genuinely needs it.
- If the deployment target includes iOS 16 or earlier, use
@StateObject at the owner and @ObservedObject when injecting legacy observable models.
Workflow
- Reorder the view to match the ordering rules.
- Remove inline actions and side effects from
body; move business logic into services/models and keep only thin orchestration in the view.
- Shorten long bodies by extracting dedicated subview types; avoid rebuilding the screen out of many computed
some View helpers.
- Ensure stable view structure: avoid top-level
if-based branch swapping; move conditions to localized sections/modifiers.
- If a view model exists or is explicitly required, replace optional view models with a non-optional
@State view model initialized in init.
- Confirm Observation usage:
@State for root @Observable models on iOS 17+, legacy wrappers only when the deployment target requires them.
- Keep behavior intact: do not change layout or business logic unless requested.
Notes
- Prefer small, explicit view types over large conditional blocks and large computed
some View properties.
- Keep computed view builders below
body and non-view computed vars above init.
- A good SwiftUI refactor should make the view read top-to-bottom as data flow plus layout, not as mixed layout and imperative logic.
- For MV-first guidance and rationale, see
references/mv-patterns.md.
Large-view handling
When a SwiftUI view file exceeds ~300 lines, split it aggressively. Extract meaningful sections into dedicated View types instead of hiding complexity in many computed properties. Use private extensions with // MARK: - comments for actions and helpers, but do not treat extensions as a substitute for breaking a giant screen into smaller view types. If an extracted subview is reused or independently meaningful, move it into its own file.
1---
2name: guide-swiftui-view-refactor
3description: Refactor and review SwiftUI view files with strong defaults for small dedicated subviews, MV-over-MVVM data flow, stable view trees, explicit dependency injection, and correct Observation usage. Use when cleaning up a SwiftUI view, splitting long bodies, removing inline actions or side effects, reducing computed `some View` helpers, or standardizing `@Observable` and view model initialization patterns.
4type: guide
5origin: https://github.com/Dimillian/Skills
6license: MIT
7metadata:
8 source: https://skillmd.com/skills/prisma-labs-dev/guide-swiftui-view-refactor
9---
10
11> **Guide Skill** — This is an expert workflow/pattern guide, not API reference documentation.
12> Originally from [Dimillian/Skills](https://github.com/Dimillian/Skills) by Thomas Ricouard. MIT License.
13
14
15# SwiftUI View Refactor
16
17## Overview
18Refactor SwiftUI views toward small, explicit, stable view types. Default to vanilla SwiftUI: local state in the view, shared dependencies in the environment, business logic in services/models, and view models only when the request or existing code clearly requires one.
19
20## Core Guidelines
21
22### 1) View ordering (top → bottom)
23- Enforce this ordering unless the existing file has a stronger local convention you must preserve.
24- Environment
25- `private`/`public` `let`
26- `@State` / other stored properties
27- computed `var` (non-view)
28- `init`
29- `body`
30- computed view builders / other view helpers
31- helper / async functions
32
33### 2) Default to MV, not MVVM
34- Views should be lightweight state expressions and orchestration points, not containers for business logic.
35- Favor `@State`, `@Environment`, `@Query`, `.task`, `.task(id:)`, and `onChange` before reaching for a view model.
36- Inject services and shared models via `@Environment`; keep domain logic in services/models, not in the view body.
37- Do not introduce a view model just to mirror local view state or wrap environment dependencies.
38- If a screen is getting large, split the UI into subviews before inventing a new view model layer.
39
40### 3) Strongly prefer dedicated subview types over computed `some View` helpers
41- Flag `body` properties that are longer than roughly one screen or contain multiple logical sections.
42- Prefer extracting dedicated `View` types for non-trivial sections, especially when they have state, async work, branching, or deserve their own preview.
43- Keep computed `some View` helpers rare and small. Do not build an entire screen out of `private var header: some View`-style fragments.
44- Pass small, explicit inputs (data, bindings, callbacks) into extracted subviews instead of handing down the entire parent state.
45- If an extracted subview becomes reusable or independently meaningful, move it to its own file.
46
47Prefer:
48
49```swift
50var body: some View {
51 List {
52 HeaderSection(title: title, subtitle: subtitle)
53 FilterSection(
54 filterOptions: filterOptions,
55 selectedFilter: $selectedFilter
56 )
57 ResultsSection(items: filteredItems)
58 FooterSection()
59 }
60}
61
62private struct HeaderSection: View {
63 let title: String
64 let subtitle: String
65
66 var body: some View {
67 VStack(alignment: .leading, spacing: 6) {
68 Text(title).font(.title2)
69 Text(subtitle).font(.subheadline)
70 }
71 }
72}
73
74private struct FilterSection: View {
75 let filterOptions: [FilterOption]
76 @Binding var selectedFilter: FilterOption
77
78 var body: some View {
79 ScrollView(.horizontal, showsIndicators: false) {
80 HStack {
81 ForEach(filterOptions, id: \.self) { option in
82 FilterChip(option: option, isSelected: option == selectedFilter)
83 .onTapGesture { selectedFilter = option }
84 }
85 }
86 }
87 }
88}
89```
90
91Avoid:
92
93```swift
94var body: some View {
95 List {
96 header
97 filters
98 results
99 footer
100 }
101}
102
103private var header: some View {
104 VStack(alignment: .leading, spacing: 6) {
105 Text(title).font(.title2)
106 Text(subtitle).font(.subheadline)
107 }
108}
109```
110
111### 3b) Extract actions and side effects out of `body`
112- Do not keep non-trivial button actions inline in the view body.
113- Do not bury business logic inside `.task`, `.onAppear`, `.onChange`, or `.refreshable`.
114- Prefer calling small private methods from the view, and move real business logic into services/models.
115- The body should read like UI, not like a view controller.
116
117```swift
118Button("Save", action: save)
119 .disabled(isSaving)
120
121.task(id: searchText) {
122 await reload(for: searchText)
123}
124
125private func save() {
126 Task { await saveAsync() }
127}
128
129private func reload(for searchText: String) async {
130 guard !searchText.isEmpty else {
131 results = []
132 return
133 }
134 await searchService.search(searchText)
135}
136```
137
138### 4) Keep a stable view tree (avoid top-level conditional view swapping)
139- Avoid `body` or computed views that return completely different root branches via `if/else`.
140- Prefer a single stable base view with conditions inside sections/modifiers (`overlay`, `opacity`, `disabled`, `toolbar`, etc.).
141- Root-level branch swapping causes identity churn, broader invalidation, and extra recomputation.
142
143Prefer:
144
145```swift
146var body: some View {
147 List {
148 documentsListContent
149 }
150 .toolbar {
151 if canEdit {
152 editToolbar
153 }
154 }
155}
156```
157
158Avoid:
159
160```swift
161var documentsListView: some View {
162 if canEdit {
163 editableDocumentsList
164 } else {
165 readOnlyDocumentsList
166 }
167}
168```
169
170### 5) View model handling (only if already present or explicitly requested)
171- Treat view models as a legacy or explicit-need pattern, not the default.
172- Do not introduce a view model unless the request or existing code clearly calls for one.
173- If a view model exists, make it non-optional when possible.
174- Pass dependencies to the view via `init`, then create the view model in the view's `init`.
175- Avoid `bootstrapIfNeeded` patterns and other delayed setup workarounds.
176
177Example (Observation-based):
178
179```swift
180@State private var viewModel: SomeViewModel
181
182init(dependency: Dependency) {
183 _viewModel = State(initialValue: SomeViewModel(dependency: dependency))
184}
185```
186
187### 6) Observation usage
188- For `@Observable` reference types on iOS 17+, store them as `@State` in the owning view.
189- Pass observables down explicitly; avoid optional state unless the UI genuinely needs it.
190- If the deployment target includes iOS 16 or earlier, use `@StateObject` at the owner and `@ObservedObject` when injecting legacy observable models.
191
192## Workflow
193
1941. Reorder the view to match the ordering rules.
1952. Remove inline actions and side effects from `body`; move business logic into services/models and keep only thin orchestration in the view.
1963. Shorten long bodies by extracting dedicated subview types; avoid rebuilding the screen out of many computed `some View` helpers.
1974. Ensure stable view structure: avoid top-level `if`-based branch swapping; move conditions to localized sections/modifiers.
1985. If a view model exists or is explicitly required, replace optional view models with a non-optional `@State` view model initialized in `init`.
1996. Confirm Observation usage: `@State` for root `@Observable` models on iOS 17+, legacy wrappers only when the deployment target requires them.
2007. Keep behavior intact: do not change layout or business logic unless requested.
201
202## Notes
203
204- Prefer small, explicit view types over large conditional blocks and large computed `some View` properties.
205- Keep computed view builders below `body` and non-view computed vars above `init`.
206- A good SwiftUI refactor should make the view read top-to-bottom as data flow plus layout, not as mixed layout and imperative logic.
207- For MV-first guidance and rationale, see `references/mv-patterns.md`.
208
209## Large-view handling
210
211When a SwiftUI view file exceeds ~300 lines, split it aggressively. Extract meaningful sections into dedicated `View` types instead of hiding complexity in many computed properties. Use `private` extensions with `// MARK: -` comments for actions and helpers, but do not treat extensions as a substitute for breaking a giant screen into smaller view types. If an extracted subview is reused or independently meaningful, move it into its own file.