UX Paths (native macOS/iOS)
Generate a catalog of realistic user journeys through a native app by reading its
code. Output feeds /ux-walker-native.
This is the sibling of /ux-paths. The method is the same — discovery agent,
story swarm, consolidation — and the process, output format, and story schema
are inherited unchanged. Read ../ux-paths/SKILL.md and follow
it, applying the substitutions below.
Do not duplicate that skill's phases here. This file only records what changes
for a native target.
What changes
Discovery: where the app's surface actually lives
A web discovery agent looks for routes. A native app has no router. Look for:
| Web concept |
Look for in a native app |
| Routes / pages |
WindowGroup, Settings, NavigationStack, NavigationSplitView, .sheet, .popover, .alert, TabView, Storyboard scenes, NSViewController subclasses |
| Nav bar / sidebar |
List in a sidebar column, NavigationLink, Sidebar toolbar items, TabView |
| Buttons and forms |
Button, TextField, Toggle, Picker, Stepper, Slider, Form, @FocusState |
| Client-side state |
@State, @Observable, @AppStorage, @SceneStorage, UserDefaults, NSUbiquitousKeyValueStore |
| API layer |
URLSession clients, XPC services, a bundled local server, CLI subprocesses the app spawns |
| Auth |
Keychain access, ASWebAuthenticationSession, OAuth token stores, subscription receipts |
| Feature flags |
Build configuration, #if DEBUG, launch arguments, environment variables the app reads |
Also enumerate — these have no web equivalent and are where native apps fail:
- Menu bar commands. Every
CommandGroup, CommandMenu, and .keyboardShortcut.
Each menu item is a user-reachable capability and belongs in the story catalog.
- Keyboard shortcuts. Collect the full list. "Complete this flow using only
the keyboard" is a story the web catalog never has to write.
- Window management. Multiple windows, tabs, full screen, restoring size and
position, what happens when the last window closes.
- Launch and first run. Cold launch, no saved state, permission prompts,
onboarding.
- Permissions. Anything triggering a system prompt — files, network, camera,
accessibility, notifications. Each needs a granted story and a denied story.
- System integration. Drag and drop, share sheet, services menu, URL scheme
handling, dock menu, notifications, background activity.
- Offline and sleep. What the app does with no network, and after the
machine wakes.
- Appearance. Light and dark mode, accent colour, Increase Contrast,
Reduce Motion, and larger text sizes.
Story wording
Write steps in native vocabulary. Not "navigate to /settings" but "open Settings
from the gear in the sidebar, or press ⌘,". A step must name something a walker
can find in the accessibility tree — a visible label, a menu item, or a
shortcut.
Each story should carry, in addition to the inherited fields:
- Entry — how the user gets here: launch, a menu item, a shortcut, a click path
- Keyboard path — the same journey without a mouse, or "not possible" if it isn't
- Window state — which window or sheet the story happens in
The Ideal path field matters more here than on the web: a desktop app that
takes six clicks for something the menu bar could do in one keystroke is exactly
the friction /ux-flow-native is looking for.
Topics for the swarm
Use the inherited topic list, plus these native-only ones:
- Menu bar and keyboard-only operation
- First launch and permission prompts
- Window and multi-window behaviour
- Appearance and accessibility settings (dark mode, contrast, larger text)
- System integration (drag and drop, share, notifications, URL schemes)
- Offline, sleep, and long-running background work
What to leave out
Skip topics that do not exist here rather than inventing native analogues:
- Responsive breakpoints — a Mac window resizes continuously. Replace with a
"works in a small window" story.
- Browser back/forward, deep links to arbitrary state, SEO, page load
performance.
- Multi-tab and multi-session-in-one-app stories, unless the app really has
document windows or tabs.
Output
Identical structure to /ux-paths: docs/ux-paths/discovery.md,
per-topic files, and docs/ux-paths/catalog.md.
Add to discovery.md a Platform Surface section listing the menu bar
commands, the keyboard shortcuts, the permissions the app requests, and the
window model. /ux-walker-native reads this to audit shortcut correctness and
keyboard reachability.
1---2name: ux-paths-native3description: Generate exhaustive user journey stories for a native macOS/iOS app by analyzing its codebase. Produces short feature exercises and long end-to-end flows written in terms of windows, panes, menus, sheets and keyboard shortcuts, ready for /ux-walker-native. Use when asked to 'map the native app', 'create stories for the mac app', 'generate ux paths for the desktop app', or 'run ux-paths-native'. For web apps use ux-paths instead.4---56# UX Paths (native macOS/iOS)78Generate a catalog of realistic user journeys through a native app by reading its9code. Output feeds `/ux-walker-native`.1011This is the sibling of `/ux-paths`. The method is the same — discovery agent,12story swarm, consolidation — and the **process, output format, and story schema13are inherited unchanged**. Read `../ux-paths/SKILL.md` and follow14it, applying the substitutions below.1516Do not duplicate that skill's phases here. This file only records what changes17for a native target.1819---2021## What changes2223### Discovery: where the app's surface actually lives2425A web discovery agent looks for routes. A native app has no router. Look for:2627| Web concept | Look for in a native app |28|---|---|29| Routes / pages | `WindowGroup`, `Settings`, `NavigationStack`, `NavigationSplitView`, `.sheet`, `.popover`, `.alert`, `TabView`, Storyboard scenes, `NSViewController` subclasses |30| Nav bar / sidebar | `List` in a sidebar column, `NavigationLink`, `Sidebar` toolbar items, `TabView` |31| Buttons and forms | `Button`, `TextField`, `Toggle`, `Picker`, `Stepper`, `Slider`, `Form`, `@FocusState` |32| Client-side state | `@State`, `@Observable`, `@AppStorage`, `@SceneStorage`, `UserDefaults`, `NSUbiquitousKeyValueStore` |33| API layer | `URLSession` clients, XPC services, a bundled local server, CLI subprocesses the app spawns |34| Auth | Keychain access, `ASWebAuthenticationSession`, OAuth token stores, subscription receipts |35| Feature flags | Build configuration, `#if DEBUG`, launch arguments, environment variables the app reads |3637**Also enumerate — these have no web equivalent and are where native apps fail:**3839- **Menu bar commands.** Every `CommandGroup`, `CommandMenu`, and `.keyboardShortcut`.40 Each menu item is a user-reachable capability and belongs in the story catalog.41- **Keyboard shortcuts.** Collect the full list. "Complete this flow using only42 the keyboard" is a story the web catalog never has to write.43- **Window management.** Multiple windows, tabs, full screen, restoring size and44 position, what happens when the last window closes.45- **Launch and first run.** Cold launch, no saved state, permission prompts,46 onboarding.47- **Permissions.** Anything triggering a system prompt — files, network, camera,48 accessibility, notifications. Each needs a granted story and a denied story.49- **System integration.** Drag and drop, share sheet, services menu, URL scheme50 handling, dock menu, notifications, background activity.51- **Offline and sleep.** What the app does with no network, and after the52 machine wakes.53- **Appearance.** Light and dark mode, accent colour, Increase Contrast,54 Reduce Motion, and larger text sizes.5556### Story wording5758Write steps in native vocabulary. Not "navigate to /settings" but "open Settings59from the gear in the sidebar, or press ⌘,". A step must name something a walker60can find in the accessibility tree — a visible label, a menu item, or a61shortcut.6263Each story should carry, in addition to the inherited fields:6465- **Entry** — how the user gets here: launch, a menu item, a shortcut, a click path66- **Keyboard path** — the same journey without a mouse, or "not possible" if it isn't67- **Window state** — which window or sheet the story happens in6869The **Ideal path** field matters more here than on the web: a desktop app that70takes six clicks for something the menu bar could do in one keystroke is exactly71the friction `/ux-flow-native` is looking for.7273### Topics for the swarm7475Use the inherited topic list, plus these native-only ones:7677- Menu bar and keyboard-only operation78- First launch and permission prompts79- Window and multi-window behaviour80- Appearance and accessibility settings (dark mode, contrast, larger text)81- System integration (drag and drop, share, notifications, URL schemes)82- Offline, sleep, and long-running background work8384### What to leave out8586Skip topics that do not exist here rather than inventing native analogues:8788- Responsive breakpoints — a Mac window resizes continuously. Replace with a89 "works in a small window" story.90- Browser back/forward, deep links to arbitrary state, SEO, page load91 performance.92- Multi-tab and multi-session-in-one-app stories, unless the app really has93 document windows or tabs.9495---9697## Output9899Identical structure to `/ux-paths`: `docs/ux-paths/discovery.md`,100per-topic files, and `docs/ux-paths/catalog.md`.101102Add to `discovery.md` a **Platform Surface** section listing the menu bar103commands, the keyboard shortcuts, the permissions the app requests, and the104window model. `/ux-walker-native` reads this to audit shortcut correctness and105keyboard reachability.
dennisonbertram