koubou

Koubou：App Store スクリーンショットジェネレーター

100 種類以上の実機フレーム、xcstrings によるローカライズ、Apple の寸法にピクセル単位で正確に対応した、HTML/CSS テンプレートを使ってプロ品質の App Store スクリーンショットを生成します。

スクリーンショットはドキュメントではなく、広告です。各スライドでは、ひとつの感情、成果、または悩みを解決できることをアピールします。

このスキルでは、ユーザーの指示が常にデフォルトより優先されます。

クリエイティブの方向性は、デフォルトでは自由です。 すべてのセットが同じ見た目にならないように、このスキルのルールはインパクト、読みやすさ、キャンバスに応じたスケールの実現に活用してください。

ルールの優先順位

このスキルのガイダンスは、以下の順に適用してください。

1. 厳守すべき制約 — 読みやすさ、スケール、サムネイルでの視認性、誠実な製品マーケティング、実際のキャンバスを意識したデザイン
2. 強く推奨されるデフォルト — 多様性、非対称性、重なり、リズム、ありきたりなレイアウトの回避
3. 好みの傾向 — 画一的なデザインを避けるためのヒューリスティックやスタイルのデフォルト。より優れたアイデアによって成果が明らかに向上する場合は、変更してかまいません

デフォルトを変更することで、より優れたスクリーンショットセットを作れる場合は、意図的に変更し、生成前にそのトレードオフを自分で確認してください。

参考ファイル（最初からすべて読むのではなく、必要に応じて参照してください）：

• setup.md — インストールと HTML ランタイムのセットアップ
• design-guide.md — デザイン原則、コピーライティングのルール、CSS のルール、HTML テンプレートの例
• style-intake.md — 質問する前にアプリ本来のビジュアル表現を確認する方法
• style-interview.md — 短く、重要な情報を得られるスタイルに関する質問と会話パターン
• yaml-reference.md — YAML 設定形式、ローカライズ、アセット、デバイス、サイズ
• capabilities-reference.md — koubou の全機能（コンテンツモード、ハイライト、ズーム、グラデーション）

フェーズ 1：セットアップ（無言で自動実行）

まず kou が利用できるか確認してください。すでに kou が動作する場合は、再インストールしたり Python のパッケージ環境に手を加えたりしないでください。

推奨順序：

kou --version 2>/dev/null

kou --version が成功した場合：

• koubou はインストール済みとして扱ってください
• pip、pip3、playwright install は実行しないでください
• ユーザーの環境を先回りして「アップグレード」または「修復」しようとしないでください
• このスキルは HTML 専用であり、このコマンドは安全に繰り返し実行できるよう設計されているため、生成前に必ず kou setup-html を実行してください

kou --version が失敗した場合は、setup.md を読み、環境への影響が最小限の手順に従ってください。

HTML のレンダリングをサポートするには：

• 必ず kou setup-html を使用してください
• 前回 HTML が動作したことを理由に、これを省略しないでください
• playwright install chromium を直接実行しないでください

セットアップに失敗した場合に限り、ユーザーに知らせてください。動作しているインストール環境には決して変更を加えないでください。

フェーズ 2：アプリを確認してから質問する

一般的なスタイルに関する質問から始めないでください。まずアプリ本来のビジュアル表現を確認し、その後、不明な点や曖昧な点だけを尋ねてください。

スタイルに関する質問をする前に style-intake.md を読んでください。以下の順序に従ってください。

2.1 スタイルの把握（スタイルに関する質問の前に必須）

まずローカルプロジェクトのソースを確認します。ユーザーにビジュアルの方向性を尋ねる前に、自動で検索してください。

次のソースを優先してください。

1. Assets.xcassets、アプリアイコン、イラスト、ロゴ、カラーアセット
2. 既存のスクリーンショットとマーケティング関連フォルダー：
   • .maestro/
   • screenshots/
   • AppStore/
   • fastlane/screenshots/
   • marketing/
3. プロダクトのドキュメントとポジショニング：
   • README*
   • CLAUDE.md
   • ローンチ計画、ランディングページのコピー、ドキュメントフォルダー
4. デザイントークンとUIコード：
   • CSS変数
   • SwiftUIのカラー、グラデーション、マテリアル、タイポグラフィの選択
   • Webのテーマファイルと共通デザイン定数
5. 過去のApp Store関連アセットがあれば、それら：
   • 以前のテンプレート
   • 過去のスクリーンショットキャンペーン
   • ローカライズ済みのマーケティングアセット

少なくとも以下の要素を抽出して要約してください。

• 支配的な色とアクセントカラー
• 全体的なコントラスト：ダーク、ライト、混合、落ち着いた色調、鮮やか
• UIの密度：ゆったり、バランスがよい、密度が高い
• 形状の表現：シャープ、柔らかい、角丸、カード主体、フラット
• アイコンとイラストのスタイル
• 見てわかる場合はタイポグラフィの方向性
• コピーのトーン：落ち着いた、技術的、遊び心がある、プレミアム、温かみがある、緊急感がある
• アプリが落ち着いた、技術的、温かみがある、活気がある、洗練されている、遊び心があるなど、どのような印象を与えるか

アプリのスタイルが明確な場合：

• 検出した特徴を平易な言葉でユーザーに要約します
• 汎用的なテンプレートの表現に一から置き換えるのではなく、その方向性を基に制作することを確認します

特徴が不明瞭、見つからない、または矛盾している場合：

• 確認できた内容を伝えます
• 漠然としたデザインに関する質問をするのではなく、不明な点について具体的な追加質問をします

2.2 意図のヒアリング（短く、要点を絞って）

style-interview.md を読み、必要最小限の質問だけをします。会話形式を保ち、一度にすべての質問を並べないでください。

必要に応じて尋ねるスタイルに関する質問：

1. キャンペーンでは、どのような印象を与えたいですか？プレミアム、遊び心のある、エディトリアル、実用的、技術的、温かみのあるものなど。
2. 方向性の参考にしたいApp Storeの事例、ブランド、スクリーンショットセットはありますか？
3. 避けたいビジュアル表現はありますか？派手なグラデーション、グラスモーフィズム、ダークのみ、カードグリッド、遊び心が強すぎるスタイルなど。
4. スクリーンショットでもアプリらしさを保つために、どのビジュアル要素を認識できるようにする必要がありますか？

まだ解決していない場合に限り、任意で尋ねる質問：

5. 希望する書体の方向性、またはフォントの印象
6. ライト、ダーク、混合のどれを重視するか
7. 密度の好み：余白を多くするか、情報を多くするか
8. スライド全体で一貫性を重視するか、目に見える変化を持たせるか

2.3 プロダクト情報（引き続き必須）

スタイルの把握を始めたら、残りの制作に必要な情報を自然に集めます。

1. アプリ：名前、機能（1文）、主な価値提案
2. スクリーンショット：アプリのキャプチャはどこにありますか？まず自動で検索してください。
   • 見つかった場合は、見つけたものを示して確認します
   • 見つからない場合は、ユーザーに生成方法を尋ねます
   • アプリのUIがはっきりわかる、余計なもののないシミュレーターキャプチャを優先します。ユーザーが選べる場合は、最近の6.1インチiPhoneのキャプチャを素材として優先してください
3. 紹介する機能：優先順位を付けた機能・メリットのリスト（3～5個を推奨）。各スライドで1つの機能を紹介します
4. メインビジュアル素材：アプリアイコンなどのブランド素材。尋ねる前に自動で検索してください
5. スライド枚数：スクリーンショットの枚数（まずは3～5枚を推奨。Appleでは最大10枚まで使用できます）

関連する場合に限り、任意で確認する項目：

6. デバイス：デフォルトは iPhone 16 Pro - Black Titanium - Portrait です。iPad／Mac／その他のデバイスが適切な場合にのみ尋ねます
7. ローカライズ：プロジェクトがすでに xcstrings または複数言語への対応を備えている場合に限ります
8. 追加素材：浮遊するUI要素、バッジ、補助イラスト
9. その他の制約：必須の訴求内容、禁止するスタイル、マーケティング上の制約

2.4 スタイルの決定（HTML の作成前に必須）

テンプレートを作成する前に、次の6項目を明確に決定し、内部で確定してください。

• brand signals detected
• chosen campaign style
• copy voice
• background system
• device composition rhythm
• variation plan across slides

各項目は、次のいずれかによって根拠を示す必要があります。

• スタイルの調査で確認したアプリの情報
• インタビューで得たユーザーからの直接のフィードバック

根拠を示せない項目がある場合は、デザインを始める前に、焦点を絞った質問を続けてください。

導出する項目（行き詰まらない限り質問しないでください）

• ブランドカラーと UI の雰囲気に基づく背景のグラデーションやテクスチャ
• レイアウトの配置（ヒーロー → 上部に機能を配置 → 下部に機能を配置 → 交互に配置）
• 機能と価値提案に基づく見出しの文言
• アプリの実際のパレットに基づくセカンダリパレット
• project.device と project.output_size に基づくキャンバスのクラス（kou inspect-frame を使用）
• アプリ名を表示するかどうか。デフォルトでは、読みやすいサイズでブランド価値を実際に高める場合を除き、省略してください
• アプリアイコンを表示するかどうか。デフォルトでは、ヒーローまたはクロージングスライドで控えめに使用し、小さな装飾要素としては使用しないでください

原則：ローカルでコンテキストを取得できる場合は、質問する前に活用してください。スタイルに関する質問は、調査の後に行います。

フェーズ 3：生成

テンプレートを生成する前にdesign-guide.mdを読みます。設定ファイルを作成する前にyaml-reference.mdを読みます。

1. 作業ディレクトリを作成します（例：AppStore/、またはプロジェクトに適した場所）

2. kou setup-htmlを実行します

3. YAMLからproject.deviceとproject.output_sizeを読み取ります。iPhone Duoのような2画面デバイスの場合は、project.displaysのすべての項目を読み取ります（yaml-reference.mdを参照）

4. kou inspect-frame "<device>" --output-size <size> --output jsonを実行します（画面ごとに1回）。CSSを書く前に、そのジオメトリを使用します

5. レイアウトに着手する前に、ナラティブの流れと、各スライドにつき見出し／サブタイトルの候補を2～3個作成します。まず最も優れた候補を選びます。コピーの品質はCSSより先に整えます

6. スタイルの方針をキャンペーンブリーフにまとめます：

   • セット全体でどのような印象を伝えるか
   • 使用可能なモチーフ
   • 使用禁止のモチーフ
   • 最初の5枚でどの程度のバリエーションを見せるか

7. HTMLテンプレートを格納するtemplates/を作成します。異なるレイアウトを最低3種類用意し、最初の3枚のスライドで同じ構成の型を繰り返してはいけません

8. すべてのHTMLテンプレートで、CSSを書く前に以下の要素にdata-kou-idとdata-kou-roleを追加します：

   • メイン見出し：data-kou-id="headline" data-kou-role="headline"
   • 補足コピー：data-kou-id="subtitle" data-kou-role="supporting"
   • メインデバイス画像：data-kou-id="device" data-kou-role="device"
   • 特徴のタイトル／サブタイトル（クロージング／特徴スライド）：data-kou-id="feature-N-title" data-kou-role="feature-title"、data-kou-id="feature-N-sub" data-kou-role="feature-sub"

   これらがないと、レイアウトサイドカーのelements配列が空になり、レンダリング後のQAができません。正しい注釈パターンについては、design-guide.mdのテンプレート例を参照してください。

9. koubouの設定を含むconfig.yamlを作成します（形式についてはyaml-reference.mdを参照）

10. キャンバスとコピーの長さに合わせて調整できるCSSを使用します。vwまたはclamp()を意図的に使い、CSS Grid、重なり、絶対配置のレイヤーを優先し、実際のキャンバス上で最終的な計算済みテキストスケールを確認します

11. HTMLを書く前に：各スライドのテキスト領域／デバイス領域を計画します（キャンバスの何パーセントを各領域に割り当てるか）。領域が明確になるまでCSSを書き始めてはいけません

12. 次を実行します：kou generate config.yaml --output json

13. 生成されたHTMLスクリーンショットごとに、JSON結果からlayout_pathを読み取り、レイアウトを適切と判断する前にサイドカーを確認します

14. レンダリング後のQA（必須 — 省略しないでください）：

    • 生成された各スライドを目視で確認します
    • layout_pathで参照されている各*.layout.jsonサイドカーを開きます
    • design-guide.mdの却下チェックリストに照らして確認します
    • レンダリングされたセットが、一般的なApp Storeの既定スタイルではなく、調査したアプリのスタイルを反映していることを確認します
    • レイアウトJSONは、位置、占有スペース、比率、数学的な重なりといった客観的なジオメトリの確認にのみ使用します
    • 測定対象となるHTMLスライドでelementsが空の場合、注釈が欠落しているか壊れているものとして、テンプレートを修正します
    • 以下を確認します：絵文字アイコンがないこと、同一のカードグリッドがないこと、デバイスが中央からずれていないこと、テキストが最小スケールを下回っていないこと、意図しないデバイスの切り抜きがないこと（ヒーロースライドではデバイスの上端／ノッチが見えること。画面の内容が読み取れること）
    • ロゴ差し替えテストを行います：競合他社向けにも使えるスライドになっていないか確認します
    • スライドに問題があれば、ユーザーに見せる前に修正して再生成します

15. 出力フォルダーを開きます：open <output_dir>

16. 調整が必要かユーザーに尋ねます。すべてを再生成せず、特定のスライドを修正して繰り返します

イテレーションのルール

• ユーザーから特定のスライドの変更を依頼された場合は、そのテンプレートと設定エントリのみを変更します
• ユーザーから全体的なスタイル変更（色、フォント、雰囲気、密度、太さ）を依頼された場合は、すべてのテンプレートを更新します
• 変更後は kou generate config.yaml --output json を再実行し、新しい layout_path の値とサイドカーの整合性を保ちます
• 編集中にリアルタイムプレビューを希望された場合は、kou live config.yaml を使います
• スライドが小さく感じられる場合は、まず拡大するかレイアウトを切り替えます。グラデーションやラベルを追加して問題を隠さないでください
• コピーの都合で文字が極端に小さくなる場合は、コピーを書き直すか、より適したレイアウトを選びます。「テキストを収める必要があった」からといって、遠慮がちなスライドを受け入れてはいけません
• 多様性を高く保ちます。目標はキャンペーンとしての一貫性であり、レイアウトの繰り返しではありません
• 最初のレンダリングに成功しても、出力がデザインルールや却下チェックリストに違反している場合は、作業を終えないでください
• ユーザーから雰囲気の変更を依頼された場合は、以前のデフォルトを擁護するのではなく、品質基準を守りつつセット全体を再解釈します
• スクリーンショットとレイアウト JSON が一致しない場合は、好みの判断にはレンダリング済みのスクリーンショットを優先し、古いジオメトリに基づいてレイアウトを決めつけるのではなく、アノテーションやレンダリングのタイミングを調べます

厳守ルール

必須制約

• 絵文字をアイコンとして使わないでください。CSS の図形（アクセントバー、ドット）またはテキストのみを使います
• 禁止されているコピー表現を使わないでください。「revolutionary」、「seamless」、「unlock」、「game-changing」など
• ロゴ差し替えテストを適用します。競合他社の名前に差し替えても成立するなら、セットの個性が足りません
• すべての HTML テンプレートに data-kou-id アノテーションを付けます。最低限、headline、subtitle、device が必要です。生成後にレイアウトのサイドカーで elements が空なら、アノテーションが不足しています。QA を通す前にテンプレートを修正してください。アノテーションのないスライドをユーザーに見せないでください

スケール

• 縦長の iPhone ポートレート（iPhone6_9、iPhone6_7）では、ヒーロー見出しを >=10vw、サイドレイアウトの見出しを >=10vw、サブタイトルを >=4.5vw にします
• vw または clamp() を使う場合は、ターゲットキャンバスで算出されたサイズが最小値を満たすことを確認します
• コントラストスライドまたはクロージングスライドでは、コンテンツのまとまりがキャンバスの高さの 60% 以上を占めるようにします

強く推奨するデフォルト

• 連続するスライドで、同じ直立した中央配置のスマートフォン構図を使わないでください
• 見出しとデバイスの間に大きな空白帯（キャンバスの高さの >15%）を残さないでください
• 中央配置のデバイスで rotate() と translate() を組み合わせる場合は、レンダリング後も視覚的な中心が意図どおりに感じられるようにしてください
• スライドに重なり、端からはみ出すトリミング、またはレイヤー構成が必要な場合は、単純な中央配置の flex カラムを使わないでください
• CSS を書く前にテキストとデバイスの領域を計画します（design-guide.md の Device-Text Zone Planning を参照）
• カードグリッドを使う場合は、厳密なグリッドがコンセプトに本当に適している場合を除き、配置をずらす、強調する、またはシンプルにします

コンテンツ

• デフォルトで小さなトップラベル、カテゴリラベル、アプリ名のヘッダーを追加しないでください
• 明確に読みやすく、戦略的な意図がない限り、アプリ名を小さな装飾テキストとして表示しないでください
• アプリアイコンを小さな角の装飾として使わないでください。使う場合は、ブランドを示す本格的な要素にします
• 短くするためだけに、不自然で逐語的な、またはこなれていない見出しを使わないでください
• スライドのストーリーとコピーに一貫性が出る前に、レイアウト作業を始めないでください

プロセス

• 最初の 3 枚のスライドがすでに App Store に掲載できる品質に感じられない場合は、提示する前に作業を続けてください
• 技術的にレンダリングに成功しただけの最初の出力を最終版として提示しないでください。必ず design-guide.md の却下チェックリストと照らし合わせて確認してください
• ルールによってクリエイティブの方向性を平坦化しないでください。読みやすさとインパクトがあれば、奇抜でも強い構図は有効です
• 最終結果がより優れ、明確で、アプリ固有のものになるなら、デフォルトを破ってもかまいません
• アプリがその表現に本当に適している場合、またはユーザーが明示的に希望している場合を除き、暗いグラデーション、中央配置のスマートフォン、大きな白い見出しという汎用的なフォールバックから始めないでください
• 同じ機能一覧を持つ競合アプリではなく、このアプリらしい見た目になっている理由を自分自身に説明できるようにしてください

主な技術的詳細

HTML テンプレートでのアセットの使用方法

テンプレート HTML では、{{asset_name}} を使ってアセットを参照します。YAML 設定では、assets: の下にあるファイルパスを asset_name に割り当てます。

Koubou は、HTML テンプレートに渡す前に、設定されたデバイスフレームを使って各画像アセットを自動的に事前レンダリングします。テンプレートには合成済みの画像（デバイスフレーム内のスクリーンショット）が渡されるため、<img src="{{asset_name}}"> で配置するだけです。

特定のスクリーンショットでフレームを無効にするには、その YAML 定義に frame: false を設定します。

テンプレート変数の置換

• YAML の variables: → HTML の {{key}} → ローカライズ可能なテキスト（xcstrings に抽出されます）
• YAML の assets: → HTML の {{key}} → 画像ファイルのパス（デバイスフレーム付きで事前レンダリングされます）

HTML スクリーンショット用のレイアウト JSON

HTML スクリーンショットでは、Koubou は計測したレイアウトジオメトリを含むコンパクトなサイドカー JSON を出力できます。

• 計測対象にする要素には data-kou-id を使用します
• 要素の役割がモデルの解釈に役立つ場合に限り、data-kou-role を使用します
• 注釈は網羅的に付けるのではなく、最小限かつ構造的なものにします
• 初期設定としては、メインの見出し、補足テキスト、主要なデバイス画像またはヒーロー画像に注釈を付けるとよいでしょう

例：

<h1 data-kou-id="headline" data-kou-role="headline">{{headline}}</h1>
<p data-kou-id="subtitle" data-kou-role="supporting">{{subtitle}}</p>
<img data-kou-id="device" data-kou-role="device" src="{{app_screenshot}}" alt="">

生成ワークフロー：

• kou generate config.yaml --output json を実行します
• コマンド出力から layout_path を読み取ります
• 参照先の *.layout.json を開きます

解釈ルール：

• ジオメトリの値は 0..1 の範囲で正規化された比率です
• elements には注釈が付けられたノードのみが含まれます
• overlaps には数学的に求められたボックスの交差のみが含まれます
• このファイルはレイアウトの事実を把握するために使い、好みを判断するためには使いません
• JSON だけを根拠に「小さすぎる」などの主観的なルールを作らず、ジオメトリと実際のスクリーンショットの確認を組み合わせて判断してください

出力構成

{output_dir}/{language}/{device_name}/{screenshot_id}.png

ローカライズされていないプロジェクトでは、言語ディレクトリは省略されます。

デバイスフレーム名

kou list-frames で表示される正確な名前を使用します。よく使われる名前は次のとおりです。

• iPhone 16 Pro - Black Titanium - Portrait
• iPhone 16 Pro Max - Black Titanium - Portrait
• iPad Pro 13 - M4 - Space Gray - Portrait
• iPhone Duo - Night Sky - Outer Closed Portrait と iPhone Duo - Night Sky - Inner Open Portrait（Star White、横向きのポーズ、Outer Open もあります）

次のコマンドで検索します：kou list-frames "iPhone 16"

iPhone Duo

1 台のデバイスに 2 つのディスプレイがあります。外側は 1398x2034、内側は 2007x2853 です（それぞれ横向きのバージョンもあります）。project.displays を使うと、1 つの設定で両方をレンダリングできます。各ディスプレイはそれぞれ専用のフォルダーに出力されます。App Store Connect では両方が同じスクリーンショットセットに保持されます。asc screenshots upload --device-type IPHONE_DUO（asc 5.12.0 以降）を使って各フォルダーをアップロードしてください。canvas_class は duo_outer_portrait または duo_inner_portrait です。内側のキャンバスはほぼ正方形のため、縦長の iPhone テンプレートを再利用せず、その形状に合わせてレイアウトを設計してください。Apple のガイドラインでは、製品画像はそのまま使用するよう求められています。コピーはデバイスの横に配置し、デバイスに重ねないでください。

レイアウト判断のためのフレーム確認

kou inspect-frame "<device>" --output-size <size> --output json を使うと、次の情報を取得できます。

• 実際のフレームサイズ
• 画面の境界と画面の bbox
• セーフマージン
• カバー率
• 向き
• canvas_class

このデータを使って、タイポグラフィのスケール、トリミングの度合い、レイアウトの密度を決めます。

出力サイズ（App Store の寸法）

名前	寸法	デバイス
iPhone6_9	1320x2868	iPhone 16 Pro Max、15 Pro Max
iPhone6_7	1290x2796	iPhone 15/14/13 Pro Max、Plus
iPhone6_5	1242x2688	iPhone 11 Pro Max、XS Max
iPhone6_1	1179x2556	iPhone 16/15/14/13 Pro
iPhoneDuo_Outer	1398x2034	iPhone Duo の外側ディスプレイ
iPhoneDuo_Inner	2007x2853	iPhone Duo の内側ディスプレイ
iPhone5_5	1242x2208	iPhone 8 Plus、7 Plus
iPadPro13	2064x2752	iPad Pro 13" M4
iPadPro12_9	2048x2732	iPad Pro 12.9"
iPadPro11	1668x2388	iPad Pro 11"

カスタム：output_size: [1320, 2868]