expo-ios-hig

Expo iOS HIG Best Practices

Design rules for building iOS 26 apps in Expo (React Native) that feel genuinely native under Apple's Human Interface Guidelines. Contains 46 rules across 8 categories, prioritized by how much each decision affects native feel and HIG compliance. Every example is TSX/Expo — the decisions you make in React Native and TypeScript, not Swift.

The core idea: a React Native app feels native when it reaches for the platform — the system navigation controller, system controls, semantic colors, SF Symbols, real haptics, the system share sheet — instead of re-implementing iOS in JavaScript. These rules say which decision earns the native feel and which one quietly forfeits it.

When to Apply

Reference these guidelines when:

• Building or reviewing iOS screens, navigation, lists, or forms in an Expo app
• Choosing navigation: Expo Router native stack vs JS stack, native tabs, sheets, modals, large titles
• Picking controls: when to use the native Alert, ActionSheetIOS, date picker, Switch, SF Symbols, or drop to @expo/ui
• Styling for the platform: safe areas, dark mode, semantic colors, the iOS type scale, spacing, Liquid Glass
• Making interaction feel native: touch targets, press feedback, swipe actions, pull-to-refresh, gestures, haptics
• Adding motion, loading/empty states, accessibility, permissions, and launch polish

When NOT to Use This Skill

• The @expo/ui component API — for how to use @expo/ui/swift-ui components, Host boundaries, and modifiers, use the expo-ui skill. This skill says which decisions make an app native and points to @expo/ui when dropping to SwiftUI is the right call; it does not re-document that API.
• The cross-platform design system itself — for the shared Unistyles theme, design tokens, variant-driven component APIs, and making components feel native on web as well as iOS, use the expo-design-system skill. This skill governs iOS native feel; that one governs the token and component architecture that the two frontends share.
• Native Swift / SwiftUI — for HIG in a native Swift codebase, use ios-hig or ios-design. This skill's examples are all React Native/TSX.
• Android — these rules target iOS conventions. Use platform-adaptive code so Android gets Material; don't apply iOS idioms there.

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Native Navigation Architecture	CRITICAL	nav-
2	Native Component Fidelity	CRITICAL	native-
3	Layout & Adaptivity	HIGH	layout-
4	Touch, Gestures & Haptics	HIGH	touch-
5	Visual System & Liquid Glass	HIGH	visual-
6	Motion & Feedback	MEDIUM-HIGH	motion-
7	Accessibility	MEDIUM-HIGH	acc-
8	System Integration & Polish	MEDIUM	system-

Quick Reference

1. Native Navigation Architecture (CRITICAL)

• nav-native-stack — Use Expo Router's native Stack for screen hierarchy
• nav-native-tabs — Adopt native tabs for top-level sections
• nav-large-titles — Enable large titles on top-level screens
• nav-sheet-detents — Present secondary tasks as sheets with detents
• nav-push-vs-present — Push for hierarchy and present for self-contained tasks
• nav-search-in-header — Place search in the navigation bar
• nav-system-back — Keep the system back button and swipe-back gesture

2. Native Component Fidelity (CRITICAL)

• native-avoid-material-ui — Avoid Material Design component kits on iOS
• native-sf-symbols — Use SF Symbols for iconography
• native-system-alert — Use the native alert for confirmations
• native-action-sheet — Use an action sheet to choose among actions
• native-datetime-picker — Use the native date and time picker
• native-switch-toggle — Use the platform Switch for boolean settings

3. Layout & Adaptivity (HIGH)

• layout-safe-area-insets — Respect safe-area insets with the safe-area context
• layout-edge-to-edge — Extend scrollable content under translucent bars
• layout-keyboard-avoidance — Keep inputs visible above the keyboard
• layout-dark-mode-semantic — Drive colors from the active color scheme
• layout-content-inset-under-bars — Inset list content past the tab bar and home indicator
• layout-readable-width-ipad — Constrain reading width on iPad and large screens

4. Touch, Gestures & Haptics (HIGH)

• touch-hit-target — Size touch targets to at least 44pt
• touch-pressable-feedback — Give every control immediate press feedback
• touch-swipe-actions — Offer swipe actions on list rows
• touch-pull-to-refresh — Use RefreshControl for pull-to-refresh
• touch-gesture-handler-thread — Drive interactive gestures with Gesture Handler
• touch-haptics-on-outcome — Pair haptics with meaningful outcomes

5. Visual System & Liquid Glass (HIGH)

• visual-semantic-colors — Use semantic system colors instead of hardcoded hex
• visual-system-font — Use the system font for interface text
• visual-type-scale — Map text styles to the iOS type scale
• visual-spacing-rhythm — Derive spacing from a single base unit
• visual-liquid-glass-gated — Apply Liquid Glass through a version-gated native view
• visual-tint-discipline — Reserve the accent tint for interactive elements

6. Motion & Feedback (MEDIUM-HIGH)

• motion-ui-thread-animation — Run animations on the UI thread
• motion-virtualized-lists — Render long lists with a virtualized list
• motion-loading-states — Show content-shaped placeholders while loading
• motion-empty-states — Design empty states that guide the next action
• motion-optimistic-updates — Apply optimistic updates for user actions

7. Accessibility (MEDIUM-HIGH)

• acc-roles-labels — Label interactive and icon-only controls for VoiceOver
• acc-dynamic-type — Let text scale with Dynamic Type
• acc-reduce-motion — Honor the Reduce Motion setting
• acc-state-and-hint — Expose control state to assistive technology
• acc-grouping-focus — Group related elements for a logical focus order

8. System Integration & Polish (MEDIUM)

• system-permissions-jit — Request permissions just in time with a rationale
• system-status-bar — Match the status bar style to the content behind it
• system-keyboard-type — Configure each text field for its content
• system-share-sheet — Share through the system share sheet
• system-app-icon-launch — Configure a real app icon and launch screen

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: references/{prefix}-{slug}.md

Each rule file contains a short explanation of why it matters for native feel, an Incorrect (non-native) TSX example, a Correct (native) example that is a minimal diff from it, and an authoritative reference URL. Where relevant, rules add a "When NOT to use this pattern" or "Alternative" section.

Related Skills

• expo-ui — @expo/ui/swift-ui component API reference. Use it when the rules here point you to native SwiftUI components.
• ios-hig / ios-design — HIG and Apple design principles for native Swift/SwiftUI codebases.
• expo — Expo React Native performance optimization, complementary to the motion/list rules here.