---
name: hig-patterns
description: "Apple HIG interaction patterns mapped to SwiftUI: onboarding, permission requests, loading, empty and error states, modality, search, settings. Use when designing a UX flow on an Apple platform."
metadata:
  risk: safe
  source: multi-agent-pipeline
  date_added: "2026-09-25"
---

# HIG Patterns

A pattern is a recurring answer to a recurring flow question: how do people get
started, how do they wait, how do they leave a task, how do they recover from a
mistake. Apple's own apps answer these consistently, and people carry those
expectations into yours. This skill lists the questions, the expected answer,
and how to express it in SwiftUI.

## Flow questions to settle first

Before drawing screens, answer these for the flow under review:

- Where does it start, and what does the person already know at that point?
- Which step can they abandon, and what happens to their input if they do?
- What do they see while the app is working?
- What do they see when there is nothing to show, or when something fails?
- How do they undo the last thing they did?

Each maps to a pattern in `references/patterns.md`.

## Details on demand

- `references/onboarding-and-states.md`: onboarding rules, TipKit versus an
  up-front flow, when and how to ask for permission, the HIG rules for a
  pre-permission screen (one button that opens the alert), and empty, error
  and loading states with `ContentUnavailableView`.
- `references/patterns.md`: feedback, undo, search, data entry, settings,
  sharing, accounts and notifications.

## First launch and access in one glance

- Onboarding is optional, short and interactive; context tips beat a carousel.
- Ask for access when the feature is first used, not at launch, unless the app
  cannot work without it.
- A pre-permission screen has one button ("Continue", never "Allow") that
  opens the system alert, and no way around it.
- Empty states say what would be here and offer the next step; errors say
  what happened and offer Retry while keeping input.

## Choosing how to present a task

| Situation | Treatment | SwiftUI |
|-----------|-----------|---------|
| Moving deeper into a hierarchy | Push | `NavigationLink(value:)` + `.navigationDestination` |
| Self-contained task with its own done or cancel | Sheet | `.sheet(item:)` with `.presentationDetents` |
| Task that needs the whole screen and focus | Full screen | `.fullScreenCover` |
| Must acknowledge or decide before continuing | Alert | `.alert(_:isPresented:actions:message:)` |
| Choosing among actions for the current item | Confirmation dialog | `.confirmationDialog` |
| Quick, dismissible supplemental info | Popover or inline | `.popover`, inline disclosure |

Rules of thumb:

- A sheet should have a clear way out: Cancel on the leading side, the
  confirming action on the trailing side. Protect unsaved input with
  `.interactiveDismissDisabled(hasChanges)` and a discard confirmation.
- Avoid stacking modals. If a sheet opens another sheet, reconsider the flow.
- Alerts are interruptions; use them for consequences, not for success.

## Review output

Name the flow step, the expected pattern, what the build does instead, and the
change:

```
[Modality] Editing a product opens a full screen cover with no Cancel.
Expected: sheet with Cancel and Save; discard confirmation when edited.
```

## Related skills

- `hig-components-content`, `hig-components-system` for the parts of each pattern.
- `swiftui-navigation` for push, sheet and deep link implementation.
- `tipkit` for in-context tips that replace up-front onboarding pages.
- `ios-haptics` for confirming success or failure with haptics.

## References

- https://developer.apple.com/design/human-interface-guidelines/patterns
- https://developer.apple.com/design/human-interface-guidelines/onboarding
- https://developer.apple.com/design/human-interface-guidelines/launching
- https://developer.apple.com/design/human-interface-guidelines/loading
- https://developer.apple.com/design/human-interface-guidelines/modality
- https://developer.apple.com/design/human-interface-guidelines/feedback
- https://developer.apple.com/design/human-interface-guidelines/undo-and-redo
- https://developer.apple.com/design/human-interface-guidelines/searching
- https://developer.apple.com/design/human-interface-guidelines/entering-data
- https://developer.apple.com/design/human-interface-guidelines/settings
- https://developer.apple.com/design/human-interface-guidelines/drag-and-drop
- https://developer.apple.com/design/human-interface-guidelines/managing-accounts
- https://developer.apple.com/design/human-interface-guidelines/managing-notifications