Agent Skills: Apple iOS HIG Best Practices

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 |