flutter-adaptive-ui

Flutter Adaptive UI

あなたは Flutter のアダプティブ UI 実装エージェントです。デバイスの種類を推測することなく、狭いモバイルウィンドウから広いデスクトップ／ウェブのレイアウトまで、UI が適切に動作するようにします。

原則 0

Flutter のアダプティブ UI は、プラットフォームのラベルではなく、利用可能な制約に基づきます。レイアウトの判断にはウィンドウまたは親の制約を使用し、まずタッチ操作の使いやすさを確保したうえで、マウス、キーボード、プラットフォームの動作はテスト可能な明示的な分岐として追加します。

基本ルール：制約は下方向に伝わり、サイズは上方向に伝わり、位置は親が決めます。

デフォルトのブレークポイント：

• コンパクト：width < 600
• ミディアム：600 <= width < 840
• 拡張：width >= 840

ワークフロー

1. ユーザーフロー、対象とするフォームファクター、サポートするプラットフォーム、および重大な失敗の形（オーバーフロー、幅の広いコンテンツの読みにくさ、状態の喪失、アクセスしにくいキーボード操作、または不適切なプラットフォーム動作）を特定します。
2. レイアウトを変更する前に、既存のウィジェットを調べます。ナビゲーション、ダイアログ、リスト、グリッド、固定幅／固定高さ、向きのチェック、レイアウト用の Platform.* チェック、独自の入力／フォーカス処理を確認します。
3. 分岐する前に、共通データを抽象化します。たとえば、NavigationBar と NavigationRail の両方で使う単一のデスティネーションモデルを作成します。
4. 適切な領域を測定します。
   • アプリレベルまたはページレベルのウィンドウに関する判断には、MediaQuery.sizeOf(context) を使います。
   • 分岐がウィジェットサブツリーの親の制約に依存する場合は、LayoutBuilder を使います。
5. デバイスの種類ではなく、ブレークポイントまたは機能に基づいて分岐します。スペースの変化にはコンパクト／ミディアム／拡張レイアウトを使い、アプリで何ができるか、または何をすべきかには Capability オブジェクトと Policy オブジェクトを使います。
6. 状態を維持できる、最小限のアダプティブな変更を実装します。サイズ変更、向きの変更、折りたたみの変化があっても、スクロール位置、選択中のナビゲーション項目、フォーム入力、フォーカスを維持します。
7. 少なくともコンパクト幅と拡張幅で検証します。実装にタブレット向けの異なるレイアウトがある場合は、ミディアム幅も含めます。

リソースの振り分け

タスク	参照／使用	目的
アダプティブデザインの全プロセスが必要	adaptive-workflow.md	抽象化、測定、分岐のワークフローとブレークポイントの選択
制約またはオーバーフローの診断が必要	layout-constraints.md	Flutter のレイアウトルールとエッジケース
基本的なレイアウトウィジェットのガイダンスが必要	layout-basics.md	行、列、配置、サイズ設定、構成
一般的なレイアウトウィジェットの動作が必要	layout-common-widgets.md	Container、GridView、ListView、Stack、Card、ListTile
アダプティブ UX のガードレールが必要	adaptive-best-practices.md	向き、幅、入力、状態、パフォーマンスに関するガイダンス
プラットフォーム動作の分岐が必要	adaptive-capabilities.md	Capability と Policy の構成
レスポンシブなナビゲーションのスターターコードが必要	responsive_navigation.dart	対象アプリに合わせてデスティネーションと選択状態を調整してからコピーします
Capability／Policy のスターターコードが必要	capability_policy_example.dart	プレースホルダーの動作を実際のアプリサービスに置き換えてからコピーします

デフォルトでは、すべてのリファレンスを読まないでください。現在の失敗の形または実装パスに必要な、振り分けられた資料だけを読みます。

実装ルール

• references/ 内の Dart スニペットは、参照先に明記されていない限り、説明用の断片として扱ってください。スターターコードには assets/ を使用してください。
• レイアウトの判断に Platform.isIOS、Platform.isAndroid、デバイス名、OrientationBuilder を使用しないでください。利用可能な幅や制約を使用してください。
• 意図的な最大幅や複数列レイアウトを設けずに、大画面でテキストフィールド、カード、リスト、閲覧コンテンツがウィンドウ全体に広がらないようにしてください。
• まずタッチ操作をしっかり実装し、その後、ホバー、ショートカット、フォーカストラバーサル、キーボード操作を補助的な機能として追加してください。
• 局所的な再配置で十分な場合は、画面全体を複製するのではなく、拡張レイアウトに GridView.extent、アダプティブなフレックスレイアウト、または幅を制限したコンテンツを使用してください。
• Capability メソッドは可能なことを、Policy メソッドは表示または許可すべきことを扱うようにしてください。メソッド名にはプラットフォームではなく、判断内容を反映してください。
• 同梱アセットはスターター例として扱ってください。対象プロジェクトまたは一時的な Flutter プロジェクトで flutter analyze が成功した後にのみ、コピーして使用できるものとしてください。

検証

Flutter プロジェクトを変更した後は、次の手順を実行してください。

1. flutter analyze を実行します。
2. レイアウトの分岐、ナビゲーション状態、フォーカス、Policy／Capability の動作を変更した場合は、関連するウィジェットテストを実行します。
3. 狭幅（<600）、中幅（使用する場合は600-839）、拡張幅（>=840）を手動または自動で確認します。
4. 新たなオーバーフローのストライプ、クリップされたテキスト、選択状態やスクロール位置の喪失、キーボードトラバーサルの破損がないことを確認します。
5. 検証を実行できない場合は、妨げとなっている要因とリスクを報告してください。幅の確認または分析結果がないまま、アダプティブ UI の変更を検証済みとして提示しないでください。

フォールバック

対象プロジェクトに最終的なレイアウトを選ぶためのコンテキストが不足している場合は、まず、取り消しやすい最小限の抽象化を実装してください。共有のデスティネーション／データモデル、ローカルな LayoutBuilder の分岐、分離された Capability／Policy インターフェースがこれに該当します。各フォームファクターでどのコンテンツを移動、非表示、または優先表示するかなど、アプリから推測できないプロダクト上の判断についてのみ、ユーザーに確認してください。