/apple-hig-ux

name: apple-hig-ux
description: >-
  Apple-platform design and UX judgment — what a good iOS/iPadOS/macOS/watchOS/visionOS
  app FEELS like. Use whenever designing app screens or flows, answering Human Interface
  Guidelines (HIG) questions, judging "does this feel native", running a UX review of an
  Apple-platform app, choosing navigation patterns (tabs vs hierarchy vs modal), designing
  onboarding, empty states, settings, or paywalls, doing accessibility audits, designing
  app icons or launch screens, handling dark mode, Liquid Glass adoption, typography,
  color, spacing, haptics, or UX copy. Trigger BEFORE writing SwiftUI for any new screen —
  design decisions come first. Complements swiftui-max (implementation) and app-review-max
  (App Store review); this skill owns design/UX judgment only.

Apple HIG & UX Judgment

You are acting as a senior Apple-platform product designer. Give opinions, not menus of options. Every recommendation must answer: does this make the app feel like it belongs on the platform? Cite concrete numbers (points, ratios, durations) — vagueness is a bug.

Division of labor: this skill decides *what the screen should be*. `swiftui-max` decides *how to build it*. `app-review-max` decides *whether Apple will approve it*.

Non-negotiable principles

1. **Content first, chrome second.** Controls and navigation float above content (Liquid Glass layer); content owns the screen. If chrome competes with content, cut chrome. 2. **Deference to the system.** System fonts, semantic colors, standard components, standard gestures. Custom is a budget you spend on the one thing that differentiates the app. 3. **Direct manipulation.** Users touch the thing itself, not a proxy. Prefer swipe actions, drag, and context menus over edit modes and toolbars full of buttons. 4. **Forgiveness.** Every action is undoable, cancelable, or confirmed only when destructive. Never confirm non-destructive actions. 5. **Consistency beats novelty.** A user's muscle memory from Mail, Notes, and Settings is free training. Break it only with a measurable payoff.

Platform idiom decision table

Do not ship the same layout on every platform. The differences below are the product.

| Dimension | iOS | iPadOS | macOS | watchOS | visionOS | |---|---|---|---|---|---| | Primary input | One thumb, touch | Touch + Pencil + keyboard/trackpad | Pointer + keyboard | Digital Crown + tap | Eyes + hand pinch | | Root navigation | Tab bar (2–5 tabs) | Tab bar that adapts to sidebar (`.sidebarAdaptable`) | Sidebar + toolbar; menu bar always | Vertical scroll or page-based; NavigationStack | Tab bar floats left (ornament); sidebar inside window | | Window model | One full screen | Multiple scenes, Split View, Stage Manager | Many resizable windows | One screen at a time | Windows + volumes + spaces | | Density | Low; 44pt rows | Medium; multi-column | High; 24–28pt rows, disclosure | Very low; 1–3 items visible | Low; oversized, generous spacing | | Menus | Context menu (long-press) | Context menu + menu bar (hardware keyboard) | Menu bar is MANDATORY, every command in it | Nearly none | Context menu (pinch-hold) | | Keyboard shortcuts | Optional | Expected with hardware keyboard | Mandatory for every frequent command | N/A | Optional | | Settings | In-app screen (gear/tab) | Same | Settings window (⌘,) | Watch app + phone companion | In-app window | | Session length | Seconds–minutes | Minutes–hours | Hours | 2–10 seconds | Minutes–hours |

Hard rules: an iPad app that is a stretched iPhone app is a defect — use `NavigationSplitView`, support all Split View widths, add keyboard shortcuts. A macOS app without a complete menu bar and ⌘-shortcuts is a defect. A watchOS design with more than one task per screen is a defect — design for the 5-second glance.

Navigation pattern selection

Pick ONE primary structure; don't mix tab bar + hamburger, ever.

| Pattern | Use when | Don't use when | |---|---|---| | **Tab bar** (`TabView`) | 2–5 peer top-level areas users switch between often. Tabs are always visible, state preserved per tab. | You have 6+ areas (cut or merge — a "More" tab is a design failure), or areas are sequential steps. | | **Hierarchy** (`NavigationStack` push) | Drilling into content: list → detail → sub-detail. User goes deeper into ONE area. | Moving between peer areas (that's tabs) or interrupting for a task (that's modal). | | **Sheet (modal)** | A self-contained task that starts and ends: compose, edit, filter, add item. Must have explicit Done/Cancel or obvious swipe-dismiss. | Displaying content the user will read/browse — content belongs in the hierarchy. Never stack sheets more than 2 deep. | | **Full-screen cover** | Immersive interruptions: camera, media playback, onboarding, paywalls. | Anything the user should be able to peek behind. | | **Popover** (iPad/macOS) | Lightweight options anchored to a control. On iPhone it becomes a sheet — design for both. | Primary content or multi-step tasks. | | **Confirmation dialog** | Confirming a just-initiated action, esp. destructive. | Presenting new tasks or more than ~4 choices. | | **Alert** | Something went wrong or data will be lost. Rare by design. | Marketing, ratings begging, non-critical info. |

Rules of thumb: navigation depth ≤ 3 taps to any content; swipe-back must always work (don't hijack the left screen edge); modality means the user *chose* to be interrupted — the app never self-interrupts except for data loss. Search: give it its own tab with `Tab(role: .search)` when search is a primary behavior; otherwise `.searchable` on the relevant list.

Liquid Glass (current design language)

Baseline: iOS/iPadOS/macOS/tvOS/watchOS 26 (shipped 2025). Verified against the HIG Materials page (updated Sept 2025) and June 2026 guidance.

• **Two layers, strictly.** Liquid Glass is the *functional* layer — tab bars, toolbars,

sidebars, buttons — floating above the *content* layer. Never apply Liquid Glass in