expo-ui · pproenca — Claude Code skill for Expo SwiftUI
Guidance for building and reviewing React Native screens with @expo/ui on iOS. Useful when adopting SwiftUI views or working with iOS 26 interface features.
MIT 142 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill expo-ui -a claude-codeWhat expo-ui does
expo-ui explains how to build screens with @expo/ui/swift-ui: choose containers, set Host boundaries, and pass SwiftUI modifiers through the modifiers prop instead of React Native styles. It also covers controls, overlays, navigation composition, and state patterns.
For iOS 26, the skill covers Liquid Glass composition, including GlassEffectContainer and partial sheet detents. Most guidance assumes iOS 17 or later; Liquid Glass rules require iOS 26. This is an iOS SwiftUI reference, not guidance for Android Jetpack Compose.
Use it to investigate SwiftUI views that render at the wrong size or ignore styling, and to choose suitable layout and input components. Routing is outside its scope, so stack and tab navigation still call for expo-router.
What it helps with
- wrap SwiftUI subtrees in
Hostand size them to their contents - replace React Native styles with SwiftUI modifiers
- build a settings screen with
FormandSection - wire a controlled
TextFieldwithuseNativeState - compose iOS 26 sheets and Liquid Glass surfaces
Example prompts for the agent
- Review this
@expo/ui/swift-uiscreen and fix itsHostboundaries and modifiers. - Help migrate this React Native screen to SwiftUI components through
@expo/ui. - Check this iOS 26 sheet composition for Liquid Glass and a partial detent.
How to install expo-ui
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill expo-ui -a claude-code2Manually: put the files in place
~/.claude/skills/expo-ui/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/expo-ui/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill expo-ui -a codex2Manually: put the files in place
.agents/skills/expo-ui/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill expo-ui -a cursor2Manually: put the files in place
.cursor/skills/expo-ui/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/expo-ui2Manually: put the files in place
.github/skills/expo-ui/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill expo-ui -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/expo-uiManually: put the files in place
.devin/skills/expo-ui/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill expo-ui -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about expo-ui
How do I install expo-ui in Claude Code?
Run npx skills add pproenca/dot-skills --skill expo-ui -a claude-code. The skill file is at ~/.claude/skills/expo-ui/SKILL.md.
What does the expo-ui skill do?
It guides agents building and reviewing iOS interfaces with @expo/ui/swift-ui, covering Host, modifiers, controls, and overlay composition.
Which iOS versions does expo-ui cover?
Most guidance assumes iOS 17 or later. Liquid Glass guidance requires iOS 26.
Source text
SKILL.md · MIT
---
name: expo-ui
description: Library reference for @expo/ui SwiftUI components on iOS — covers Host boundaries, modifier composition, iOS 26 Liquid Glass and Human Interface Guidelines composition rules, layout/input/navigation/display catalogues, and ObservableState patterns. Use this skill whenever writing or reviewing React Native code that imports from @expo/ui/swift-ui or @expo/ui/swift-ui/modifiers — including new Expo apps adopting native SwiftUI views, migrations from React Native primitives to expo-ui, and code targeting iOS 26 features (Liquid Glass, GlassEffectContainer, sheet detents). Trigger even if the user does not explicitly mention "expo-ui" but is writing iOS-targeted Expo UI code that should bridge to SwiftUI.
---
# 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`](references/host-wrap-all-swiftui-roots.md) — Wrap every SwiftUI subtree in a Host
- [`host-match-contents`](references/host-match-contents.md) — Size Host to its SwiftUI content with matchContents
- [`host-viewport-size-for-form`](references/host-viewport-size-for-form.md) — Use useViewportSizeMeasurement for Form and List
- [`host-color-scheme-explicit`](references/host-color-scheme-explicit.md) — Pass explicit colorScheme when overriding the system
- [`host-ignore-safe-area`](references/host-ignore-safe-area.md) — Use ignoreSafeArea only for full-bleed surfaces
### 2. iOS 26 HIG Composition Rules (CRITICAL)
- [`hig-glass-effect-container`](references/hig-glass-effect-container.md) — Group glass siblings inside GlassEffectContainer
- [`hig-no-glass-on-glass`](references/hig-no-glass-on-glass.md) — Avoid nesting glassEffect on glass surfaces
- [`hig-no-stacked-modals`](references/hig-no-stacked-modals.md) — Resolve a sheet before presenting another
- [`hig-popover-iphone-fallback`](references/hig-popover-iphone-fallback.md) — Don't use Popover on iPhone — use BottomSheet
- [`hig-sheet-detents-partial`](references/hig-sheet-detents-partial.md) — Include a partial detent for Liquid Glass appearance
- [`hig-confirmation-dialog-destructive`](references/hig-confirmation-dialog-destructive.md) — ConfirmationDialog + destructive role
- [`hig-tint-only-for-brand`](references/hig-tint-only-for-brand.md) — Reserve tint for brand surfaces, not destructive
### 3. Modifiers System (CRITICAL)
- [`mod-prop-not-style`](references/mod-prop-not-style.md) — Modifiers go through the `modifiers` prop, not RN style
- [`mod-composition-order`](references/mod-composition-order.md) — Modifier order is meaningful — each wraps the previous
- [`mod-import-from-modifiers-subpath`](references/mod-import-from-modifiers-subpath.md) — Import from `@expo/ui/swift-ui/modifiers`
- [`mod-frame-vs-fixedsize`](references/mod-frame-vs-fixedsize.md) — frame proposes a size, fixedSize opts out of flex
- [`mod-padding-vs-frame`](references/mod-padding-vs-frame.md) — padding for inner space, frame for outer bounds
- [`mod-presentation-on-sheet-content`](references/mod-presentation-on-sheet-content.md) — Presentation modifiers attach to sheet content
- [`mod-disabled-prop`](references/mod-disabled-prop.md) — Use disabled modifier, don't conditionally render
- [`mod-animation-wraps-trigger`](references/mod-animation-wraps-trigger.md) — withAnimation wraps state-driven prop changes
### 4. Layout Components (HIGH)
- [`layout-hstack-vs-vstack`](references/layout-hstack-vs-vstack.md) — Pick stack direction by content flow
- [`layout-lazy-stack-for-long-lists`](references/layout-lazy-stack-for-long-lists.md) — LazyVStack inside ScrollView for long lists
- [`layout-form-for-settings`](references/layout-form-for-settings.md) — Form adopts iOS grouped chrome automatically
- [`layout-section-with-header-footer`](references/layout-section-with-header-footer.md) — Use Section header/footer slots
- [`layout-scrollview-axes`](references/layout-scrollview-axes.md) — Set axes explicitly for horizontal/2D scroll
- [`layout-grid-vs-stack`](references/layout-grid-vs-stack.md) — Grid for column-aligned content
### 5. Input & Controls (HIGH)
- [`input-button-role-for-destructive`](references/input-button-role-for-destructive.md) — Set role='destructive' for delete buttons
- [`input-button-systemimage`](references/input-button-systemimage.md) — Use systemImage SF Symbol for button icons
- [`input-textfield-observable-state`](references/input-textfield-observable-state.md) — useNativeState for TextField, not React state
- [`input-securefield-for-passwords`](references/input-securefield-for-passwords.md) — SecureField for passwords, not TextField
- [`input-toggle-on-async`](references/input-toggle-on-async.md) — SyncToggle for instant flicks, Toggle for async
- [`input-picker-style-via-modifier`](references/input-picker-style-via-modifier.md) — pickerStyle modifier picks appearance
- [`input-date-picker-range`](references/input-date-picker-range.md) — Constrain selectable dates with range
- [`input-stepper-bounded`](references/input-stepper-bounded.md) — Provide min and max on Stepper
### 6. Navigation & Overlays (HIGH)
- [`nav-alert-for-critical-only`](references/nav-alert-for-critical-only.md) — Alert for blocking notifications only
- [`nav-context-menu-vs-swipe`](references/nav-context-menu-vs-swipe.md) — ContextMenu or SwipeActions per row, not both
- [`nav-bottom-sheet-via-group`](references/nav-bottom-sheet-via-group.md) — Wrap BottomSheet content in Group
- [`nav-share-link-system`](references/nav-share-link-system.md) — ShareLink for the system share sheet
- [`nav-tabview-style-modifier`](references/nav-tabview-style-modifier.md) — tabViewStyle modifier picks appearance
- [`nav-disclosure-group-collapsible`](references/nav-disclosure-group-collapsible.md) — DisclosureGroup for collapsible sections
- [`nav-link-not-button-for-urls`](references/nav-link-not-button-for-urls.md) — Link for URLs, Button for in-app actions
- [`nav-menu-primary-action`](references/nav-menu-primary-action.md) — onPrimaryAction disambiguates tap from long-press
### 7. Display & Feedback (MEDIUM-HIGH)
- [`display-text-markdown`](references/display-text-markdown.md) — Enable markdownEnabled for inline rich text
- [`display-image-system-name`](references/display-image-system-name.md) — Prefer systemName SF Symbols over uiImage
- [`display-chart-data-points`](references/display-chart-data-points.md) — ChartDataPoint arrays drive native axes
- [`display-gauge-current-value-label`](references/display-gauge-current-value-label.md) — Provide currentValueLabel for accessibility
- [`display-progress-indeterminate`](references/display-progress-indeterminate.md) — Undefined value → spinner, 0 → frozen bar
- [`display-label-icon-vs-title`](references/display-label-icon-vs-title.md) — systemImage for SF Symbols, icon slot for custom
### 8. State & Cross-Cutting Patterns (MEDIUM)
- [`state-use-native-state-for-fields`](references/state-use-native-state-for-fields.md) — useNativeState for every bridged input
- [`state-worklet-writes`](references/state-worklet-writes.md) — Update ObservableState from worklets
- [`state-controlled-via-selection-prop`](references/state-controlled-via-selection-prop.md) — selection or defaultSelection, not both
- [`state-platform-check-pre-26`](references/state-platform-check-pre-26.md) — Guard iOS 26-only features with version check
- [`state-textfield-ref-imperative`](references/state-textfield-ref-imperative.md) — TextFieldRef for focus and selection
## How to Use
Read individual reference files for detailed explanations and code examples:
- [Section definitions](references/_sections.md) — Category structure and impact levels
- [Rule template](assets/templates/_template.md) — 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](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
© pproenca · MIT · pproenca/dot-skills
Similar skills
All skills for Mobile →expo-ui by other authors comes first.