ios-hig

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