Twitterカード画像生成エージェントスキル

Twitterカード画像ジェネレーター

X（旧Twitter）のリンクプレビュー（誰かがリンクを共有したときにタイムラインに表示されるカード）に最適化された画像を生成します。Twitterカードは標準のOpen Graphとは異なる固有の画像寸法とレンダリング動作を持ちます。このスキルは、Twitterの2:1アスペクト比とプラットフォーム固有の特性に適応した完全な生成パイプラインをカバーします。

og-image-generatorの6つの生成アプローチと6つのビジュアルスタイルがすべてここで適用されます。唯一の違いは、出力サイズ（1200x675、1200x630ではなく）、X固有の設計適応、タイムラインセーフゾーニング、プレイヤーカードのサポートです。

使用する場面

• ユーザーがX/Twitterのリンクプレビュー、summary_large_image、またはプレイヤーカードのポスター用に**1200×675px（2:1）**の画像を必要とする場合
• ユーザーがtwitter:image、Twitterカード、Xプレビュー画像、ツイートプレビュー、タイムラインカードのデザインについて言及する場合
• ユーザーがダークモード対応のレイアウト、上部60%のコンテンツゾーン、またはXの角丸クロップ用の20pxエッジマスクを必要とする場合
• ユーザーが既にog-image-generatorを使用しており、同じスタイルとパイプラインのTwitter適応版を求める場合

使用しない場面

• 汎用OG画像（1200×630、1.91:1）：Facebook、LinkedIn、Slackなど向け — 代わりにog-image-generatorを使用
• HTMLメタタグの設定のみ（画像ファイルを作成しない） — marketing-skillsのtwitter-cardsを使用
• SVG出力 — Twitterはカード画像にSVGをサポートしていません。PNGまたはJPGを使用してください
• ノーコードビジュアルエディタまたはホスト型API — エージェントパイプラインを実行する代わりにOginifyを使用

呼び出し時：初回使用時は、このスキルがカバーする内容とその重要性を1～2文で述べてからメインの出力を提供します。２回目以降またはユーザーがスキップを要求した場合は、直接メインの出力に進みます。

1. Twitterが画像を消費する方法

Twitterは以下の優先順位で画像を読み取ります：

1. twitter:image — 明示的に設定されている場合、それを直接使用
2. og:image — Twitterカードタグがない場合、OG画像にフォールバック
3. 画像なし — プレーンテキストのリンクプレビュー

重要な洞察：FacebookとLinkedInはtwitter:imageを読み取りません。TwitterだけがTwitterカードタグを読み取ります。つまり、実際のレンダリングパイプラインは共有できますが、メタデータには両方の画像パスが必要です。

2. Twitter画像仕様

カードタイプによる画像表示：

ほとんどのユースケースでは、summary_large_imageを1200x675pxでターゲットにします。

3. 6つの生成アプローチ（Twitter適応）

og-image-generator §1の6つのアプローチはすべてTwitter画像でも機能します。唯一の違いは出力サイズです。このセクションではTwitter固有の適応をカバーします。完全なレンダリングパイプラインのドキュメントについてはog-image-generator §1を参照してください。

3.1 AI画像生成（コア#1）

OGと同じ3部構成のプロンプト戦略ですが、Twitter固有のフレーミングを追加：

パート1 — 視覚的説明：背景、構図、ムード
パート2 — テキスト指定：引用符で囲んだ正確なテキスト、サイズのヒント付き
パート3 — Twitter制約：「1200x675px、2:1アスペクト比、キーテキストは上部60%に、
         ダークモード用に暗い背景が望ましい」

ハイブリッドアプローチ（推奨）：AIが背景/雰囲気を生成し、Satoriがテキストをオーバーレイします。AIモデルがまだ苦手とする中国語テキストや、Twitterの約40%のダークモード使用率によりテキストの正確さがより重要になる場合に特に有効です。

完全なAIツール比較表（GPT Image 2.0、Flux、Nano Banana、DALL-E 3、Midjourney）についてはog-image-generator §1.1を参照してください。

3.2 エージェントネイティブのコンテンツ認識ワークフロー（コア#2）

OGと同じ6ステップのワークフロー（§1.2）：コンテンツの読み取り → スタイルのマッチング → 視覚要素の抽出 → 生成の選択 → 生成 → 検証。各ステップにTwitter固有の追加事項：

ステップ2（スタイルのマッチング） — Twitterのダークモードを考慮：暗い背景のスタイル（ターミナル/CLI、ミッドナイトインクマガジン、ブルータリストダークモード）またはX用のダークバリアントを持つスタイルを優先します。

ステップ3（視覚要素の抽出） — Twitterのモバイルでのタイムラインクロップが約1:1になるため、最も重要な視覚要素は正方形内で機能する必要があります。1200x675で機能する水平なデータリボンでも、正方形クロップでは見えなくなる可能性があります。1:1でもよく読める要素を少なくとも1つ抽出します。

ステップ4（生成の選択） — 同じ決定木。AI生成の場合：「テキストはTwitterのモバイルレンダリング幅約260pxに耐えられるか？」を追加。

ステップ6（検証） — OGチェックとTwitter固有のチェック（§8）の両方を実行します。

3.3 Satori + resvg（コードベース）

OGと同じパイプライン。高さを630から675に変更。完全な実装についてはog-image-generator §1.3を参照。

// 共有エンドポイントがOGとTwitterの両方に対応：
export async function GET(req: Request) {
  const { searchParams } = new URL(req.url);
  const title = searchParams.get('title') ?? 'Default';
  const platform = searchParams.get('platform') ?? 'og'; // 'og' | 'twitter'

  const width = 1200;
  const height = platform === 'twitter' ? 675 : 630;

  return new ImageResponse(
    <OgTemplate title={title} height={height} />,
    { width, height },
  );
}

次にページのメタデータで：

const ogUrl = `/og?title=${encodeURIComponent(title)}`;
const twitterUrl = `/og?title=${encodeURIComponent(title)}&platform=twitter`;

export const metadata: Metadata = {
  openGraph: {
    images: [{ url: ogUrl, width: 1200, height: 630 }],
  },
  twitter: {
    card: 'summary_large_image',
    images: [twitterUrl],  // Twitter固有の1200x675
  },
};

3.4 Puppeteer、マネージドサービス、JSON設定

OGと同じ — ビューポート/高さを630ではなく675に設定。og-image-generator §1.4–1.6を参照。v3ページ優先度システム（S/A/B/C）とパイプライン選択については、content-strategy.md と pipeline-guide.md を参照してください。

4. X固有のデザイン考慮事項

TwitterはFacebook/LinkedInとは異なる方法で画像をレンダリングします。以下の点を念頭にデザインしてください：

ダークモード（約40%のユーザー）：画像はフィード内にインラインで表示され、ツイートに囲まれます。暗い背景は自然に溶け込み、明るい背景は目立ちますがダークモードでは不快に見えることがあります。すべてのテンプレートにダークバリアントまたはダークフレンドリーなデフォルトが必要です。6つのスタイルのうち、ターミナル/CLI、ミッドナイトインクマガジン、ブルータリスト（黒背景）は自然とダークモードフレンドリーです。スイスミニマルと新聞はダークモード用の代替バージョンを用意すべきです。

タイムラインクロップ（モバイル）：モバイルでは、summary_large_image画像はツイートが展開されるまでタイムラインで約1:1にクロップされます。完全な2:1画像はタップしたときにのみ表示されます。最も重要なコンテンツ（タイトル、プライマリビジュアル）を画像の上部60%に配置します。つまり、クロップ後も残る中央の正方形領域です。決して重要なテキストを下部20%に置かないでください。

小さなサイズでのテキストの可読性：タイムライン画像はモバイルフィードで約260px幅で表示されます。テンプレートを1/4スケール（約300px幅）でテストし、テキストが読み取り可能であることを確認します。これはOGの約500pxのデスクトップフィードサイズよりも厳しい条件です。

エッジマスク：Twitterはカード画像に微妙な角丸マスクを適用します。エッジから20px以内に配置されたロゴや重要な要素は部分的にクリップされるリスクがあります。

Twitter用の推奨テンプレート適応（スタイル別）：

5. プレイヤーカードのポスター

ビデオ/オーディオコンテンツの場合、playerカードタイプはポスター画像が必要です：

<meta name="twitter:card" content="player">
<meta name="twitter:player" content="https://example.com/player.html">
<meta name="twitter:player:width" content="480">
<meta name="twitter:player:height" content="480">
<meta name="twitter:image" content="https://example.com/poster.jpg">

ポスター画像はユーザーが再生をタップする前に表示されます。魅力的なサムネイルとしてデザインします — 再生ボタン（中央の三角形の円）、ビデオタイトル、コンテンツのフレームを含めます。同じ2:1比率の推奨が適用されます。再生ボタンは中央の正方形ゾーンで最大の要素であるべきです。

AI生成ポスターの場合：「中央に再生ボタン、上部3分の1にタイトルテキスト、暗い背景、1200x675pxのビデオサムネイル」とプロンプトします。

6. スタイルシステム（OGと共有 — 16スタイル）

Twitter画像はog-image-generator §3およびreferences/style-system-v3.mdの16のビジュアルスタイルを使用します。すべてのテンプレートはTwitterで機能します — キャンバスの高さを675pxに変更するだけです。

Xトップパフォーマー：ターミナル、ブルータリスト、ネオブルータリズム、ダークグラデーション、ヴェイパーウェイヴ — ハイコントラスト+暗背景がXタイムラインに最適です。X回避：ダークバリアントのない過度にコーポレートなブランドスタイル；ダークモードタイムラインでの真っ白な背景。

7. フォントとタイポグラフィ

OGと同じルール。og-image-generator references/typography.mdを参照。

Twitter固有の追加：タイムライン画像が約260px幅でレンダリングされるため（OGのデスクトップフィードでの約500pxと比較して）、最小フォントサイズを4px大きくし、24pxではなく28pxを最小にします。

8. エージェントYAMLチェック

checks:
  # P0 — 必須
  - id: dimensions-twitter
    description: twitter:imageが1200x675px（2:1）または1200x628px（クロスプラットフォーム）
  - id: card-type-match
    description: 大きな画像を使用する場合、twitter:cardがsummary_large_image
  - id: absolute-url
    description: twitter:image URLが絶対URL（https://）で、公開アクセス可能
  - id: format
    description: 画像形式がPNG、JPG、またはWebP（SVGではない）

  # P1 — すべき
  - id: og-fallback
    description: og:imageも設定されている（twitter:imageを読み取らないプラットフォーム用のフォールバックとして）
  - id: timeline-safe-zone
    description: 重要なテキストと主要な視覚アンカーが上部60%内にある；下部20%に重要なものがない
  - id: square-crop-survival
    description: 最も重要な視覚要素が1:1の中央クロップで正しく読み取れる（モバイルタイムライン）
  - id: dark-mode
    description: テンプレートにダーク背景バリアントがあるか、ダークフレンドリーなデフォルトスタイルを使用している
  - id: edge-mask-clearance
    description: ロゴと重要な要素がすべてのエッジから20px以上離れている（Twitterの角丸マスク）

  # P2 — あれば良い
  - id: cross-platform-compatible
    description: 同じ画像（1200x628px）がOGとTwitterの両方で別々に生成せずに機能する
  - id: ai-text-validated
    description: AI生成の場合、すべてのテキストがソースと照合されており、幻覚や誤字がない
  - id: player-poster
    description: プレイヤーカードページに再生ボタン付きの専用ポスター画像がある
  - id: content-aware-twitter
    description: 画像がページ固有のコンテンツを反映しており、単なるTwitterサイズのテンプレートにタイトルだけではない

9. よくある間違い

1. 誤ったアスペクト比：OGの1200x630（1.91:1）を調整せずに使用。Twitterは許容しますが、1200x675（2:1）の方がカードをより良く埋め、レターボックスを回避します。
2. twitter:imageタグの欠落：OGフォールバックだけに依存 — 明示的なtwitter:imageがないと、Twitterがどの画像を選ぶかの制御を失います。
3. 下部20%のテキスト：Twitterはモバイルで画像を約1:1にクロップします。下部近くの重要なテキストはタイムラインで切り取られます。
4. ダークモードの考慮不足：明るい背景の画像は、約40%のユーザーが有効にしているTwitterのダークモードタイムラインで不快に見えます。
5. SVGの使用：Twitterはカード画像にSVGをサポートしていません。常にPNGまたはJPGを出力してください。
6. 静止した最初のフレームがないGIF：TwitterはGIFの最初のフレームのみを表示します。フレーム1が意味のある静止画像であることを確認してください。
7. 260pxビューでのAIテキストの幻覚：フルサイズでは正しく見えるAI生成テキストでも、小さくレンダリングされると文字化けする可能性があります。1/4スケールで検証してください。
8. エッジに接触するロゴ：Twitterの角丸マスクがエッジから約10pxをクリップします。ロゴはエッジから20px以上離してください。

10. テスト

• カードバリデーター：https://cards-dev.twitter.com/validator — カードがどのようにレンダリングされるかを正確に表示します。任意のURLを貼り付けてプレビューします。
• 手動テスト：テストアカウントからリンクをツイートし、タイムラインと展開ビューを確認します。
• ダークモードテスト：ライトモードとダークモードのTwitterクライアントでカードを確認します。
• キャッシュバスト：Twitterはカードデータを積極的にキャッシュします（最大7日間）。変更後は、カードバリデーターを使用して強制的に再スクレイプします。
• モバイルクロップテスト：1:1アスペクト比（中央675x675にクロップ）でカードのスクリーンショットを撮り、正方形クロップがページのコンテンツを伝えているか確認します。

11. 関連スキル

これらのスキルはオプションです — このスキルは単独で機能します。追加機能が必要な場合にインストールしてください：

同じリポジトリ（常に一緒にインストール）：

• og-image-generator：OG画像生成（1200x630、1.91:1） — 完全なレンダリングパイプライン、全6スタイル、シードテンプレート、タイポグラフィガイド、Satoriの制約。このTwitterカードジェネレーターはそのインフラ全体を再利用します。

別のリポジトリ（インストールされている場合とされていない場合がある）：

• twitter-cards (marketing-skills)：twitter:card、twitter:site、twitter:creator、検証のためのHTMLメタタグ設定。タグの設定方法を処理します。このスキルは画像の作成方法を処理します。
• open-graph (marketing-skills)：og:title、og:image、og:url、プラットフォームテストツールのHTMLメタタグ設定
• social-share-generator (marketing-skills)：ユーザーがXにリンクを共有する際にTwitterカードデータを消費する共有ボタンUI