fangdididi/asset-size-matrix

asset-size-matrix は何をしますか？

ひとつのマスターですべてのスロットをカバーし、重要な要素は絶対に切り取らない。そして、ファイルごとにレシートを発行します。

このスキルの概要

ローンチに必要な画像は、1つだけでは済みません。リンクプレビュー、ビデオサムネイル、スクエア投稿、ポートレート投稿、3:4カバー、縦型ストーリー、プロフィールバナー、アプリアイコン、リポジトリプレビュー、場合によっては縦型動画も必要です。それぞれに独自のピクセルサイズ、ファイルルール、そしてインターフェースオーバーレイ（縦フィードの右側にある「いいね！」列、サムネイルの隅にある再生時間バッジ、バナーの上に重なるアバター、アイコンの丸いマスク）があります。

通常、人々はクロップボックスを十数回ドラッグして対応します。その結果はおなじみのものです。9:16バージョンで見出しが半分に切れる、アバターの下にロゴが隠れる、4Kマスターでは読めたテキストがフィードでは3ピクセルになる、2.3MBでリジェクトされたサムネイル、周囲より8dBも静かなショート動画……。

このスキルは、この作業をテーブル化します。すべての出力先は、数字と日付が付いたスロットカードになります。マスターには一度だけマークを付けます。どのボックスを残す必要があるかを指定します。小さなプランナーが、各スロットについて、指定されたボックスをスロットの安全領域内に収める最大のクロップを計算し、クロップが機能しない場合にはその旨を明確に伝えます。そして、エクスポートされたすべてのファイルをカードと照合してチェックします。

解決する問題

• クロップは目視で一つずつ決められるため、一貫性がなく、なぜそのクロップが選ばれたのか誰も説明できません。
• 安全領域は、公開されてCTAボタンの下に隠れてしまうまで忘れられます。
• 「とりあえずクロップ」が、クロップでは対応できないスロット（ワイドレイアウトを9:16に押し込むなど）に適用され、結果的に要素が切れたり、読み取れないほど縮小されたりします。
• テキストサイズはマスター上で判断され、スロットが実際に表示されるサイズでは評価されません。
• ファイルルール（フォーマット、重量、コーデック、フレームレート、ラウドネス）は、アップロードエラーによって初めて判明します。
• プラットフォームの数値は、出典も日付もない古いブログ記事からコピーされます。

使用すべき時

以下のような場合に使用します。

• 1つのデザインを複数のサイズまたは複数のプラットフォームで提供する必要がある場合。
• 「ローンチキット」「ソーシャルパック」「すべてのサイズ」「バナーセット」を求められた場合。
• カバーやサムネイルがアップロード後に頻繁に切れたりぼやけたりする場合。
• ショート動画を、縦型、スクエア、ワイドのバージョンで提供する必要がある場合。
• バッチエクスポートを行い、すべてのファイルが仕様を満たしていることを証明したい場合。

次の目的では使用しないでください。デザインをゼロから作成する（最初にマスターを作成すること）、ビデオコンテンツを編集する（カット、キャプション、色調補正）、公開する。新しいレイアウトが必要なスロットを通知することはできますが、新しいレイアウトを作成するのはデザインの仕事です。

必要なもの

• マスター：理想的には編集可能なソース（Figma/PSD/HTML/SVG/プロジェクトファイル）と、利用可能な最大サイズでのフラットエクスポート。クロップのみのスロットにはピクセル画像だけでも問題ありません。
• 出力先のリスト、または目標（「X、Instagram、ブログでローンチ」など）。
• ビデオスロットの場合：動画ファイル、および自動チェックを行う場合はffmpeg/ffprobeがインストールされていること。
• ヘルパースクリプトscripts/matrix.pyを使用するにはPython 3.8以上（標準ライブラリのみ）。

ステップバイステップ

1. マスターを確認する

master.json（examples/master.jsonを参照）に以下を記録します。

• ピクセル幅と高さ、静止画か動画か。
• 編集可能なソースが存在するか（これはREFLOWのコストを左右します）。
• 利用可能な最大バージョン。チャットで貼られた縮小コピーから計画を立てないでください。

マスターが最大のスロットより小さい場合は、すぐにその旨を伝えます。後でUPSCALEとして表示されます。

2. スロットリストを日付付きで作成する

slots.jsonを作成します（examples/slots.jsonから始めてください）。スロットごとに1つのカード：

フィールド	意味
id	エクスポートファイル名の語幹、例：video-thumb → video-thumb.jpg
w, h	配信するピクセルサイズ；exact: falseは「少なくともこのサイズ、同じアスペクト比」を意味します
safe	プラットフォームUIで覆われるスロットピクセル単位の上、右、下、左のインセット
drop	このスロットに表示すべきでない名前付きボックス（例：アイコンの見出し）
fit	wide（デフォルト、可能な限り多くのコンテキストを保持）またはtight（安全領域を埋める）
display_w	スロットが実際に表示される幅（CSS px単位）、例：グリッド内のサムネイル
min_text_px	display_wで読み取り可能な最小のキャップ高さ
formats, max_kb	許可されるファイルタイプと重量制限
ビデオフィールド	video_codec, audio_codec, pix_fmt, fps 範囲, min_s/max_s, sample_rate, lufs (+lufs_tol), true_peak_max
source	数値の出典

リストのルール：

• 先頭にas_of（今日の日付）を入れます。サイズとオーバーレイは変わります。日付のないカードは噂に過ぎません。
• 各カードを、プラットフォーム自身の最新のヘルプページまたはダウンロード可能なテンプレートと照合します。数値を確認できない場合は、そのまま保持しますが、"source": "unverified"と書き、引き継ぎ時にその旨を伝えます。
• 出力先が不明確な場合のみ、スロットについて質問します。1つにまとめた質問が5つの個別質問より勝ります：「リンクカード、サムネイル、スクエア、9:16ストーリー、バナーを作成します。追加や削除はありますか？」

3. マスターにマークを付ける

引き続きmaster.jsonで、ボックスをマスターピクセルの[x, y, w, h]としてリストします。

• keep: ドロップされないすべてのスロットで表示される必要があるもの（製品、顔、キーアート）。
• text: 各テキストブロック。マスター上の大文字の高さcap_pxを含みます。
• logo: マーク。
• focus: 何もマークされていない場合に中央に配置する点。

ボックスは、デザインツールで測定するか、ソースファイルからレイヤー境界を読み取るか、画像を開いて注意深く推定して取得します。各ボックスには数パーセントの余裕を持たせてください。顔にぴったりと寄り添うボックスは、実際にはあごを切り落とします。

4. すべてのスロットを計画する

python3 scripts/matrix.py plan --master master.json --slots slots.json

各スロットについて、以下の判定結果が得られます。

• CROP: クロップ＋スケールにより、必要なすべての要素が安全領域内に収まります。行にはクロップ矩形と、すぐに使えるffmpegフィルター（crop=w:h:x:y,scale=W:H）が含まれます。
• UPSCALE: クロップは機能しますが、マスターを拡大します。行には必要なマスターサイズが示されます。ソフトな画像を出力する代わりに、より大きなエクスポートかベクターロゴを依頼してください。
• REFLOW: クロップが機能しないか、テキストが表示サイズで読めなくなります。行にart_onlyが含まれている場合、アートワークはきれいにクロップでき、リストされたテキスト/ロゴのみをこの形状に合わせて再設定する必要があります。それ以外の場合は、構成自体を変更する必要があります。

エクスポートする前に、ユーザーにテーブルを見せてください。これが、考えを変えるのに最も安上がりなタイミングです。

5. 各REFLOWを解決する

機能する最も軽い修正を、次の順序で選びます。

1. タイプの再設定: art_only矩形でアートをクロップし、見出しとロゴをスロットの安全領域内に再配置します。min_text_pxを満たすサイズで配置します。
2. 再スタック: ワイドレイアウト（左にテキスト、右にアート）を、編集可能なソースから、同じフォント、色、間隔比率を維持しながら、縦長のレイアウト（上にアート、下にテキスト）に変更します。
3. キャンバスの拡張: ソースファイル内（またはブランドカラーで）の背景を広げて、アートを縮小するのではなく、安全領域に収まるようにします。
4. 小さなスロット用に短縮: アイコンやアバターはマークのみを保持します。2カラムグリッド内の3:4カバーは、より短い見出しが必要になる場合があります。自分でコピーを書き換えないでください。短い行を提案し、所有者に承認を仰いでください。

すべてのスロットがCROP、または意図的で説明可能な例外になるまで、変更のたびにplanを再実行します。

6. エクスポート

• クロップのみのスロット: 計画されたフィルターを適用します（静止画、動画とも）：ffmpeg -i master.png -vf "crop=...,scale=..." link-card.png。
• REFLOWスロット: 編集可能なソースから、スロットの正確なサイズでエクスポートします。
• すべてのファイルに<スロットid>.<拡張子>という名前を付け、1つのフォルダに入れます。そうすればチェッカーが見つけられます。
• 静止画: sRGB、プラットフォームが不明な色に平坦化する場所では透明色なし。max_kbを満たすまで、段階的に品質を下げます。
• 動画: 偶数幅と高さ、yuv420p、カードに別段の指定がない限りソースのフレームレート、カードのターゲットに正規化されたラウドネス。サイズ制限がある場合は、ビットレートを計算します：python3 scripts/matrix.py budget --seconds 58 --max-mb 50。
• その他のレシピはreferences/export-recipes.mdにあります。

7. すべてのファイルをチェックする

python3 scripts/matrix.py check --slots slots.json --dir out/ --loudness

各スロットはPASS、FAIL、CHECK（測定できなかったものがある）、またはMISSINGで返されます。機械的な失敗（間違ったサイズ、フォーマット、重量、ピクセルフォーマット、サンプルレート）は自由に修正してください。コンテンツを変更する失敗（短い時間、よりタイトなクロップ、バックグラウンドノイズを持ち上げる大きなオーディオ）は、所有者の選択が必要です。選択肢とそのコストを提示してください。

8. 実際のサイズで確認する

チェッカーは見ることができません。各スロットをdisplay_wで表示し、安全領域を枠で囲んだコンタクトシートを作成し、それを開きます。

python3 scripts/matrix.py sheet --slots slots.json --dir out/   # out/contact-sheet.html を出力

次の点を確認します。安全線を越えるテキスト、関節（あご、頭頂部、手）で切れた顔、忙しない背景のロゴ、異なるブランドのように見える2つのスロット。

9. 引き渡す

フォルダと短いマニフェストを提供します。

Kit: Tidepool launch, slots as_of 2026-10-24 (2 cards unverified: note-cover, article-cover)
link-card.png       1200x630   184 KB  PASS  crop
video-thumb.jpg     1280x720   402 KB  PASS  reflow: headline re-set at 96 px cap
story-vertical.png  1080x1920  1.1 MB  PASS  reflow: restacked, canvas extended
app-icon.png        1024x1024   61 KB  PASS  from vector logo (raster was 1.6x too small)
vertical-video.mp4  1080x1920  21 MB   PASS  -14.2 LUFS, -1.3 dBTP, 30 fps, 41.0 s
Look: contact-sheet.html (all slots at display size)

例

「このローンチバナーをどこでも機能させたい。」 マスター 4000x2250、見出し左、電話モックアップ右。計画：リンクカードとリポジトリプレビューはCROP；サムネイルはREFLOW（見出しがグリッドサイズで13.5pxの高さしかなく、14px必要）；スクエア、ポートレート、3:4はart_onlyクロップでREFLOW（電話の下に見出しを再設定）；9:16はアートオンリーなしでREFLOW（モックアップが安全列に対して幅広すぎるため、キャンバスを拡張して再スタック）；アプリアイコンはUPSCALE（ベクターロゴを使用）。examples/plan.output.mdを参照。

「YouTubeがサムネイルを拒否し続ける。」 1つのスロット。チェックでは2.4 MB（2 MB制限、1280x721）と表示されます。1280x720で再エクスポート、JPEG品質を95から88に下げる：1.3 MB、PASS。

「同じショート動画をReels、Shorts、ワイドYouTubeカット用に。」 3つのビデオスロット。縦型スロットは、スピーカーが中央にいるため16:9マスターからCROP可能；ワイドカットはマスターそのもの。チェックで44.1 kHzオーディオ（WARN）と-21.9 LUFS（-14に対してFAIL）が判明；正規化して再エクスポート、再チェック。examples/check.output.txtを参照。

ヒント

• マスターに一度マークを付け、master.jsonをデザインファイルと一緒に保管します。次のキャンペーンで再利用できます。
• 2つのプラットフォームが形状を共有していても、オーバーレイが異なる場合は、別々のカードを割り当ててください。
• 1つのエクスポートが複数のフィードに対応する必要がある場合、縦型動画には1つの控えめな安全ボックスを推奨します。
• 数値はパスしても、人の関節を切るクロップは依然として失敗です。ルックステップを信頼してください。
• fit: tightはマークとアイコン用です。それ以外のものはコンテキストを保持する必要があります（wide）。
• 未確認の数値は、静かに信頼するのではなく、マニフェストに表示しておいてください。
• 再エクスポートのたびに、変更したファイルだけでなく、すべてのファイルを再チェックしてください。バッチツールは隣接ファイルを上書きします。