ios-navigation

iOS ナビゲーション（モジュラー MVVM-C）

クリニックのモジュラーアーキテクチャを使用する SwiftUI アプリ向けの、意見を明確に打ち出したナビゲーションの指針です。コーディネーターとルートシェルの連携、機能の分離、堅牢なプッシュ／シート／ディープリンクのフローに重点を置きます。

譲れない制約（iOS 26 / Swift 6.2）

• すべてのナビゲーションビューで @Equatable マクロを使用し、AnyView は決して使用しない
• どこでも @Observable を使用し、ObservableObject ／ @Published は決して使用しない
• アプリターゲットのコーディネーターが NavigationPath を所有し、ルートシェルが .navigationDestination のマッピングを所有する
• モーダル状態はコーディネーターが所有し、シート用のインライン @State ブール値は決して使用しない
• ドメイン層でコーディネータープロトコルを定義し、具象コーディネーターを機能モジュールに含めない

クリニックアーキテクチャの契約（iOS 26 / Swift 6.2）

このスキルのすべてのガイダンスは、クリニックのモジュラー MVVM-C アーキテクチャを前提としています。

• 機能モジュールがインポートできるのは Domain と DesignSystem のみです（Data や兄弟機能は決してインポートしません）
• アプリターゲットが統合地点となり、DependencyContainer、具象コーディネーター、ルートシェルの連携を所有します
• Domain は純粋な Swift を保ち、モデルと、リポジトリ、*Coordinating、ErrorRouting、AppError の各契約を定義します
• Data は SwiftData／ネットワーク／同期／再試行／バックグラウンド I/O を所有し、Domain プロトコルを実装します
• 読み書きフローの既定動作は、読み取りでは stale-while-revalidate、書き込みでは楽観的なキュー処理です
• ViewModel はリポジトリプロトコルを直接呼び出します（既定のユースケース／インタラクター層はありません）

適用する場合

以下の場合にこのガイドラインを参照してください。

• NavigationStack または NavigationSplitView を使ったナビゲーション階層を設計する
• プッシュ、シート、fullScreenCover のどれを使うか選択する
• ヒーローアニメーション、ズームトランジション、またはジェスチャーによる閉じる動作を実装する
• 複数ステップのフロー（オンボーディング、チェックアウト、登録）を構築する
• 共有ナビゲーション状態に @Environment と @Bindable を組み合わせて @Observable を使用する
• ナビゲーションのアンチパターンとモジュラーアーキテクチャへの準拠についてコードをレビューする
• ディープリンク、状態復元、またはタブの状態保持を追加する
• ナビゲーションで VoiceOver と視差効果を減らす設定への対応を確保する

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

優先度	カテゴリ	影響度	プレフィックス
1	ナビゲーションアーキテクチャ	重大	arch-
2	ナビゲーションのアンチパターン	重大	anti-

| 3 | トランジションとアニメーション | 高 | anim- | | 4 | モーダル表示 | 高 | modal- | | 5 | フローのオーケストレーション | 高 | flow- | | 6 | ナビゲーションのパフォーマンス | 中〜高 | perf- | | 7 | ナビゲーションのアクセシビリティ | 中 | ally- | | 8 | 状態と復元 | 中 | state- |

クイックリファレンス

1. ナビゲーションアーキテクチャ（重要）

• arch-navigation-stack - 非推奨の NavigationView ではなく NavigationStack を使用します
• arch-value-based-links - destination クロージャではなく、値ベースの NavigationLink を使用します
• arch-destination-registration - navigationDestination はスタックのルートで登録します
• arch-destination-item - オプショナルベースのナビゲーションには navigationDestination(item:) を使用します（iOS 26 / Swift 6.2）
• arch-route-enum - ルートは Hashable な列挙型として定義します
• arch-split-view - マルチカラムレイアウトには NavigationSplitView を使用します
• arch-coordinator - ナビゲーションロジックを Observable コーディネーターに切り出します
• arch-observable-environment - 共有状態には @Observable と @Bindable を組み合わせて @Environment を使用します
• arch-deep-linking - NavigationPath に追加してディープリンクを処理します
• arch-navigation-path - 異種型を型消去して扱うナビゲーションには NavigationPath を使用します
• arch-equatable-views - すべてのナビゲーションビューに @Equatable マクロを適用します
• arch-observable-only - @Observable のみを使用し、ObservableObject や @Published は使用しません
• arch-no-anyview - ナビゲーションでは AnyView を使用せず、@ViewBuilder またはジェネリクスを使用します
• arch-coordinator-modals - すべてのモーダルはコーディネーター経由で表示し、インラインの @State は使用しません

2. ナビゲーションのアンチパターン（重要）

• anti-mixed-link-styles - NavigationLink(destination:) と NavigationLink(value:) を混在させないでください
• anti-scattered-destinations - navigationDestination を複数のビューに分散させないでください
• anti-shared-stack - NavigationStack をタブ間で共有しないでください
• anti-hidden-back-button - スワイプジェスチャーを維持せずに戻るボタンを非表示にしないでください
• anti-navigation-in-init - ビューのイニシャライザーで負荷の高い処理を行わないでください
• anti-hamburger-menu - ハンバーガーメニューによるナビゲーションは避けてください
• anti-programmatic-tab-switch - プログラムによるタブ選択の変更は避けてください

3. トランジションとアニメーション（高）

• anim-zoom-transition - ヒーローアニメーションにはズームナビゲーショントランジションを使用します（iOS 18+）
• anim-matched-geometry-same-view - matchedGeometryEffect は同じビュー階層内でのみ使用します
• anim-spring-config - 最新のスプリングアニメーション構文を使用します（iOS 26 / Swift 6.2）
• anim-gesture-driven - ジェスチャー駆動のトランジションにはインタラクティブなスプリングアニメーションを使用します
• anim-transition-source-styling - トランジションのソースをシェイプと背景でスタイル設定します
• anim-reduce-motion-transitions - すべてのナビゲーションアニメーションで視差効果を減らす設定を尊重します
• anim-scroll-driven - スクロール駆動のトランジションには onScrollGeometryChange を使用します（iOS 18+）

4. モーダル表示（HIGH）

• modal-sheet-vs-push - 詳細画面への移動にはプッシュを使い、補足コンテンツにはシートを使います
• modal-detents - コンテキストに応じたシートのサイズ設定には、表示デテントを使います
• modal-fullscreen-cover - 没入型の独立した体験に限り、fullScreenCover を使います
• modal-sheet-placement - .sheet は NavigationLink ではなく、コンテナビューに配置します
• modal-interactive-dismiss - interactiveDismissDisabled を使って、未保存の変更がある場合の操作による閉じる動作を制御します
• modal-nested-navigation - モーダル内では別の NavigationStack を使います

5. フローのオーケストレーション（HIGH）

• flow-tab-independence - 各タブにそれぞれ独自の NavigationStack を持たせます
• flow-multi-step - 複数ステップのフローには、ルート配列を使う NavigationStack を使います
• flow-sidebar-navigation - サイドバーには、選択バインディングを使う NavigationSplitView を使います
• flow-tab-sidebar-adaptive - iPad でタブをサイドバーに切り替えるには、sidebarAdaptable TabView を使います（iOS 18 以降）
• flow-pop-to-root - NavigationPath をクリアして、ルート画面に戻る動作を実装します
• flow-screen-independence - 画面を親のナビゲーションコンテキストから独立させます

6. ナビゲーションのパフォーマンス（MEDIUM-HIGH）

• perf-lazy-destinations - 遷移先を遅延構築するには、値ベースの NavigationLink を使います
• perf-task-modifier - ナビゲーション時の非同期データ読み込みには .task を使います
• perf-state-object-ownership - @Observable の状態は @State で所有し、通常のプロパティとして渡します
• perf-avoid-body-side-effects - ビューの body 内での副作用を避けます

7. ナビゲーションのアクセシビリティ（MEDIUM）

• ally-rotor-headers - VoiceOver ローターでナビゲーションのセクション見出しを識別できるようにします
• ally-focus-after-navigation - プログラムによるナビゲーションイベントの後にフォーカスを管理します
• ally-group-navigation-elements - 関連するナビゲーション要素をグループ化して、スワイプ回数を減らします
• ally-hide-decorative-navigation - 装飾的なナビゲーション要素を VoiceOver から隠します
• ally-keyboard-focus - フォームでのキーボードナビゲーションには @FocusState を使います

8. 状態と復元（MEDIUM）

• state-codable-routes - ナビゲーション状態を永続化するため、ルートの enum を Codable にします
• state-scene-storage - シーンごとのナビゲーション状態を永続化するには SceneStorage を使います
• state-tab-persistence - 選択中のタブを SceneStorage で永続化します
• state-deep-link-urls - ディープリンク URL をルートの enum に解析します
• state-avoid-app-level-path - App レベルで NavigationPath を定義するのは避けます

使用方法

詳しい説明とコード例については、個々のリファレンスファイルを参照してください。

• セクションの定義 - カテゴリー構成と影響レベル
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス情報