compose

Compose エキスパートスキル

Android、デスクトップ、iOS、Web にわたり、正確でパフォーマンスに優れた Compose コードを書くための、特定の立場に偏らない実践的なガイダンスです。 Jetpack Compose と Compose Multiplatform を対象としています。 androidx/androidx と JetBrains/compose-multiplatform-core の実際のソースコードを分析して作成されています。

ワークフロー

Compose コードを支援するときは、次のチェックリストに従ってください。

1. リクエストを理解する

• どの Compose レイヤーが関係していますか？（Runtime、UI、Foundation、Material3、Navigation）
• 状態の問題、レイアウトの問題、パフォーマンスの問題、アーキテクチャに関する質問のどれですか？
• Android のみですか、それとも Compose Multiplatform（CMP）ですか？

2. デザインを分析する（ビジュアルの参考資料がある場合）

• ユーザーが Figma フレーム、スクリーンショット、またはデザイン仕様を共有した場合は、references/design-to-compose.md を参照してください
• デザインをコンポーザブルのツリーに分解してください
• 調整せず、そのまま書き写してください。コピー、大小文字、句読点、数値の書式を正確に反映し、各値に完全一致するトークンを割り当てます。最も近い値で代用するのではなく、テーマにないトークンは追加してください（references/design-to-compose.md）
• デザイントークンを MaterialTheme に、間隔を CompositionLocals に対応付けてください
• アニメーションの要件を特定してください。references/animation.md（contentKey、phase rule、M3 motion tokens）、references/animation-recipes.md（shimmer/loading-crossfade ＋ choreography）、または references/animation-advanced.md（shared-element、predictive back、色には drawBehind を使用）を参照してください

3. 適切なリファレンスを参照する

回答する前に、references/ から関連するリファレンスファイルを読みます。

トピック	リファレンスファイル
状態のホイスティング境界（UI の値がビジネスロジックを駆動する）、derivedStateOf のキャプチャに関する落とし穴、フェーズをまたいだ逆方向の書き込み、イベントより永続的な状態を優先すること、@ReadOnlyComposable	references/state-management.md
スロット／コンテンツ API の作成 — レシーバースコープ（RowScope）、省略可能な（nullable な）スロット、XxxDefaults、スロットとブール値フラグの使い分け	references/view-composition.md
画面とコンテンツの分離（private なコンテンツコンポーザブル）、フレームワークの状態は UI に置く（ViewModel にホイスティングしない）	references/screen-structure.md
Modifier を API 契約として扱うルール（再利用可能なルートに配置をハードコードしない、呼び出し側の modifier を先頭に置く）とチェーンの順序	references/modifiers.md
エフェクト（LaunchedEffect／DisposableEffect／SideEffect）、ライフサイクルエフェクト（LifecycleResumeEffect）、エフェクトのアンチパターン	references/side-effects.md
compositionLocalOf と staticCompositionLocalOf の違い（再コンポジションのスコープ）、カスタムローカル、ローカルに可変の State を置かないこと	references/composition-locals.md
LazyList のパフォーマンスに関する落とし穴 — indexOf() による O(n²)、キー内で新しいオブジェクトを作らないこと、animateItem、ReportDrawnWhen、無限スクロールのトリガー	references/lists-scrolling.md
Navigation 3（NavDisplay、状態としてのバックスタック、Compose の形状に関するガードレール）、型安全な @Serializable ルート	references/navigation.md
AnimatedContent の contentKey による形状指定、読み取りを最新のフェーズまで遅延すること（ラムダ形式の modifier）、M3 のモーション／イージングトークン	references/animation.md
アニメーションのレシピ（シマー／ローディングのクロスフェード）、順次／並列／段階的な振り付け	references/animation-recipes.md
共有要素のトランジション（sharedBounds／sharedElement／skipToLookaheadSize）、アニメーションする色に drawBehind を使うこと、予測型戻る操作	references/animation-advanced.md
M3 の 3 つのスロットを超えてテーマを拡張する — CompositionLocal を使ったカスタムデザイントークン	references/theming-material3.md
タッチターゲット、間隔、標準的なレイアウト、折りたたみ式デバイス、M3 準拠の監査	android-skills:android-ux
再コンポジションのスキップ、安定性、ベースラインプロファイル、ベンチマーク	references/performance.md
トラバーサル順序（traversalIndex／isTraversalGroup）、ライブリージョンモード（Polite と Assertive）	references/accessibility.md
FocusRequester、focusable()、focusProperties、キーイベント、D-pad、TV、キーボード、フォーカスの復元	references/focus-navigation.md
削除／置換された API、古い Compose バージョンからの移行パス	references/deprecated-patterns.md
Styles API（実験的）：Style {}、MutableStyleState、Modifier.styleable()	references/styles-experimental.md
デザインの書き起こし — 表記／大文字小文字／数値形式を正確に保つこと、完全一致トークンと近似トークンの区別、欠けているトークンは置き換えずに追加すること、正としてエクスポートデータをレンダリング結果より優先すること、Figma の dropShadow／innerShadow（1.9 以降、チェーン内の配置）、間隔／エレベーションのデザイントークン用 CompositionLocal	references/design-to-compose.md
本番環境でのクラッシュパターン、防御的コーディング、状態／パフォーマンスのルール	references/production-crash-playbook.md
CMP の注意点（collectAsState を commonMain で使うこと、commonMain の @Preview パッケージ、Lottie から Kottie への移行、コンパイラーの安定性と非 JVM）、Android 専用から CMP への移行	references/multiplatform.md
デスクトップ（Window、Tray、MenuBar）、iOS（UIKitView）、Web（ComposeViewport）	references/platform-specifics.md

4. 適用して検証する

• リファレンスのパターンに従ったコードを書く
• ユーザーの既存コードにアンチパターンがあれば指摘する
• 過剰に設計せず、最小限の正しい解決策を提案する

5. 出典を示す

Compose の内部実装に言及する場合は、正確なソースファイルを示します。

// See: compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/Composer.kt

主な原則

1. Compose は3つのフェーズで処理します：コンポジション → レイアウト → 描画です。各フェーズでの状態の読み取りによって、そのフェーズと後続のフェーズのみが実行されます。

2. 再コンポジションは頻繁に発生しますが、コストは低く抑えられます — ただし、コンパイラーが変更されていないスコープをスキップできるようにする必要があります。安定した型を使い、コンポーザブルの本体での割り当てを避けてください。

3. Modifier の順序は重要です。Modifier.padding(16.dp).background(Color.Red) と Modifier.background(Color.Red).padding(16.dp) では、見た目が異なります。

4. 状態はできるだけ低い階層に置き、必要な範囲でのみ上位に持ち上げてください。可能だからといって、すべてを ViewModel に入れないでください。

5. 副作用は、Compose の宣言的な世界と命令型 API をつなぐためにあります。用途に合ったものを使ってください。誤用すると、原因の追跡が難しいバグにつながります。

6. Compose Multiplatform はランタイムを共有しますが、プラットフォームは共有しません。commonMain の UI コードは移植可能です。プラットフォーム固有の API（LocalContext、BackHandler、Window）には、expect/actual または条件付きソースセットが必要です。

ソースコードの検証

常に実際のソースコードで検証してください。学習データだけに頼ってはいけません。

Tier 1（推奨）：android-sources MCP サーバー

利用できる場合は、迅速で正確な検索に MCP ツールを使用してください。

lookup_class(className: "LazyListState")
lookup_method(className: "Composer", methodName: "startRestartGroup")
search_in_source(query: "fun rememberLazyListState")
list_class_members(className: "Modifier")
get_class_hierarchy(className: "LazyListState")
find_references(className: "SnapshotState", methodName: "value")

Tier 2（フォールバック）：GitHub の生 URL

MCP サーバーを利用できない場合は、ソースを直接取得してください。

• AndroidX：https://raw.githubusercontent.com/androidx/androidx/androidx-main/{path}
• ディレクトリ一覧：gh api repos/androidx/androidx/contents/{path}
• CMP：https://raw.githubusercontent.com/JetBrains/compose-multiplatform-core/jb-main/{path}
• AOSP プラットフォーム：https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/{path}?format=TEXT（base64）

2層アプローチ

1. ガイダンスから始める — トピックに固有のリファレンス（例：references/state-management.md）を読みます
2. 実際のソースコードで検証する — MCP ツールまたは GitHub の生 URL を使って動作を確認します

ソースツリーのマップ

androidx/androidx (branch: androidx-main)
├── compose/runtime/runtime/src/commonMain/kotlin/androidx/compose/runtime/
├── compose/ui/ui/src/androidMain/kotlin/androidx/compose/ui/platform/
├── compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/
├── compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/
├── compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/
└── compose/navigation/navigation-compose/src/commonMain/kotlin/androidx/navigation/compose/

compose-multiplatform-core (branch: jb-main)
├── compose/ui/ui/src/desktopMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/iosMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/webMain/kotlin/androidx/compose/ui/window/
├── compose/ui/ui/src/skikoMain/kotlin/androidx/compose/ui/
└── compose/foundation/foundation/src/skikoMain/kotlin/androidx/compose/foundation/

compose-multiplatform (resources library)
└── components/resources/library/src/commonMain/

権威あるドキュメント

ガイダンス、ベストプラクティス、移行ガイドなど、ソースコードだけでは答えられない内容については、ウェブ検索より Google の Android Knowledge Base を優先してください。

android docs search "LazyColumn performance"              # ranked kb:// URLs + summaries
android docs fetch kb://android/develop/ui/compose/lists  # full content of a result

Android、Wear、TV、KMP、Glance に関する厳選されたドキュメントを4,800件以上収録しています。references/ 内のファイルで質問に対応できない場合に使用してください。実装の詳細が必要で、ガイダンスではなく具体的な動作を確認したい場合は、上記のソースコード検索を使用してください。