ionic-design

Ionic Framework の設計

使用するタイミング

次の場合に使用します：

• Capacitor アプリで Ion* / ion-* コンポーネントを作成またはレビューするとき
• テーマ設定：--ion-color-*、ダークモード、ハイコントラスト、プラットフォーム別スタイル
• iOS モードと Material Design モードの表示がおかしい場合、または mode の上書きが正しく動作しない場合
• Ionic 7/8 から 9 にアップグレードするとき、または npm i @ionic/*@latest の後にエラーが発生したとき
• 新しい Capacitor アプリで Ionic と別の UI キットのどちらを選ぶか検討するとき

次の場合は使用しないでください：

• Konsta UI コンポーネント：konsta-ui
• Tailwind v4 のインストール／設定：tailwind-capacitor
• Ionic 以外でのノッチ／システムバーのパディング：safe-area-handling
• キーボードが入力欄に重なる場合：capacitor-keyboard（Ionic アプリでは resize: 'ionic' を使用します）
• Appflow／Ionic Enterprise プラグインからの移行：ionic-appflow-migration、ionic-enterprise-sdk-migration

バージョン（2026年10月）

パッケージ	現行	備考
@ionic/core、@ionic/react、@ionic/vue、@ionic/angular	9.x（latest）	v8-lts タグでは 8.x
ionicons	8.x
Ionic 9 の最小要件	Capacitor 7+、iOS 16+、Android Chromium 89+、Angular 18-22、React 18/19 + React Router 6.4+、Vue 3.5 + vue-router 5、TypeScript 5.4+

まずインストール済みのバージョンを確認します：npm ls @ionic/core @ionic/react @ionic/vue @ionic/angular。インストール済みのメジャーバージョンに合わせてコードを記述し、v8 と v9 の API を混在させないでください。

ワークフロー

1. 確認：フレームワーク、Ionic のメジャーバージョン、ルーターのバージョン、グローバル CSS のインポート、setupIonicReact / IonicVue / provideIonicAngular の設定、capacitor.config の Keyboard.resize を確認します。
2. アップグレードする場合：references/ionic-9-migration.md を読み込みます。まず npx @ionic/migrate をプレビューで実行し、検出結果を報告してから適用します。
3. コンポーネント：ページシェル、リスト、フォーム、オーバーレイ、タブについては references/components.md を参照します。
4. テーマ設定：色、ダーク／ハイコントラストのパレット、モード別 CSS、シャドウパーツについては references/theming.md を参照します。
5. 以下の手順に従って、両方のモードとデバイスで検証します。

該当するトピックを扱う場合にのみ、リファレンスを読み込みます。

Ionic のバグの大半を防ぐルール

• ルーティングされる各ページは、IonPage > IonHeader + IonContent（+ オプションの IonFooter）で構成します。IonPage がないと、画面遷移とライフサイクルフックが正しく動作しません。
• スクロールは ion-content 内で行います。body やラッパーの div をスクロールさせず、IonContent の scrollToTop() / getScrollElement() を使用します。
• URL によるルーティングには ion-router-outlet（IonRouterOutlet、IonTabs）を使用します。Ionic 9 では ion-nav は ion-router と連携しなくなりました。ページ内の URL を持たないスタックには引き続き使用できます。
• セーフエリアは --ion-safe-area-top|right|bottom|left（デフォルトは env()）で処理します。これに加えて body にパディングを設定しないでください。viewport-fit=cover が必要です。
• フォームでは、コントロール自体に label と labelPlacement を指定します（<IonInput label="Email" labelPlacement="floating" />）。従来の <IonItem><IonLabel/><IonInput/></IonItem> によるラベル付けは Ionic 8 で削除されました。
• オーバーレイでは、インラインの <IonModal isOpen> / trigger またはフック（useIonModal、modalController）を一貫して使用します。状態をリセットできるよう、必ず didDismiss を処理します。
• プラットフォーム別のスタイルには、html 上の .ios / .md クラスまたは mode CSS セレクターを使用します。isPlatform('ios') は動作の分岐にのみ使用し、navigator.userAgent は使用しないでください。
• アイコンは使用するものだけをインポートし（import { heart } from 'ionicons/icons'）、icon={heart} として渡します。スタンドアロン／バンドルビルドでは、文字列の名前を使う場合に addIcons による登録が必要です。

検証

1. ビルドして同期します：npm run build && npx cap sync。
2. ブラウザーで両方のモードを実行します：開発用 URL に ?ionic:mode=ios と ?ionic:mode=md を追加し、ヘッダー、ツールバー、リスト、ボタンを確認します。
3. OS のダークモードを切り替えるか（クラスパレットを使用している場合は <html> に ion-palette-dark を追加し）、カスタムカラーのコントラストを確認します。
4. デバイスで確認します：Dynamic Island を搭載した iPhone と、ジェスチャーナビゲーションを使用する Android 15/16 で、ヘッダー／タブバーのインセットを確認します。フォームページでキーボードを開きます。
5. アップグレード後：grep -rn "ion-picker-legacy\|pickerController\|useIonPicker\|@ionic/angular/standalone\|autocorrect=\"off\"" src/ の結果が空であることを確認し、npx tsc --noEmit が成功することを確認します。

エラー処理

エラー／症状	原因	修正方法
Package path ./dist/... is not exported from package（webpack）／ERR_PACKAGE_PATH_NOT_EXPORTED（Node）が @ionic/core で発生する	Ionic 9 の exports マップ、ディープインポート	@ionic/core、@ionic/core/components、@ionic/core/components/ion-*.js、@ionic/core/loader、@ionic/core/css/*.css からインポートします
@ionic/angular/standalone（Ionic 9）のインポートエラー、または移行時の警告	スタンドアロンインポートの移動	@ionic/angular からインポートします。遅延読み込み API は @ionic/angular/lazy からインポートします
React：Route／IonRoute で Property 'component' does not exist が発生する	Ionic 9 では React Router 6 が必要です	element={<Page />} を使用します。Redirect の代わりに Navigate、useHistory の代わりに useNavigate を使用します
アップグレード後に自動修正が有効になる	Ionic 9 では文字列の autocorrect="off" が真として扱われます	属性を削除するか、false をバインドします
同じオプションを再選択しても ionChange が発火しない	Ionic 9 では値が変更された場合のみ発火します	閉じるときは ionDismiss を使用します
シートモーダルのハンドルにフォーカスできるようになり、ブレークポイントの切り替えが循環する	Ionic 9 の handleBehavior のデフォルトが cycle です	元に戻すには handle-behavior="none" を指定します
スタイルが適用されず、コンポーネントのスタイルが失われる	コア CSS がインポートされていません	エントリーポイントで一度、@ionic/<fw>/css/core.css（および structure／typography）をインポートします
ダークモードが有効にならない	パレットがインポートされていません	css/palettes/dark.system.css をインポートします（または .class.css と ion-palette-dark クラスを使用します）
Angular 21 で非同期処理後にビューが更新されない	Ionic 9 と Angular 21 ではゾーンレスがデフォルトです	シグナル／markForCheck() を使用するか、provideZoneChangeDetection() を追加します

リソース

• Ionic のドキュメント：https://ionicframework.com/docs
• Ionic 9 の破壊的変更：https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md
• テーマ設定：https://ionicframework.com/docs/theming/basics
• ダークモード：https://ionicframework.com/docs/theming/dark-mode