ios-hig

name	ios-hig
description	Apple Human Interface Guidelines for iOS and iPadOS. Load for iOS or iPadOS design tasks.

Detection Signals

Load this skill when any of the following are present:

Signal	Location
iOS target in cross-platform project	React Native, Flutter, or pubspec.yaml with iOS support
Native iOS/iPadOS project	.xcodeproj, .xcworkspace, Info.plist, Swift source files
SwiftUI or UIKit usage	import SwiftUI, import UIKit in source files
Design task for iOS	User mentions "iOS design", "HIG", "Apple guidelines", or "SwiftUI design"

---

Core Principle — Feel Native

iOS users expect apps to feel like a natural extension of the operating system. Deviation from platform patterns — even aesthetically — creates friction. When in doubt, prefer the native pattern over a custom one.

---

Navigation Patterns

Choose the navigation model that matches the information architecture. Never mix models without a clear reason.

Tab Bar

• Use for 3–5 top-level destinations that are peers (no hierarchy between them)
• Tabs are always visible and always accessible — never hide or disable individual tabs
• Icons: use SF Symbols; active tab uses filled variant + tint color; inactive uses outlined variant + secondaryLabel color
• Tab bar height: 49pt (83pt with home indicator safe area on notched devices)
• Labels: short (1–2 words max); truncate with … only as a last resort

Navigation Stack (Push)

• Use for hierarchical content — each level drills deeper into detail
• Back button appears automatically; never replace it with a custom "Back" label unless the destination title is ambiguous
• Navigation bar title: use .large style at the root level, .inline for deeper levels
• Never push more than 3–4 levels without a shortcut back to root (e.g., long-press back button)

Modal Presentation

Style	Usage
Sheet (.sheet)	Lightweight tasks that don't require full context switch
Full-screen cover (.fullScreenCover)	Immersive tasks (camera, onboarding, video); user cannot swipe to dismiss
Popover (iPad)	Contextual information anchored to a control; auto-adapts to sheet on iPhone

• Sheets support pull-to-dismiss by default — preserve this behavior; only disable when unsaved data is at risk (show a confirmation action sheet instead)
• Never present a sheet from within a sheet — use navigation push instead
• Full-screen covers must always provide an explicit dismiss control (button or gesture)

Split View (iPad)

• Use NavigationSplitView for two- or three-column layouts on iPad
• Sidebar (first column): persistent navigation; list of sections or categories
• Content (second column): list or index within a section
• Detail (third column): full detail view
• Collapse gracefully to a single-column navigation stack on iPhone and compact-width iPad

---

Controls

SF Symbols

• Always prefer SF Symbols over custom icons — they scale with Dynamic Type, support weight variants, and adapt to Dark Mode automatically
• Match symbol weight to the surrounding text weight: regular text → regular symbol
• Use filled variants for selected/active states; outlined for inactive
• Symbols used as interactive controls must have an accessibility label
• Custom symbols must follow the SF Symbols grid and optical alignment — use the SF Symbols app to verify

Buttons

Style	Usage
Filled (.borderedProminent)	Primary action; one per screen
Tinted (.bordered with tint)	Secondary action; safe to use multiple times
Gray (.bordered)	Tertiary or neutral actions
Plain (.plain)	Low-emphasis, inline, or destructive actions

• Minimum touch target: 44×44pt — use .contentShape(Rectangle()) to expand hit area without changing visual size
• Destructive actions must use .destructive role — renders in red and triggers a confirmation if needed
• Button labels: verb phrases ("Save Changes", "Delete Account") — never noun-only labels ("OK")

Toggles and Pickers

• Toggle (Switch): for immediate binary settings — changes apply instantly without a "Save" button
• Picker: use .segmented style for 2–4 mutually exclusive short options; use .menu style for longer lists
• Stepper: for incrementing/decrementing numeric values within a known range
• Slider: for continuous values where precision is less critical than range exploration
• DatePicker: always use the system date picker — never build a custom one

Text Input

• TextField: single-line; set keyboardType, textContentType, and autocorrectionDisabled appropriately
• SecureField: for passwords — never use TextField for passwords
• TextEditor: multi-line; add a character count label when there is a limit
• Always dismiss the keyboard when the user taps outside the field (onTapGesture on the background)
• Return key label should match the action: "Done", "Search", "Send", "Next"

---

Typography — SF Pro

Apple's system font family is SF Pro (iOS/macOS) and SF Pro Rounded (friendly contexts). Use it via Dynamic Type — never specify a fixed font size.

Dynamic Type Scales

Style	Default Size	Usage
largeTitle	34pt	Hero page titles (used sparingly)
title1	28pt	Primary screen headings
title2	22pt	Secondary headings
title3	20pt	Tertiary headings
headline	17pt semibold	List row primaries, emphasized labels
body	17pt	Primary body text
callout	16pt	Secondary body, sidebars
subheadline	15pt	Supporting labels
footnote	13pt	Secondary descriptions, timestamps
caption1	12pt	Image captions, form helper text
caption2	11pt	Smallest visible labels

Rules:

• Always use .font(.body), .font(.headline), etc. — never Font.system(size: 17)
• Support Accessibility text sizes (up to ~310% of default) — test with "Larger Text" in Accessibility settings
• When Accessibility sizes are enabled, consider moving labels to a vertical stack using @ScaledMetric or ViewThatFits
• Minimum: caption2 (11pt) — never use sizes below this

---

Layout

Safe Area

• Never place interactive content or critical text outside the safe area — it will be obscured by notch, Dynamic Island, or home indicator
• Use .safeAreaInset() (SwiftUI) or safeAreaLayoutGuide (UIKit) — never hard-code pixel offsets
• Bottom content (buttons, tab bars): account for the home indicator (34pt on notched devices)

Spacing and Margins

• Standard content margin: 16pt from screen edges (20pt on Plus/Max models)
• Group related content with consistent spacing; use the 8pt grid as the base unit
• List rows: minimum 44pt height for tappable rows
• Section headers: listRowInsets preserves the standard left inset unless deliberately removed

Grids and Collections

• Use LazyVGrid / LazyHGrid (SwiftUI) or UICollectionViewCompositionalLayout (UIKit) for grid layouts — never manual frame placement
• Item spacing: 8pt default; increase to 16pt for card-style items
• Always account for variable row heights — never assume fixed item height in a collection

---

Dark Mode

iOS automatically switches between light and dark appearances. Designs must support both.

Color Usage

• Always use semantic system colors — they adapt automatically: .primary, .secondary, .background, .secondaryBackground, .grouped Background, .separator, .label, .secondaryLabel
• Custom colors must define both light and dark variants in the Asset Catalog (Appearances: Any, Dark)
• Never hard-code Color.white for backgrounds or Color.black for text — use semantic equivalents

Images and Icons

• SF Symbols adapt automatically — no extra work needed
• Custom images: provide light and dark variants in the Asset Catalog when they differ
• Avoid images with embedded text — they do not adapt to Dark Mode

Elevation and Depth

• iOS does not use colored tonal elevation like Material — use shadows, blur (.background(.ultraThinMaterial)), or grouping to separate layers
• Materials (ultraThinMaterial, thinMaterial, regularMaterial, thickMaterial, ultraThickMaterial) adapt to both appearances automatically

---

Accessibility

VoiceOver

• Every interactive element must have an accessibilityLabel (what it is) and, when needed, an accessibilityHint (what happens when activated)
• Decorative images: mark as .accessibilityHidden(true)
• Custom controls: implement accessibilityValue for current state and accessibilityAdjustableAction for sliders/pickers
• Test all key flows with VoiceOver enabled before release

Reduce Motion

• Respect the Reduce Motion accessibility setting — replace all non-essential animations with simple crossfades or instant transitions
• In SwiftUI: @Environment(\.accessibilityReduceMotion) var reduceMotion
• Never use motion to convey meaning that cannot be understood without it

Increase Contrast

• Respect the Increase Contrast setting — borders and separators become more prominent automatically with system colors; custom colors must provide high-contrast variants
• In SwiftUI: @Environment(\.accessibilityDifferentiateWithoutColor) and @Environment(\.colorSchemeContrast)

Touch Targets

• Minimum: 44×44pt for all tappable elements
• For small visual elements (icons, toggles), expand the hit area with padding or .contentShape(Rectangle())

---

iPhone vs iPad Adaptations

The same app must adapt its layout based on the available space — not serve a different design.

Aspect	iPhone (Compact)	iPad (Regular)
Navigation	Tab Bar + Navigation Stack	Split View or Tab Bar
Modals	Full-width sheets	Popovers, centered sheets
Content columns	Single column	Two or three columns
Keyboard	Full-screen, pushes content	Floating or docked; content shifts
Pointer (iPadOS)	N/A	Support hover effects (.hoverEffect())

• Use @Environment(\.horizontalSizeClass) to branch layout — compact = iPhone / iPad portrait in some cases; regular = iPad landscape and most iPad orientations
• Never detect device model (UIDevice.current.userInterfaceIdiom) to branch layout — use size class; it handles Split View and Stage Manager correctly
• Test on iPad with Stage Manager enabled — the app may appear in various window sizes

---

Platform Conventions to Never Break

These behaviors are deeply ingrained in iOS users. Deviating causes immediate friction:

• Pull-to-refresh: always supported in scrollable lists that show server data
• Swipe-to-delete: always supported in editable lists (onDelete in SwiftUI)
• Long-press context menu: offer contextual actions on tappable items (.contextMenu)
• Back swipe: never disable edge-swipe-to-go-back; it is a core navigation gesture
• Scroll-to-top: tapping the status bar scrolls the active scroll view to the top — do not break this
• Share sheet: use UIActivityViewController / ShareLink — never build a custom share UI
• System alerts: use UIAlertController / .alert() for OS-level confirmations — never custom modal dialogs for destructive actions