compose-preview

Compose Preview

Android Studio を使わずに @Preview のコンポーザブルを PNG にレンダリングします（Android は Robolectric 経由、CMP Desktop は Skia 経由）。CLI、Gradle プラグイン、レンダラーは compose-ai-tools から提供されます。MCP サーバーは compose-preview-server から提供されます。

まずレンダリングする

レンダリングまたはプレビューの表示を依頼されたら、以下の短い手順に従ってください。ガイドラインの レビューを依頼された場合は、ツールを呼び出す前に レビュー用チェックリストを使って、ローカル、ホスト型、UI Builder のいずれの方法を使うか選んでください。公開カタログとサーバー上にあるデザインでは、まずホスト型ツールを使います。ローカルのチェックアウトがなくても、クローン、Gradle、クラウド環境は必要ありません。ツールを利用できない場合は、確認できなかったことを報告し、インテグレーションのセットアップ手順に従ってください。

ローカル MCP サーバー（compose-preview-server 3.78.0 以降）が接続されている場合、その initialize の指示に呼び出し方法が記載されています。render_preview preview=<FunctionName> を使い、事前の探索や登録、手作りのモックは行わないでください。その指示に従ってください。このスキルでは、さらに呼び出し回数を制限します。通常のレンダリングは最大 3 回のツール呼び出しとし、返信に base64 を含めず、画像を見る必要がある場合に限って画像を取得します。

最初の呼び出しはレンダリングです。プレビューを grep したり、先にソースを読んだりしないでください。サーバーが関数名からプレビューを見つけます。レンダリングに失敗した場合に限り、情報を調べてください。

1. レンダリングする。 クライアントがローカルファイルを読み取れる場合（Claude Code、Codex、Gemini CLI、OpenCode、Antigravity）は、inline=false を指定してください。結果には pngPath、 sha256、寸法、changed が含まれ、画像トークンは含まれません。otherMatches が一覧にある場合は、ユーザーから依頼されたものだけをレンダリングしてください。 message に選択を求める記載がある variantChoice が含まれている場合（複数のプレビューが一致し、ホスト側に選択肢が表示されなかった場合）は、選ぶのはあなたではなくユーザーです。レンダリングした候補と choices の全項目を番号付きリストで返信し、どれを意図していたか尋ねてください。その後はそこで終了してください。「ほかのバリアントもあります」のように選択肢を選んだり、リストを短くしたりしないでください。グリッド形式の結果、または選択の辞退については、質問する必要はありません。
2. 必要な場合に限って確認する。 UI の説明や評価をする前に、ファイルリーダーで pngPath を読み取ってください。ユーザーが目にするのはその画像です。changed または sha256 だけで質問に答えられる場合（例：「編集内容は反映されたか？」）は、読み取りを省略してください。実際に見た内容だけを説明してください。ここで画像を表示できない場合は、その旨を率直に伝えてください。
3. 簡潔に返信する。 ユーザーが同じ画像を開けるよう、pngPath を含めてください。ターミナルや印刷モードのハーネスではツールが返す画像をユーザーが見られないため、「上の画像」とは書かないでください。代わりに pngPath を示してください。

ライブラリのコンポーネントはカタログから取得します。 ユーザーが自身のプレビューではなく、ライブラリのコンポーネント（Material 3、Wear M3 EdgeButton など）を指定した場合は、ホスト型カタログ（compose-catalogs）を使用してください。まず catalog_list_previews を呼び出し、次に resources/read で公開済みスナップショットを読み取ります。catalog_render_preview で設定を変更する場合に限り、live アクセスをリクエストしてください。ユーザーから依頼されない限り、ライブラリのコンポーネントを表示するためにユーザーのプロジェクトへプレビューファイルを追加してはいけません。 カタログ MCPを参照してください。

複数レンダリングではハッシュを使います。 複数のレンダリング（バリアント、デバイス、フォントスケール、ロケール、変更前後の比較など）では、observe=hash を指定するか、contactSheet: false を設定して render_matrix を使用してください。セルごとのハッシュのみが返されます。ピクセルデータを取得するのは、最終画面、ハッシュが変わったセル、または目視での評価が必要なセルに限ってください。その場合は、該当セルごとに render_preview（そのセルの overrides または uri と inline=false を指定）を 1 回呼び出し、その pngPath を 1 回読み取ってください。 デザインガイドラインのレビュー。 Android のデザインガイダンスに照らしてプレビューやカタログのデザインをレビューするよう求められた場合は、 design-guidelines.mdを読んでください。キー不要のエージェントレビュー、公開された結果、CLI のcompose-preview reviewループを扱い、対象サーフェスの明示的な選択、必須画像、不完全なカバレッジについて説明しています。デフォルトの スキルバンドルに含まれているため、オプションの PR レビューバンドルは必要ありません。

複数レンダーのレビューはdesign-reviewerに引き継いでください。 design-reviewer サブエージェントが利用可能な場合（compose-agent-plugins プラグインに含まれています）、アクセシビリティ、フォントスケール、円形デバイス、その他のマトリックスチェックを委任してください。そうすれば画像をコンテキストに取り込まずに済み、判定結果とパスを伝えられます。対象、ホーム／リビジョン、カタログのルール、求められているカバレッジを伝えてください。利用できない場合は、同じチェックリストを自分で実行し、委任できなかったことを報告してください。 通常のハッシュ確認では、contactSheet: falseのままにしてください。デザインガイドラインとの視覚的な比較を求められた場合はピクセルが必要です。レビュアーがいない場合は、自分のコンテキスト内でも必須フレームを確認してください。関連する個別画像か、範囲を限定した比較シートだけを確認するようにし、ハッシュだけを根拠に視覚的なカバレッジを主張してはいけません。

ソースを編集した後は、render_previewを再度呼び出してください。notify_file_changedは任意です。結果が古いと示された場合は、force: {"reason": "<why>"}を指定して、もう一度だけ呼び出してください。レンダリングを追いかけるために./gradlewやcleanを実行したり、build/ディレクトリを削除したりしてはいけません。強制レンダリングでもまだ問題がある場合は、 mcp.md § Troubleshootingを読んでください（まずcompose-preview mcp doctorを実行します）。

詳細はリクエストがあった場合のみ。 アクセシビリティまたはレイアウトについて尋ねられた場合に限り、details: ["a11y", "layout"]を追加してください。observe=pngは、ファイルを読み込めないクライアント向けにインライン画像を返します。

MCP ツールがない場合は？ CLI を使います：compose-preview show --json --filter <Name>を実行し、エントリーのpngPathを読み取ってください。古い場合は--force=<reason>を一度だけ指定します。cli.mdを参照してください。どちらの方法でも、レンダーツールの出力だけがレンダリング結果です。手作業で作成した HTML、CSS、SVG のモックをレンダリング結果として扱ってはいけません。レンダリングに失敗した場合は、エラーとともに報告してください。

プレビューできない場合（ViewModel または注入されたサービスを受け取る場合）は、状態を持たない内部コンポーザブルの抽出を提案し、それをプレビューしてください （state-hoisting.md）。

インストール／更新（不足している場合のみ）

compose-preview --versionで確認してください。見つからない場合は、このスキルのスタブbash <this skill's dir>/scripts/compose-preview --versionを実行してください。初回実行時に CLI がインストールされ、PATHに追加されます。その他の入手方法、更新方法、Gradle プラグインについてはsetup.mdを参照してください。MCP の接続設定（ローカルサーバーとホストされた 1 つの URL）についてはmcp.mdを参照してください。

プラットフォームスキルとの連携

Android の Wear Compose Material 3 スキル などの公式プラットフォームスキルが、API、依存関係、移行方法を決定します。このスキルが行うのはレンダリングと検証のみです。

• プラットフォームスキルに従います。 使用するコンポーネント、API、バージョンについては、プラットフォームスキルに従ってください。このスキルのリファレンスを、別の API ガイドとして扱わないでください。
• 変更は想定内です。 移行中にハッシュや画像が変わっても、それは回帰ではなく情報です。ブロック要因になるのは、レンダリングの失敗または新たなアクセシビリティエラーのみです。古いスクリーンショットに戻したり、それに合わせて UI を調整したりしないでください。
• カタログのバージョンに注意してください。 ホスト型カタログは固定されたライブラリバージョンをレンダリングするため、プロジェクトの libs.versions.toml と異なる場合があります。catalog-mcp.md § Choosing a component を参照してください。

移行ワークフロー。 編集する前に、各ファイルに対して find_previews_for_file を実行し、render_preview observe=hash でベースラインを記録します。プラットフォームスキルに沿って編集した後、再レンダリングし、失敗と新たなアクセシビリティエラー（get_preview_data kind=a11y/atf）をブロック要因として報告します。主要な画面を 1～3 個選び、変更前と変更後を示し、Wear では小型の円形デバイスと最大のフォントスケールを確認してください。詳細は wear-ui.md § Verification workflow を参照してください。

リファレンス一覧

タスクに必要な項目のみを読んでください。

トピック	参照先
インストール、更新、使用するスキル、Gradle プラグインの適用、コード不要の初期化スクリプト	setup.md
CLI コマンド、--filter/--id/--force、counts の分類、レンダリングファイル名、SVG 出力、Gradle タスク、プレビュー以外のビルド用 build-brief	cli.md
使用する MCP サーバー（ローカルとホスト型 https://preview.coo.ee/mcp の違い）、ローカルサーバーのセットアップ、ツール、履歴、複数ワークスペース、トラブルシューティング	mcp.md
インタラクションループ：セマンティック参照、observe モード、diff_semantics、切り抜き、render_matrix（バリアント／マトリックス）、記録 → テスト、失敗の kind	agent-loop.md
アクセシビリティ（ATF、compose-preview a11y）	a11y.md
レンダリングごとのデータ（a11y、レイアウト、再コンポジション、SVG）	data-products.md
複数プレビュー、GIF、@SettledPreview、スクロールキャプチャ	capture-modes.md
Wear Compose UI／Wear Tiles	wear-ui.md、wear-tiles.md
CMP の :shared モジュール	cmp-shared.md
Android XML ドローアブル／アイコン	resource-previews.md
レンダリングごとの実行時権限	runtime-permissions.md
編集可能なオーバーライド設定	override-knobs.md
ディスプレイフィルター	display-filters.md
Remote Compose、compose-preview rc	remote-compose.md
ホスト型カタログの MCP ツールと権限付与のフロー（serve、チェックアウト不要）	catalog-mcp.md
制限付きサーバーアクセス（compose-preview auth request）	server-access.md
エージェントの許可リスト、PNG のステージング	permissions.md
クラウドサンドボックス	agent-cloud.md
VS Code 拡張機能（人間向け）	vscode.md

CI と PR レビューは、オプトイン方式の関連スキルに含まれています。 compose-preview-ci（ベースライン、PR コメント用 Actions）と compose-preview-review （ベースと head のレンダリングおよび差分）です。追加するには、 setup.md § Which skills を参照してください。