expo-ui

Expo @expo/ui SwiftUI のベストプラクティス

@expo/ui/swift-ui と @expo/ui/swift-ui/modifiers のライブラリリファレンスです。Expo のネイティブ UI ブリッジにおける iOS 向けの機能を扱います。iOS 26 以前でネイティブ SwiftUI ビューを表示する Expo アプリを構築するエージェント向けに、カスケードの影響度に基づいて優先順位付けされた、8 カテゴリ・53 個のルールをまとめています。

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• @expo/ui/swift-ui を使って新しい画面を構築する場合 — 適切なコンテナー（Form、List、ScrollView）を選び、Host で正しくラップして、モディファイアを適用します
• React Native のプリミティブ（View、Text、TouchableOpacity）からネイティブの SwiftUI コンポーネントへ移行する場合
• iOS 26 の機能（Liquid Glass マテリアル、GlassEffectContainer、新しいシートの detent 動作）を対象にする場合
• @expo/ui/swift-ui または @expo/ui/swift-ui/modifiers からインポートするコードをレビューする場合
• 「SwiftUI ビューが表示されない／サイズが違う／スタイルが無視される」といった問題をデバッグする場合 — 通常は Host またはモディファイアに原因があります
• HIG のモダリティガイダンスに従って、Alert、ConfirmationDialog、BottomSheet、Popover などの表示サーフェスを組み合わせる場合
• useNativeState と worklet への書き込みを使って、TextField、Toggle、Picker、Slider などの制御された入力を作成する場合

このスキルを使用しない場面

• Android Jetpack Compose — このスキルの対象は iOS SwiftUI のみです。@expo/ui/jetpack-compose には独自の規約があります
• ユニバーサル（クロスプラットフォーム）コンポーネント — @expo/ui が公開するコンポーネントは少数です。このスキルの対象はプラットフォーム固有の iOS 向け機能です
• ナビゲーションのルーティング — スタック／タブのルーティングには expo-router と expo-router/unstable-native-tabs を使用してください。このスキルが扱うのは UI の構成のみです
• iOS 17 より前のフォールバック — ほとんどのルールは iOS 17 以降を前提としています。Liquid Glass のルールには iOS 26 が必要です

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	セットアップと Host の境界	CRITICAL	host-
2	iOS 26 HIG の構成ルール	CRITICAL	hig-
3	モディファイアシステム	CRITICAL	mod-
4	レイアウトコンポーネント	HIGH	layout-
5	入力とコントロール	HIGH	input-
6	ナビゲーションとオーバーレイ	HIGH	nav-
7	表示とフィードバック	MEDIUM-HIGH	display-
8	状態と横断的なパターン	MEDIUM	state-

クイックリファレンス

1. セットアップと Host の境界（CRITICAL）

• host-wrap-all-swiftui-roots — SwiftUI のすべてのサブツリーを Host でラップします
• host-match-contents — matchContents を使って、Host のサイズを SwiftUI コンテンツに合わせます
• host-viewport-size-for-form — Form と List には useViewportSizeMeasurement を使用します
• host-color-scheme-explicit — システム設定を上書きする場合は、colorScheme を明示的に渡します
• host-ignore-safe-area — ignoreSafeArea は全面表示のサーフェスにのみ使用します

2. iOS 26 HIG の構成ルール（CRITICAL）

• hig-glass-effect-container — ガラス表現の兄弟要素を GlassEffectContainer 内にまとめます
• hig-no-glass-on-glass — ガラスのサーフェス内に glassEffect をネストしないようにします
• hig-no-stacked-modals — 別のシートを表示する前に、現在のシートを解決します
• hig-popover-iphone-fallback — iPhone では Popover を使わず、BottomSheet を使用します
• hig-sheet-detents-partial — Liquid Glass の外観にするため、部分的な detent を含めます
• hig-confirmation-dialog-destructive — ConfirmationDialog と destructive ロールを組み合わせます
• hig-tint-only-for-brand — tint はブランドのサーフェスに限定し、破壊的な操作には使いません

3. モディファイアシステム（重要）

• mod-prop-not-style — モディファイアは RN のスタイルではなく、modifiers プロパティを通して適用します
• mod-composition-order — モディファイアの順序には意味があります。それぞれが前のモディファイアをラップします
• mod-import-from-modifiers-subpath — @expo/ui/swift-ui/modifiers からインポートします
• mod-frame-vs-fixedsize — frame はサイズを提案し、fixedSize は flex の対象から外します
• mod-padding-vs-frame — 内側の余白には padding、外側の境界には frame を使います
• mod-presentation-on-sheet-content — Presentation モディファイアはシートのコンテンツに適用します
• mod-disabled-prop — disabled モディファイアを使い、条件付きでレンダリングしないようにします
• mod-animation-wraps-trigger — withAnimation で、状態に応じて変化するプロパティをラップします

4. レイアウトコンポーネント（高）

• layout-hstack-vs-vstack — コンテンツの流れに合わせてスタックの方向を選びます
• layout-lazy-stack-for-long-lists — 長いリストには ScrollView 内で LazyVStack を使います
• layout-form-for-settings — Form は iOS のグループ化された外観を自動的に適用します
• layout-section-with-header-footer — Section の header／footer スロットを使います
• layout-scrollview-axes — 横方向または 2D のスクロールでは axes を明示的に設定します
• layout-grid-vs-stack — 列を揃えるコンテンツには Grid を使います

5. 入力とコントロール（高）

• input-button-role-for-destructive — 削除ボタンには role='destructive' を設定します
• input-button-systemimage — ボタンのアイコンには systemImage の SF Symbol を使います
• input-textfield-observable-state — TextField には React の state ではなく useNativeState を使います
• input-securefield-for-passwords — パスワードには TextField ではなく SecureField を使います
• input-toggle-on-async — 即時の切り替えには SyncToggle、非同期処理には Toggle を使います
• input-picker-style-via-modifier — pickerStyle モディファイアで外観を選択します
• input-date-picker-range — range で選択可能な日付を制限します
• input-stepper-bounded — Stepper に最小値と最大値を指定します

6. ナビゲーションとオーバーレイ（高）

• nav-alert-for-critical-only — ブロックを伴う通知にのみ Alert を使います
• nav-context-menu-vs-swipe — 各行には ContextMenu または SwipeActions のどちらかを使い、両方は使いません
• nav-bottom-sheet-via-group — BottomSheet のコンテンツを Group でラップします
• nav-share-link-system — システムの共有シートには ShareLink を使います
• nav-tabview-style-modifier — tabViewStyle モディファイアで外観を選択します
• nav-disclosure-group-collapsible — 折りたたみ可能なセクションには DisclosureGroup を使います
• nav-link-not-button-for-urls — URL には Link、アプリ内の操作には Button を使います
• nav-menu-primary-action — onPrimaryAction でタップと長押しを区別します

7. 表示とフィードバック（MEDIUM-HIGH）

• display-text-markdown — インラインのリッチテキストを有効にするには、markdownEnabled を有効にします
• display-image-system-name — uiImage よりも systemName の SF Symbols を優先します
• display-chart-data-points — ChartDataPoint 配列でネイティブの軸を設定します
• display-gauge-current-value-label — アクセシビリティのために currentValueLabel を指定します
• display-progress-indeterminate — value が未定義の場合はスピナー、0 の場合は停止したバーになります
• display-label-icon-vs-title — SF Symbols には systemImage を、カスタムアイコンには icon スロットを使用します

8. 状態と横断的なパターン（MEDIUM）

• state-use-native-state-for-fields — ブリッジされたすべての入力に useNativeState を使用します
• state-worklet-writes — worklet から ObservableState を更新します
• state-controlled-via-selection-prop — selection と defaultSelection のどちらか一方を使用し、両方は使いません
• state-platform-check-pre-26 — iOS 26 専用の機能は、バージョンチェックでガードします
• state-textfield-ref-imperative — フォーカスと選択範囲の操作には TextFieldRef を使用します

使用方法

詳しい説明とコード例については、各リファレンスファイルをお読みください。

• セクションの定義 — カテゴリーの構成と影響度
• ルールテンプレート — 新しいルールを追加するためのテンプレート
• リファレンスファイル：references/{prefix}-{slug}.md

各ルールファイルには、次の内容が含まれます。

• SwiftUI ブリッジで重要となる理由の簡単な説明
• 現実的なドメインに基づく誤ったコード例
• 誤った例からの差分を最小限にした正しいコード例
• 該当する場合：代替アプローチ、使用すべきでないケース、警告の注記、信頼できる参照 URL

注意点

gotchas.md を参照してください。実際の使用で問題点が明らかになったら、項目を追加します。

関連スキル

• Android Jetpack Compose コンポーネントについては、対応するスキルで @expo/ui/jetpack-compose を対象にします
• ナビゲーションのルーティング（スタック、タブ）には、expo-router を直接使用します
• フォーム検証ライブラリについては、react-hook-form スキルを参照してください