Agent Skills: Expo @expo/ui SwiftUI Best Practices

Expo @expo/ui SwiftUI Best Practices

Library reference for @expo/ui/swift-ui and @expo/ui/swift-ui/modifiers — the iOS surface of Expo's native UI bridge. Contains 53 rules across 8 categories, prioritised by cascade impact for agents building Expo apps that render to native SwiftUI views on iOS 26 and earlier.

When to Apply

Reference these guidelines when:

• Building a new screen with @expo/ui/swift-ui — pick the right container (Form vs List vs ScrollView), wrap in Host correctly, apply modifiers
• Migrating from React Native primitives (View, Text, TouchableOpacity) to native SwiftUI components
• Targeting iOS 26 features — Liquid Glass material, GlassEffectContainer, new sheet detent behaviours
• Reviewing code that imports from @expo/ui/swift-ui or @expo/ui/swift-ui/modifiers
• Debugging "the SwiftUI view doesn't render / is the wrong size / ignores styles" — usually a Host or modifier issue
• Composing presentation surfaces — Alert, ConfirmationDialog, BottomSheet, Popover — under HIG modality guidance
• Writing controlled inputs (TextField, Toggle, Picker, Slider) with useNativeState and worklet writes

When NOT to Use This Skill

• Android Jetpack Compose — this skill covers iOS SwiftUI only. The @expo/ui/jetpack-compose surface has its own conventions
• Universal (cross-platform) components — @expo/ui exposes a small set; this skill scopes to the platform-specific iOS surface
• Navigation routing — for stack/tab routing, use expo-router and expo-router/unstable-native-tabs; this skill covers UI composition only
• Pre-iOS-17 fallbacks — most rules assume iOS 17 minimum; Liquid Glass rules require iOS 26

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Setup & Host Boundaries | CRITICAL | host- | | 2 | iOS 26 HIG Composition Rules | CRITICAL | hig- | | 3 | Modifiers System | CRITICAL | mod- | | 4 | Layout Components | HIGH | layout- | | 5 | Input & Controls | HIGH | input- | | 6 | Navigation & Overlays | HIGH | nav- | | 7 | Display & Feedback | MEDIUM-HIGH | display- | | 8 | State & Cross-Cutting Patterns | MEDIUM | state- |

Quick Reference

1. Setup & Host Boundaries (CRITICAL)

• host-wrap-all-swiftui-roots — Wrap every SwiftUI subtree in a Host
• host-match-contents — Size Host to its SwiftUI content with matchContents
• host-viewport-size-for-form — Use useViewportSizeMeasurement for Form and List
• host-color-scheme-explicit — Pass explicit colorScheme when overriding the system
• host-ignore-safe-area — Use ignoreSafeArea only for full-bleed surfaces

2. iOS 26 HIG Composition Rules (CRITICAL)

• hig-glass-effect-container — Group glass siblings inside GlassEffectContainer
• hig-no-glass-on-glass — Avoid nesting glassEffect on glass surfaces
• hig-no-stacked-modals — Resolve a sheet before presenting another
• hig-popover-iphone-fallback — Don't use Popover on iPhone — use BottomSheet
• hig-sheet-detents-partial — Include a partial detent for Liquid Glass appearance
• hig-confirmation-dialog-destructive — ConfirmationDialog + destructive role
• hig-tint-only-for-brand — Reserve tint for brand surfaces, not destructive

3. Modifiers System (CRITICAL)

• mod-prop-not-style — Modifiers go through the modifiers prop, not RN style
• mod-composition-order — Modifier order is meaningful — each wraps the previous
• mod-import-from-modifiers-subpath — Import from @expo/ui/swift-ui/modifiers
• mod-frame-vs-fixedsize — frame proposes a size, fixedSize opts out of flex
• mod-padding-vs-frame — padding for inner space, frame for outer bounds
• mod-presentation-on-sheet-content — Presentation modifiers attach to sheet content
• mod-disabled-prop — Use disabled modifier, don't conditionally render
• mod-animation-wraps-trigger — withAnimation wraps state-driven prop changes

4. Layout Components (HIGH)

• layout-hstack-vs-vstack — Pick stack direction by content flow
• layout-lazy-stack-for-long-lists — LazyVStack inside ScrollView for long lists
• layout-form-for-settings — Form adopts iOS grouped chrome automatically
• layout-section-with-header-footer — Use Section header/footer slots
• layout-scrollview-axes — Set axes explicitly for horizontal/2D scroll
• layout-grid-vs-stack — Grid for column-aligned content

5. Input & Controls (HIGH)

• input-button-role-for-destructive — Set role='destructive' for delete buttons
• input-button-systemimage — Use systemImage SF Symbol for button icons
• input-textfield-observable-state — useNativeState for TextField, not React state
• input-securefield-for-passwords — SecureField for passwords, not TextField
• input-toggle-on-async — SyncToggle for instant flicks, Toggle for async
• input-picker-style-via-modifier — pickerStyle modifier picks appearance
• input-date-picker-range — Constrain selectable dates with range
• input-stepper-bounded — Provide min and max on Stepper

6. Navigation & Overlays (HIGH)

• nav-alert-for-critical-only — Alert for blocking notifications only
• nav-context-menu-vs-swipe — ContextMenu or SwipeActions per row, not both
• nav-bottom-sheet-via-group — Wrap BottomSheet content in Group
• nav-share-link-system — ShareLink for the system share sheet
• nav-tabview-style-modifier — tabViewStyle modifier picks appearance
• nav-disclosure-group-collapsible — DisclosureGroup for collapsible sections
• nav-link-not-button-for-urls — Link for URLs, Button for in-app actions
• nav-menu-primary-action — onPrimaryAction disambiguates tap from long-press

7. Display & Feedback (MEDIUM-HIGH)

• display-text-markdown — Enable markdownEnabled for inline rich text
• display-image-system-name — Prefer systemName SF Symbols over uiImage
• display-chart-data-points — ChartDataPoint arrays drive native axes
• display-gauge-current-value-label — Provide currentValueLabel for accessibility
• display-progress-indeterminate — Undefined value → spinner, 0 → frozen bar
• display-label-icon-vs-title — systemImage for SF Symbols, icon slot for custom

8. State & Cross-Cutting Patterns (MEDIUM)

• state-use-native-state-for-fields — useNativeState for every bridged input
• state-worklet-writes — Update ObservableState from worklets
• state-controlled-via-selection-prop — selection or defaultSelection, not both
• state-platform-check-pre-26 — Guard iOS 26-only features with version check
• state-textfield-ref-imperative — TextFieldRef for focus and selection

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:

• Brief explanation of why it matters in the SwiftUI bridge
• Incorrect code example anchored to a realistic domain
• Correct code example with a minimal diff from the incorrect one
• Where relevant: Alternative approach, When NOT to use, Warning callouts, authoritative reference URL

Gotchas

See gotchas.md — append entries as failure points surface during real use.

Related Skills

• For Android Jetpack Compose components, the parallel skill would target @expo/ui/jetpack-compose
• For navigation routing (stack, tabs), use expo-router directly
• For form validation libraries, see the react-hook-form skill