Apple HIG SwiftUI iOS 17+ Best Practices

A principal designer's lens for evaluating and refactoring SwiftUI interfaces to Apple-quality standards. Contains 48 rules across 8 categories, ordered by the visual review process a senior Apple designer follows when auditing an app. Each rule identifies a specific anti-pattern, explains why it degrades the experience, and provides the iOS 17+ fix while respecting the app's brand voice.

Scope & Relationship to Sibling Skills

This skill is the refactoring and review lens — it evaluates existing UI and identifies visual anti-patterns to fix. When loaded alongside ios-design (building new UI), ios-hig (HIG compliance), or swift-refactor (code-level refactoring), this skill supersedes overlapping rules with more detailed "incorrect → correct" transformations and "When NOT to apply" guidance. Use this skill for auditing and improving existing screens; use the siblings for greenfield implementation.

When to Apply

Reference these guidelines when:

• Reviewing existing SwiftUI screens for visual quality issues
• Auditing typography scale, weight usage, and type treatments
• Evaluating color system coherence across light and dark mode
• Refactoring animations from legacy easeInOut to spring-based motion
• Fixing navigation transitions that break spatial continuity
• Replacing custom overlays with Apple's materials system
• Standardizing spacing, touch targets, and corner radii
• Adopting iOS 17-18 APIs like scrollTransition, PhaseAnimator, or MeshGradient

Rule Categories by Priority

Quick Reference

1. Visual Hierarchy (CRITICAL)

• hier-single-focal - One primary focal point per screen
• hier-size-weight-contrast - Combine size, weight, and contrast for hierarchy
• hier-progressive-disclosure - Use progressive disclosure for dense information
• hier-card-modularity - Use self-contained cards for dashboard layouts
• hier-whitespace-grouping - Use whitespace to separate conceptual groups
• hier-reading-order - Align visual weight with logical reading order

2. Typography Discipline (CRITICAL)

• typo-system-text-styles - Use Apple text styles, never fixed font sizes
• typo-weight-not-caps - Use weight for emphasis, not ALL CAPS
• typo-single-typeface - One typeface per app, differentiate with weight and size
• typo-max-styles-per-screen - Limit to 3-4 distinct type treatments per screen
• typo-no-light-body - Avoid light font weights for body text
• typo-foreground-style - Use foregroundStyle over foregroundColor

3. Color System (CRITICAL)

• color-semantic-always - Use semantic colors, never hard-coded black or white
• color-role-naming - Name custom colors by role, not hue
• color-contrast-aa - Ensure WCAG AA contrast ratios
• color-saturated-small - Reserve saturated colors for small interactive elements
• color-dark-mode-pairs - Define light and dark variants for every custom color
• color-brand-within-system - Map brand palette onto iOS semantic color roles
• color-one-purpose - Each semantic color serves exactly one purpose

4. Motion & Animation (HIGH)

• motion-spring-default - Default to spring animations for all UI transitions
• motion-spring-presets - Use .smooth for routine, .snappy for interactive, .bouncy for delight
• motion-no-linear-easeInOut - Prefer springs over linear and easeInOut for UI elements
• motion-symbol-effects - Use built-in symbolEffect, not manual symbol animation
• motion-content-transition - Use contentTransition for changing text and numbers
• motion-reduce-motion - Always provide reduce motion fallback
• motion-purposeful - Every animation must communicate state change or provide feedback

5. Screen Transitions (HIGH)

• trans-zoom-collections - Use zoom transitions for collection-to-detail navigation
• trans-sheet-vs-push - Sheets for tasks and creation, push for drill-down hierarchy
• trans-multi-detent-sheets - Provide multiple sheet detents with drag indicator
• trans-matched-geometry - Use matchedGeometryEffect for contextual origin transitions
• trans-no-hard-cuts - Always animate between states, even minimally
• trans-preserve-swipe-back - Never break the system back-swipe gesture

6. Materials & Depth (HIGH)

• depth-materials-not-opacity - Use system materials, not custom semi-transparent backgrounds
• depth-vibrancy-hierarchy - Match vibrancy level to content importance
• depth-material-thickness - Choose material thickness by contrast needs
• depth-background-interaction - Enable background interaction for peek-style sheets
• depth-shadow-vs-material - Use materials for layering, not drop shadows for depth

7. Spacing & Rhythm (MEDIUM-HIGH)

• rhythm-consistent-grid - Use a 4pt base unit for all spacing
• rhythm-touch-targets - All interactive elements at least 44x44 points
• rhythm-consistent-radii - Standardize corner radii per component type
• rhythm-consistent-padding - Use consistent padding across all screens
• rhythm-alignment-consistency - Consistent alignment per content type within a screen
• rhythm-safe-area-respect - Always respect safe areas

8. iOS 17+ Modernization (MEDIUM)

• modern-scroll-transitions - Use scrollTransition for scroll-position visual effects
• modern-phase-animator - Use PhaseAnimator for multi-step animation sequences
• modern-mesh-gradients - Use MeshGradient for premium dynamic backgrounds
• modern-text-renderer - Use TextRenderer for hero text animations only
• modern-inspector - Use inspector for trailing-edge detail panels

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