Apple iOS HIG Best Practices

Comprehensive guide for Apple Human Interface Guidelines compliance in iOS apps built with SwiftUI. Contains 34 rules across 6 categories covering navigation, interaction design, accessibility, user feedback, UX patterns, and visual design.

Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

• Feature modules import

  Domain

  +

  DesignSystem

  only (never

  Data

  , never sibling features)
• App target is the convergence point and owns

  DependencyContainer

  , concrete coordinators, and Route Shell wiring

• Domain

  stays pure Swift and defines models plus repository,

  *Coordinating

  ,

  ErrorRouting

  , and

  AppError

  contracts

• Data

  owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
• Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
• ViewModels call repository protocols directly (no default use-case/interactor layer)

When to Apply

Reference these guidelines when:

• Building navigation hierarchies with tab bars, NavigationStack, or split views
• Designing touch interactions, gestures, and haptic feedback
• Ensuring accessibility with VoiceOver, Dynamic Type, and color contrast
• Implementing loading states, error handling, and empty states
• Building onboarding flows, permission requests, and confirmation dialogs
• Supporting dark mode, SF Symbols, and standard layout margins
• Reviewing apps for HIG compliance

Rule Categories by Priority

nav-

inter-

acc-

feed-

ux-

vis-

Quick Reference

1. Navigation (CRITICAL)

• nav-tab-bar

  - Design tab bars for top-level navigation

• nav-navigation-stack

  - Use NavigationStack for hierarchical navigation

• nav-toolbar-placement

  - Place actions in toolbars using standard placements

2. Interaction Design (CRITICAL)

• inter-touch-targets

  - Maintain 44pt minimum touch targets

• inter-gesture-patterns

  - Use standard gesture patterns

• inter-haptic-feedback

  - Add haptic feedback for meaningful events

• inter-keyboard-handling

  - Handle keyboard appearance gracefully

• inter-drag-drop

  - Support drag and drop for content transfer

• inter-pull-to-refresh

  - Support pull to refresh for lists

• inter-swipe-actions

  - Add swipe actions for contextual operations

• inter-list-search

  - Use searchable for built-in search

3. Accessibility (CRITICAL)

• acc-labels

  - Provide meaningful accessibility labels

• acc-dynamic-type

  - Support Dynamic Type for all text

• acc-color-contrast

  - Maintain sufficient color contrast

• acc-reduce-motion

  - Respect reduce motion preference

• acc-color-independent

  - Never rely on color alone

• acc-focus-management

  - Manage focus for assistive technologies

• acc-scaled-metric

  - Use ScaledMetric for adaptive sizing

• acc-view-that-fits

  - Use ViewThatFits for adaptive layouts

4. User Feedback (HIGH)

• feed-loading-states

  - Show appropriate loading indicators

• feed-error-states

  - Handle errors with clear recovery actions

• feed-notifications

  - Use notifications judiciously

• feed-success-confirmation

  - Confirm successful actions appropriately

• feed-empty-states

  - Design helpful empty states

5. UX Patterns (HIGH)

• ux-onboarding

  - Design minimal onboarding

• ux-permissions

  - Request permissions in context

• ux-modality

  - Use modality appropriately

• ux-confirmation-dialog

  - Use confirmation dialogs for destructive actions

• ux-data-entry

  - Minimize data entry friction

• ux-undo

  - Support undo for destructive actions

• ux-settings

  - Organize settings logically

6. Visual Design (HIGH)

• vis-dark-mode

  - Support dark mode with semantic colors

• vis-sf-symbols

  - Use SF Symbols with correct rendering mode and weight

• vis-layout-margins

  - Use standard layout margins and safe areas

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files