7 added, 119 removed.
Need
UI architecture
Default options
SwiftUI with an MV-first split across @State, @Environment, and small dedicated View types
Why it's needed
Large screens usually get easier to maintain when Codex simplifies the view tree and state flow before introducing another view model layer.
11name: Refactor SwiftUI screens# Refactor SwiftUI screens | Codex use cases
2tagline: Use Codex to split an oversized SwiftUI screen into small subviews
3 without changing behavior or layout.
4summary: Use Codex and the Build iOS Apps plugin to break a long SwiftUI view
5 into dedicated section views, move side effects out of `body`, stabilize state
6 and Observation usage, and keep the refactor MV-first instead of introducing
7 unnecessary view models.
8skills:
9 - token: build-ios-apps
10 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
11 description: Use the SwiftUI view refactor skill to extract dedicated subviews,
12 preserve stable data flow, simplify Observation usage, and keep behavior
13 intact while Codex edits large SwiftUI screens.
14bestFor:
15 - Giant SwiftUI files where `body` mixes layout, branching, async work, and
16 inline actions in one hard-to-review screen
17 - Existing iOS features that should stay visually and behaviorally identical
18 while the internals become easier to maintain
19 - Screens with computed `some View` fragments, optional view models, or state
20 plumbing that should be simplified into explicit subview inputs and
21 callbacks
22starterPrompt:
23 title: Refactor One Large Screen Without Changing Behavior
24 body: >-
25 Use the Build iOS Apps plugin and its SwiftUI view refactor skill to clean
26 up [NameOfScreen.swift] without changing what the screen does or how it
27 looks.
28 2
3Need
29 4
305 Constraints:UI architecture
31 6
327 - Preserve behavior, layout, navigation, and business logic unless you findDefault options
33 a bug that must be called out separately.
34 8
359 - Default to MV, not MVVM. Prefer `@State`, `@Environment`, `@Query`,SwiftUI with an MV-first split across `@State`, `@Environment`, and small dedicated `View` types
36 `.task`, `.task(id:)`, and `onChange` before introducing a new view model,
37 and only keep a view model if this feature clearly needs one.
38 10
3911 - Reorder the view so stored properties, computed state, `init`, `body`,Why it's needed
40 view helpers, and helper methods are easy to scan top to bottom.
41 12
4213 - Extract meaningful sections into dedicated `View` types with smallLarge screens usually get easier to maintain when Codex simplifies the view tree and state flow before introducing another view model layer.
43 explicit inputs, `@Binding`s, and callbacks. Do not replace one giant `body`
44 with a pile of large computed `some View` properties.
45 14
46 - Move non-trivial button actions and side effects out of `body` into small
47 methods, and move real business logic into services or models.
48
49 - Keep the root view tree stable. Avoid top-level `if/else` branches that
50 swap entirely different screens when localized conditional sections or
51 modifiers are enough.
52
53 - Fix Observation ownership while refactoring: use `@State` for root
54 `@Observable` models on iOS 17+, and avoid optional or delayed-initialized
55 view models unless the UI genuinely needs that state shape.
56
57 - After each extraction, run the smallest useful build or test check that
58 proves the screen still behaves the same.
59
60
61 Deliver:
62
63 - the refactored screen and any extracted subviews
64
65 - a short explanation of the new subview boundaries and data flow
66
67 - any places where you intentionally kept a view model and why
68
69 - the validation checks you ran to prove behavior stayed intact
70relatedLinks:
71 - label: Build iOS Apps plugin
72 url: https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
73 - label: Agent skills
74 url: /codex/skills
75techStack:
76 - need: UI architecture
77 goodDefault: SwiftUI with an MV-first split across `@State`, `@Environment`, and
78 small dedicated `View` types
79 why: Large screens usually get easier to maintain when Codex simplifies the view
80 tree and state flow before introducing another view model layer.
81 - need: Refactor workflow
82 goodDefault: "[Build iOS Apps
83 plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-app\
84 s)"
85 why: The plugin's SwiftUI view refactor skill gives Codex clear rules for
86 extraction, Observation, and side-effect cleanup while preserving
87 behavior.
88 - need: Validation
89 goodDefault: "`xcodebuild`, previews, and focused UI checks"
90 why: Small build or simulator checks after each extraction make it easier to
91 trust a behavior-preserving refactor than a one-shot rewrite.
92
93## Refactor one screen without changing what it does
94
95This use case is for the moment when a SwiftUI file has grown into one giant screen and every small edit feels risky. The goal is not to redesign the feature or invent a new architecture. Ask Codex to preserve behavior and layout, then split the screen into small subviews with explicit data flow so the next change becomes easier to review.
96
97Use the [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) for this kind of cleanup. Its SwiftUI view refactor skill is opinionated in a useful way: default to MV over MVVM, keep business logic in services or models, use local view state and environment dependencies first, and only keep a view model when the feature clearly needs one.
98
99## What to ask Codex to do
100
101Start by naming one concrete screen file and asking Codex to preserve behavior while improving structure. These are the refactor rules worth putting directly in your prompt:
102
103- Reorder the file so environment dependencies, stored properties, computed non-view state, `init`, `body`, view helpers, and helper methods are easy to scan top to bottom.
104- Extract meaningful sections into dedicated `View` types with small explicit inputs, `@Binding`s, and callbacks.
105- Keep computed `some View` helpers rare and small. Do not rebuild one giant screen as a long list of private computed view fragments.
106- Move non-trivial button actions and side effects out of `body`, and move real business logic into services or models.
107- Keep the root view tree stable. Prefer localized conditionals in sections or modifiers over top-level `if/else` branches that swap whole screens.
108- Fix Observation ownership as you go. For root `@Observable` models on iOS 17+, the owning view should store them in `@State`; use legacy observable wrappers only when your deployment target requires that.
109
110## Ask for a small validation loop
111
112Behavior-preserving refactors should come with proof. Ask Codex to run the smallest build, preview, test, or simulator check that exercises the screen after each meaningful extraction, then summarize what changed structurally and what stayed intentionally the same.
113
114## Practical tips
115
116### Split first, then debate architecture
117
118If a screen is too large, ask Codex to extract section views before introducing a new abstraction layer. A shorter, more explicit view tree often removes the pressure to add a view model at all.
119
120### Pass the smallest possible interface into each subview
121
122Prefer `let` values, `@Binding`s, and one-purpose callbacks over handing every child view the entire parent model. That makes each extracted section easier to preview and harder to accidentally couple back to the whole screen.
123
124### Ask Codex to call out intentional non-changes
125
126For a safe refactor, it helps when Codex explicitly lists what it did not change: business rules, navigation behavior, persistence, analytics semantics, and user-visible layout. That makes review much faster.
