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

Priority Category Impact Prefix

1 Navigation CRITICAL nav-

2 Interaction Design CRITICAL inter-

3 Accessibility CRITICAL acc-

4 User Feedback HIGH feed-

5 UX Patterns HIGH ux-

6 Visual Design HIGH 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

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules