UX Flow Audit

UX issues are not polish — they're defects that cause support tickets, bad reviews, and user churn.

Axiom's code-level auditors check patterns. This skill checks what users actually experience: Can they complete their task? Can they get back? Do they know what's happening?

6 iOS UX Principles (Detection Anchors)

These principles anchor every detection category. When a principle is violated, users get stuck, confused, or frustrated.

1. Honor the Promise

What the button/title says must match what the user gets. A "Settings" button that opens a profile page breaks trust.

2. Escape Hatch

Every modal (sheet, fullScreenCover, alert) must have a way out. A sheet without a dismiss button or drag-to-dismiss traps users.

3. Primary Action Visibility

The main thing users came to do must be immediately visible and tappable. If the CTA requires scrolling or menu-diving, users won't find it.

4. Dead End Prevention

Every view must have a forward path (next step) or a completion state (success message, return to start). A view with no actions and no navigation is a dead end.

5. Progressive Disclosure

Don't overwhelm on first screen. Show essentials first, details on demand. An onboarding flow that dumps 12 settings on page one loses users.

6. Feedback Loop

Users must know what's happening during async operations. No loading state = "is it broken?" No error state = "what went wrong?" No empty state = "is this feature missing?"

Detection Categories

8 Core Defects (always check — these are UX bugs, not opinions):

1. Dead-End Views (CRITICAL)
2. Dismiss Traps (CRITICAL)
3. Buried CTAs (HIGH)
4. Promise-Scope Mismatch (HIGH)
5. Deep Link Dead Ends (HIGH)
6. Missing Empty States (HIGH)
7. Missing Loading/Error States (HIGH)
8. Accessibility Dead Ends (HIGH)

3 Contextual Checks (check when product context warrants — these involve design judgment):

9. Onboarding Gaps (MEDIUM) — requires knowing the product's onboarding strategy
10. Broken Data Paths (MEDIUM) — overlaps with code correctness; include only when UX-visible
11. Platform Parity Gaps (MEDIUM) — depends on target device strategy

Core defects are always worth reporting. Contextual checks require product knowledge — flag them if they look wrong, but acknowledge they may be intentional decisions.

1. Dead-End Views (CRITICAL)

Views with no navigation forward, no actions, and no completion state.

Detect:

• SwiftUI: Views with no

  NavigationLink

  ,

  Button

  ,

  .sheet

  ,

  .fullScreenCover

  ,

  .navigationDestination

  , or dismiss action
• UIKit: View controllers with no

  IBAction

  , no

  addTarget

  , no navigation push/present calls, no

  UIBarButtonItem

• Check for views/VCs that are navigation destinations but offer no way to proceed or return

Common cause: Placeholder views during development that ship to production.

2. Dismiss Traps (CRITICAL)

Sheets or fullScreenCover without a dismiss path.

Detect:

• SwiftUI:

  .fullScreenCover

  without

  @Environment(\.dismiss)

  or explicit dismiss button;

  .sheet

  with

  .interactiveDismissDisabled(true)

  without alternative dismiss; alert/confirmation dialogs missing cancel actions
• UIKit:

  present(_:animated:)

  with

  modalPresentationStyle = .fullScreen

  where presented VC has no dismiss/close button;

  isModalInPresentation = true

  without alternative dismiss path

Why critical: Users literally cannot leave the screen. The only escape is force-quitting the app.

3. Buried CTAs (HIGH)

Primary actions hidden below fold, in menus, or behind navigation.

Detect:

• Primary action buttons placed after long

  ScrollView

  content
• Important actions only in

  .toolbar

  overflow menu (

  .secondaryAction

  )
• CTAs inside expandable

  DisclosureGroup

  sections
• No prominent action on the main tab's root view

Not a buried CTA: Below-fold placement that is intentional — checkout confirmation ("review order then confirm"), terms acceptance ("read then agree"), or content that the user should see before acting. The test: is the below-fold placement serving the user (they need context first) or hurting them (they can't find the action)?

4. Promise-Scope Mismatch (HIGH)

NavigationTitle, button label, or tab name doesn't match the content.

Detect:

• .navigationTitle("X")

  where view content is clearly about Y

• NavigationLink("Settings")

  that navigates to a profile/account view
• Tab labels that don't match tab content
• Button text suggesting one action but performing another

5. Deep Link Dead Ends (HIGH)

URL opens but lands on empty or broken state.

Detect:

• .onOpenURL

  handlers that push a view without checking if data exists
• Deep link destinations that assume pre-loaded state
• Universal link handling that doesn't validate the entity ID
• No fallback when deep-linked content is unavailable

Cross-reference:

axiom-swiftui-nav

6. Missing Empty States (HIGH)

Lists, grids, or content views with no data show blank screen.

Detect:

• List

  or

  ForEach

  without

  if items.isEmpty { ... }

  or

  .overlay

  for empty state

• @Query

  results displayed without empty check
• Search results with no "no results" view
• Filtered views that can reach zero items

7. Missing Loading/Error States (HIGH)

Async operations with no feedback.

Detect:

• SwiftUI:

  .task { }

  or

  Task { }

  that fetches data without a loading indicator;

  try await

  without error presentation (no

  .alert

  , no error state variable); state enum missing

  .loading

  or

  .error

  cases
• UIKit:

  URLSession

  calls without

  UIActivityIndicatorView

  or progress UI; completion handlers that don't update UI on error; missing

  UIAlertController

  for failure cases
• Both: Network calls without timeout or retry UI
• Both:

  catch

  blocks that only

  print

  /log in

  #if DEBUG

  with no user-visible feedback — the user sees the operation silently fail

Focus on network/write operations: Skip loading indicators for fast local reads (GRDB queries, UserDefaults, cached data) that complete in under 100ms — adding spinners to these creates visual flicker. Focus on network calls, database writes, and any operation that can meaningfully fail.

Scan systematically: When you find a silent-error pattern in one file (e.g.,

catch { print(...) }

8. Accessibility Dead Ends (HIGH)

Actions only reachable via gestures or visual cues, invisible to assistive technology.

Detect:

• .onLongPressGesture

  /

  .swipeActions

  /

  DragGesture

  without

  .accessibilityAction

  equivalent
• Custom controls without

  .accessibilityLabel

  or

  .accessibilityHint

• Navigation that depends on color alone (e.g., "tap the green button")
• Pull-to-refresh (

  refreshable

  ) without VoiceOver-accessible alternative (note:

  refreshable

  is automatically accessible — check custom implementations)

Cross-reference:

axiom-accessibility-diag

9. Onboarding Gaps (MEDIUM)

First-launch flow that's incomplete or overwhelming.

Detect:

• No

  @AppStorage

  -gated onboarding check
• Onboarding flow without skip/later option
• More than 5 onboarding screens
• Onboarding that requires account creation before showing app value

10. Broken Data Paths (MEDIUM)

State/binding wiring issues that manifest as UX problems (view shows stale data, edits don't save, view appears empty when data exists).

Detect:

• Views accepting

  @Binding

  that are initialized with

  .constant()

  in non-preview code
• Views expecting

  @Environment

  values not provided by ancestors

• @Observable

  models created locally when they should be injected

• @State

  used where

  @Binding

  should propagate changes upward

Scope note: This overlaps with general SwiftUI correctness (

axiom-swiftui-debugging

11. Platform Parity Gaps (MEDIUM)

iPad sidebar missing, landscape broken, Mac Catalyst issues.

Detect:

• NavigationStack

  without

  NavigationSplitView

  alternative for iPad
• No

  .horizontalSizeClass

  checks for adaptive layout
• Views that break in landscape (fixed heights, no scroll)
• Missing keyboard shortcut support on iPad/Mac

Audit Process

Step 1: Map Entry Points

Find all ways users enter the app:

• @main

  App struct / SceneDelegate

• .onOpenURL

  handlers (deep links)
• Widget

  Link

  destinations
• Notification response handlers (

  UNUserNotificationCenterDelegate

  )
• Spotlight/Siri intent handlers

Step 2: Map Navigation Containers

Find all navigation structure:

• NavigationStack

  /

  NavigationSplitView

• TabView

  with tab structure

• .sheet

  /

  .fullScreenCover

  presentations
• Custom modal presentations

Step 3: Trace Flows

For each entry point → completion path:

1. Can the user reach their goal?
2. Can the user get back?
3. Does the user know what's happening at each step?

Step 4: Check Data Wiring

• Are

  @Binding

  vars actually passed from parent?
• Are

  @Observable

  objects injected via environment?
• Are

  @Query

  results handled for empty case?

Step 5: Check Platform Adaptivity

• iPad: Does sidebar/split view work?
• Landscape: Does layout adapt?
• Mac Catalyst/Designed for iPad: Do keyboard shortcuts exist?

Step 6: Check Accessibility Flows

• Can VoiceOver users complete every flow?
• Are gesture-only actions backed by accessibility actions?

Cross-Auditor Correlation

When findings overlap with other Axiom auditors, note the correlation and elevate severity:

.accessibilityAction

Output Format

Enhanced Rating Table (for CRITICAL and HIGH findings)

Urgency: Ship-blocker / Next release / Backlog Blast Radius: All users / Specific flow / Edge case Fix Effort: Time estimate for the fix ROI: Computed from urgency x blast radius / effort

Navigation Reachability Score

At end of audit, output:

## Navigation Reachability

- Total screens found: [N] (views with navigation presentation)
- Deep-linkable screens: [N] (.onOpenURL can reach them)
- Widget-reachable screens: [N] (widget Link destinations)
- Notification-reachable screens: [N] (notification handlers)
- Coverage: [N]% of screens are externally reachable

Fix Effort Reality Check

Most UX flow defects are fast fixes. When someone says "that's a big change," check this table:

dismiss()

if items.isEmpty { ContentUnavailableView(...) }

.secondaryAction

.primaryAction

@State var isLoading

.alert

.accessibilityAction

The cost of NOT fixing: A dismiss trap or dead end after payment generates 1-star reviews within hours of launch. Each review costs 10-20 positive reviews to offset. The 15-minute fix prevents weeks of damage control.

Anti-Rationalization

Resources

Skills: axiom-swiftui-nav, axiom-accessibility-diag, axiom-hig, axiom-swiftui-debugging

Agents: ux-flow-auditor (automated scanning), swiftui-nav-auditor (navigation architecture), accessibility-auditor (WCAG compliance)