This page contains 7 additions and 202 deletions.
Need
Desktop actions and settings
Default options
commands, CommandMenu, keyboard shortcuts, and a Settings scene
Why it's needed
Menu bar actions, shortcuts, and a dedicated settings window make the feature feel like a real Mac app instead of an iOS screen stretched to desktop.
11name: Build a Mac app shell# Build a Mac app shell | Codex use cases
2tagline: Use Codex to build a Mac-native SwiftUI app shell with a sidebar,
3 detail pane, inspector, commands, and Settings.
4summary: Use Codex and the Build macOS Apps plugin to turn an app idea into a
5 desktop-native `NavigationSplitView` app, keep sidebar selection stable, add
6 menus, toolbars, and keyboard shortcuts, and move preferences into a dedicated
7 `Settings` scene.
8skills:
9 - token: build-macos-apps
10 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps
11 description: Use the macOS SwiftUI patterns, window management, AppKit interop,
12 and build/run skills to create sidebar-detail-inspector layouts, wire
13 menus and settings, and validate the app in a shell-first loop.
14bestFor:
15 - New Mac app ideas or iPad-first and web-first concepts that need a real
16 desktop shell with persistent navigation, menus, toolbars, and keyboard
17 shortcuts
18 - Editor, library, admin, or review tools where a sidebar selection drives a
19 detail pane and an inspector exposes secondary metadata or actions
20 - Mac apps where settings should live in a dedicated preferences window
21 instead of another pushed screen in the main content stack
22starterPrompt:
23 title: Build a Mac-Native Sidebar and Inspector Shell
24 body: >-
25 Use the Build macOS Apps plugin to turn [describe your app idea] into a
26 Mac-native SwiftUI app shell with a sidebar, detail pane, inspector,
27 commands, and Settings.
28 2
3Need
29 4
305 Constraints:Desktop actions and settings
31 6
327 - Choose the scene model first. Prefer `WindowGroup` for the main window andDefault options
33 add a dedicated `Settings` scene for preferences.
34 8
359 - Build the main UI around `NavigationSplitView` with explicit selection`commands`, `CommandMenu`, keyboard shortcuts, and a `Settings` scene
36 state, a native `.sidebar` list, a detail surface, and an
37 `inspector(isPresented:)` panel for secondary metadata or controls.
38 10
3911 - Keep sidebar rows lightweight and native: one icon, one title line, and atWhy it's needed
40 most one short secondary line. Do not wrap every row in large custom cards
41 unless there is a strong product reason.
42 12
4313 - Expose important actions through scene-level `commands`, `CommandMenu`,Menu bar actions, shortcuts, and a dedicated settings window make the feature feel like a real Mac app instead of an iOS screen stretched to desktop.
44 toolbar buttons, and keyboard shortcuts. Do not hide the only path to a
45 critical action behind gestures.
46 14
47 - Use `@SceneStorage` for window-scoped UI state, `@AppStorage` for
48 preferences, and explicit parent-owned selection bindings for sidebar/detail
49 coordination.
50
51 - Prefer system materials, semantic colors, and standard sidebar
52 backgrounds. Add custom styling only to detail or inspector content cards
53 when needed.
54
55 - Use a narrow AppKit bridge only if SwiftUI cannot express one specific
56 desktop behavior cleanly.
57
58 - Create or update `script/build_and_run.sh`, run the smallest useful
59 build/run check, and tell me the exact commands you used.
60
61
62 Deliver:
63
64 - the scene structure and main sidebar/detail/inspector views
65
66 - the menu, toolbar, and keyboard shortcut wiring
67
68 - the Settings scene and preference state model
69
70 - any AppKit bridge you added and why it was necessary
71
72 - the build/run validation steps and any desktop UX follow-up you recommend
73relatedLinks:
74 - label: Build macOS Apps plugin
75 url: https://github.com/openai/plugins/tree/main/plugins/build-macos-apps
76 - label: Agent skills
77 url: /codex/skills
78techStack:
79 - need: Split-view app shell
80 goodDefault: "`NavigationSplitView`, `.sidebar` lists, and `inspector(isPresented:)`"
81 why: A persistent sidebar, detail pane, and inspector match common Mac app
82 layouts better than touch-first push navigation.
83 - need: Desktop actions and settings
84 goodDefault: "`commands`, `CommandMenu`, keyboard shortcuts, and a `Settings` scene"
85 why: Menu bar actions, shortcuts, and a dedicated settings window make the
86 feature feel like a real Mac app instead of an iOS screen stretched to
87 desktop.
88 - need: State ownership
89 goodDefault: "`@State`, `@SceneStorage`, `@AppStorage`, and explicit selection bindings"
90 why: Codex can keep sidebar selection, inspector visibility, and user
91 preferences predictable without adding a view model by reflex.
92 - need: Native escape hatches
93 goodDefault: "[AppKit](https://developer.apple.com/documentation/appkit) through
94 narrow `NSViewRepresentable` or `NSWindow` bridges"
95 why: Use AppKit only for platform behaviors SwiftUI cannot express cleanly,
96 while keeping SwiftUI as the source of truth for scene and selection
97 state.
98
99## Start from the Mac scene model
100
101This use case is for turning an app idea into a Mac app shell that feels built for desktop, not stretched from a touch-first stack. Ask Codex to choose the scene model first, then design the main window around stable sidebar selection, a detail surface, and an inspector for secondary controls or metadata.
102
103
104
105Use the [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps) when you want Codex to apply that desktop structure and keep the build/run loop shell-first. Its macOS SwiftUI patterns skill is a good fit for scene design, sidebars, inspectors, commands, settings, and small AppKit bridges when SwiftUI stops just short of one Mac-specific behavior.
106
107## Build a sidebar, detail pane, and inspector
108
109Prefer `NavigationSplitView` when the feature benefits from persistent navigation and a stable selected item. Keep sidebar rows native and lightweight, let the sidebar use system backgrounds, and reserve custom cards or dense metadata for the detail pane or inspector.
110
111```swift
112struct LibraryRootView: View {
113 @SceneStorage("LibraryRootView.selection") private var selection: Item.ID?
114 @SceneStorage("LibraryRootView.showInspector") private var showInspector = true
115
116 var body: some View {
117 NavigationSplitView {
118 List(selection: $selection) {
119 ForEach(items) { item in
120 Label(item.title, systemImage: item.systemImage)
121 .tag(item.id)
122 }
123 }
124 .listStyle(.sidebar)
125 .navigationTitle("Library")
126 } detail: {
127 ItemDetailView(selection: selection)
128 .inspector(isPresented: $showInspector) {
129 ItemInspectorView(selection: selection)
130 }
131 }
132 }
133}
134```
135
136If the app needs unusual split sizing, low-level window coordination, or custom responder-chain behavior, ask Codex to keep the SwiftUI shell intact and add only the smallest AppKit bridge required for that one gap.
137
138## Put commands, toolbars, and shortcuts in the desktop layer
139
140Mac users should be able to discover important actions in the menu bar, the toolbar, and keyboard shortcuts. Ask Codex to wire scene-level `commands`, context-sensitive menu items, and toolbar buttons around the same app actions so desktop users do not have to hunt for gesture-only controls.
141
142```swift
143@main
144struct LibraryApp: App {
145 var body: some Scene {
146 WindowGroup {
147 LibraryRootView()
148 }
149 .commands {
150 CommandMenu("Library") {
151 Button("New Item") {
152 // Create a new item.
153 }
154 .keyboardShortcut("n")
155
156 Button("Toggle Inspector") {
157 // Route this command to the focused window or selected item state.
158 }
159 .keyboardShortcut("i", modifiers: [.command, .option])
160 }
161 }
162
163 Settings {
164 LibrarySettingsView()
165 }
166 }
167}
168```
169
170Use `FocusedValue`, scene state, or explicit selection state when a command should apply to the current detail item. If a shortcut would be registered in multiple places, ask Codex to consolidate ownership so the app has one clear command route.
171
172## Keep preferences in `Settings`
173
174For app preferences, use a dedicated `Settings` scene and persist durable user choices with `@AppStorage`. This is usually a better Mac fit than pushing a settings screen inside the main content window.
175
176```swift
177struct LibrarySettingsView: View {
178 @AppStorage("showItemMetadata") private var showItemMetadata = true
179
180 var body: some View {
181 TabView {
182 Form {
183 Toggle("Show Item Metadata", isOn: $showItemMetadata)
184 }
185 .tabItem { Label("General", systemImage: "gearshape") }
186 }
187 .frame(width: 460, height: 260)
188 .scenePadding()
189 }
190}
191```
192
193## Prompt the app concept, then validate the shell
194
195This page works best when your prompt names the app concept, the main content objects, and the primary actions, then asks Codex to build the desktop shell around that workflow first. Have the agent run a small build/run check and summarize the scene structure, command wiring, state ownership, and any AppKit edge it had to bridge.
196
197## Practical tips
198
199### Keep the sidebar native
200
201Use one icon, one title line, and at most one short secondary line in sidebar rows. Move richer cards, counters, and metadata into the detail pane or inspector so the source list stays easy to scan.
202
203### Avoid hiding settings in the main stack
204
205If a user preference affects the whole app, ask Codex to put that control in `Settings` with `@AppStorage` and expose an entry point through the app menu instead of building another pushed settings screen.
206
207### Save AppKit for narrow desktop gaps
208
209If the feature needs open/save panels, first-responder control, or a custom `NSView`, use AppKit as a small edge around a SwiftUI-owned state model rather than rewriting the whole window in AppKit.
