HTML 図表作成ツールは何をしますか？

自己完結型の .html ファイルを生成します。ファイルには 視覚的に議論する インライン <svg> が1つ含まれており、単に情報を表示するだけではありません。その後、Playwrightでスクリーンショットを撮り、PNGを検査し、問題がなくなるまで修正します。

このスキルのファイル

ファイル	目的	読むタイミング
`references/color-palette.md`	すべての色とブランドスタイル: 唯一の情報源	すべての図表の前に
`references/visual-patterns.md`	各レイアウトパターン（ファンアウト、タイムライン、ツリー...）のスケッチ	設計ステップ2
`references/starter.html`	ページシェル: CSSトークン、テキスト/シェイプクラス、矢印マーカー、各規則の例を1つ	すべての図表の開始点としてコピー
`scripts/render.py`	HTMLをPNGにスクリーンショットし、ジオメトリをリント	編集のたびに実行（「レンダリングと検証」を参照）
`examples/`	完成した2つの図表とそのPNG	密度とスタイルの参考にしたい場合

すべての図表をブランドに合わせて再スタイルするには、color-palette.md（および starter.html の対応するトークン）を編集します。それ以外はすべて普遍的な方法です。

すでに決定している2つの方針（図表ごとに再議論しない）

1. すべてSVG。HTMLはその周りのページのみ。

ボックス、テキスト、矢印、コードブロックはすべて1つの <svg id="diagram"> 内に配置します。接続用のSVGオーバーレイがあるHTML/CSS（flexbox/grid div）でボックスを構築しないでください。

理由: 図表は幾何学の問題であり、矢印は両端に正確な座標を必要とします。すべてSVGの場合、すべてのノードとすべての矢印がファイルに記述された1つの座標系を共有するため、算術で矢印の端点を計算し、数値を編集して修正できます。HTMLボックスの場合、位置はブラウザのレイアウトエンジンから得られます。ソースに含まれておらず、フォントやビューポートの幅によって変化し、コネクタは実行時にボックスを測定するJavaScriptを必要とします。それはデバッグすべき2つ目のプログラムであり、読者のビューポートは検証したものと異なる可能性があります。すべてSVGのコストは現実的ですが、より小さいものです。SVGテキストは折り返されず（<tspan> で自分で改行する）、その幅はレンダリングされるまでわかりません（リントがそれを測定し、オーバーフローを報告します）。

<foreignObject>（SVG内のHTML）はデフォルトではオフです。これはテキストの折り返しを実現できる唯一の場所ですが、ブラウザ外ではレンダリングが一貫せず、リントでチェックできません。ユーザーがシェイプ内に段落を必要とする場合にのみ使用してください。

2. レイアウトにGraphvizやD2を使用しない。座標は手動で配置する。

理由: この方法論では、レイアウトは 概念を反映する ことが求められます。ファンアウト、タイムライン、サイクル、左右比較、自由浮動注釈、説明するステップの横に配置されたコードブロックなど。自動レイアウトエンジンは異なる目標（エッジ交差が少ない階層グラフ）を最適化するため、すべての図表を同じトップダウンの階層構造に平坦化します。これは、このスキルが回避しようとしているまさに「均一なボックス」の出力です。また、バイナリ依存関係を追加し、再スタイルや注釈が難しいSVGを生成します。

例外: 真にグラフ形状の主題（依存関係グラフのように、15以上のノードと多数のクロスリンクがある場合）で、交差が主な問題となる場合。その場合は、dot -Tplain（Graphviz）をノードの座標を取得するためだけに実行し、その後、このスキルのスタイルと規則を使用してノードを自分で描画します。その旨と理由を明記してください。

核となる哲学

図表は議論すべきであり、表示すべきではない。

図表はフォーマットされたテキストではありません。これは、言葉だけでは表現できない関係性、因果関係、流れを示す視覚的な議論です。形状自体が意味を持つべきです。

同型性テスト: すべてのテキストを削除した場合、構造だけで概念が伝わりますか？そうでなければ、再設計してください。

教育性テスト: 誰かがこの図表から具体的な何かを学べますか、それとも単にボックスにラベルを付けているだけですか？良い図表は教えます。実際のフォーマット、実際のイベント名、具体的な例を示します。

深さの評価（これを最初に行う）

設計する前に、この図表に必要な詳細レベルを決定します。

シンプル／概念的な図表

以下の場合に抽象的な形状を使用します。

メンタルモデルや哲学を説明する場合
対象者が技術的な詳細を必要としない場合
概念自体が抽象である場合（例：「関心の分離」）

包括的／技術的な図表

以下の場合に具体的な例を使用します。

実際のシステム、プロトコル、アーキテクチャを図示する場合
図表が教育や説明に使用される場合（例：YouTube動画）
対象者が実際にどのようなものかを理解する必要がある場合
複数のテクノロジーの統合方法を示す場合

技術図の場合、証拠成果物を含める必要があります（以下を参照）。

調査の義務（技術図の場合）

技術的なものを描く前に、実際の仕様を調査してください。

プロトコル、API、フレームワークを図示する場合:

実際のJSON/データ形式を調べる
実際のイベント名、メソッド名、APIエンドポイントを見つける
ピースが実際にどのように接続されているかを理解する
実際の用語を使用し、汎用的なプレースホルダーは使用しない

悪い例: 「プロトコル」→「フロントエンド」良い例: 「AG-UIがイベントをストリーミング（RUN_STARTED、STATE_DELTA、A2UI_UPDATE）」→「CopilotKitがcreateA2UIMessageRenderer()を介してレンダリング」

調査により、図表は正確でかつ教育的になります。

証拠成果物

証拠成果物は、図表の正確性を証明し、視聴者の学習を助ける具体的な例です。技術図に含めてください。

証拠成果物の種類（図表に関連するものを選択）:

成果物の種類	使用するタイミング	レンダリング方法
コードスニペット	API、統合、実装の詳細	黒い長方形 + シンタックスカラーのテキスト（証拠成果物の色についてはカラーパレットを参照）
データ/JSONの例	データ形式、スキーマ、ペイロード	黒い長方形 + 色付きテキスト（カラーパレットを参照）
イベント/ステップのシーケンス	プロトコル、ワークフロー、ライフサイクル	タイムラインパターン（線 + 点 + ラベル）
UIモックアップ	実際の出力/結果を示す	実際のUIを模した入れ子の長方形
実際の入力コンテンツ	システムへの入力を示す	サンプルコンテンツが見える長方形
API/メソッド名	実際の関数呼び出し、エンドポイント	ドキュメントから実際の名前を使用し、プレースホルダーは使用しない

例: ストリーミングプロトコルに関する図の場合、以下を示す可能性があります。

仕様からの実際のイベント名（「イベント1」、「イベント2」ではなく）
接続方法を示すコードスニペット
ストリーミングデータの実際の外観

例: データ変換パイプラインに関する図の場合:

サンプル入力データ（実際の形式。「入力」ではない）
サンプル出力データ（実際の形式。「出力」ではない）
関連する場合の中間状態

重要な原則: 実際のものがどのように見えるかを示すこと。単に何と呼ばれているかだけではありません。

マルチズームアーキテクチャ

包括的な図表は、複数のズームレベルで同時に動作します。国境と通り名の両方を示す地図のように考えてください。

レベル1: 概要フロー

パイプラインまたはプロセス全体を一目で確認できる簡略化された概要。多くの場合、図の上部または下部に配置されます。

例: 入力 → 処理 → 出力 または クライアント → サーバー → データベース

レベル2: セクション境界

関連するコンポーネントをグループ化するラベル付き領域。これにより、「部屋」のような視覚的な領域が作成され、視聴者が何が一緒に属するかを理解するのに役立ちます。

例: 責任別（バックエンド / フロントエンド）、フェーズ別（セットアップ / 実行 / クリーンアップ）、またはチーム別（ユーザー / システム / 外部）でのグループ化

レベル3: セクション内の詳細

各セクション内の証拠成果物、コードスニペット、具体的な例。ここに教育的価値があります。

例: 「バックエンド」セクション内で、「APIレスポンス」とラベル付けされたボックスだけでなく、実際のAPIレスポンス形式を示すことができます。

包括的な図表の場合、3つのレベルすべてを含めることを目指してください。 概要はコンテキストを提供し、セクションは整理し、詳細は教えます。

悪い例と良い例

悪い例（表示）	良い例（議論）
ラベルが付いた5つの均等なボックス	各概念に動作を反映した形状がある
カードグリッドレイアウト	視覚構造が概念構造と一致している
テキストを装飾するアイコン	意味そのものである形状
すべてに同じコンテナ	概念ごとに異なる視覚的語彙
すべてがボックス内	選択的なコンテナを持つ自由浮動テキスト

シンプルと包括的（どちらが必要かを知る）

シンプルな図表	包括的な図表
汎用的なラベル: 「入力」→「処理」→「出力」	具体的: 入力/出力が実際にどのように見えるかを示す
名前付きボックス: 「API」、「データベース」、「クライアント」	名前付きボックス + 実際のリクエスト/レスポンスの例
「イベント」や「メッセージ」のラベル	仕様からの実際のイベント/メッセージ名を含むタイムライン
「UI」や「ダッシュボード」の長方形	実際のUI要素とコンテンツを示すモックアップ
説明に約30秒	約2〜3分の教育コンテンツ
視聴者は構造を学ぶ	視聴者は構造と詳細の両方を学ぶ

シンプルな図表は、抽象的な概念、簡単な概要、または対象者がすでに詳細を知っている場合に適しています。包括的な図表は、技術アーキテクチャ、チュートリアル、教育コンテンツ、または図表自体に教えさせたい場合に必要です。

コンテナ vs. 自由浮動テキスト

すべてのテキストに形状が必要なわけではありません。 デフォルトは自由浮動テキストにします。目的がある場合にのみコンテナを追加してください。

コンテナを使用する場合...	自由浮動テキストを使用する場合...
セクションの焦点である場合	ラベルまたは説明である場合
他の要素との視覚的なグループ化が必要な場合	補足的な詳細またはメタデータである場合
矢印を接続する必要がある場合	近くの何かを説明する場合
形状自体が意味を持つ場合（決定ダイヤモンドなど）	タイポグラフィだけで十分な階層が作成される場合
システム内の明確な「もの」を表す場合	セクションタイトル、サブタイトル、または注釈である場合

タイポグラフィによる階層: フォントサイズ、太さ、色を使用して、ボックスなしで視覚的な階層を作成します。28pxのタイトルは、その周りに長方形を必要としません。

コンテナテスト: 各ボックス要素について、「これは自由浮動テキストとして機能するか？」と自問してください。はいの場合、コンテナを削除します。

設計プロセス（SVGを書く前に行うこと）

ステップ0: 必要な深さを評価する

何よりも先に、これが必要かどうかを判断します:

シンプル／概念的: 抽象的な形状、ラベル、関係性（メンタルモデル、哲学）
包括的／技術的: 具体的な例、コードスニペット、実際のデータ（システム、アーキテクチャ、チュートリアル）

包括的な場合: 最初に調査を行います。実際の仕様、形式、イベント名、APIを調べてください。

ステップ1: 深く理解する

内容を読みます。各概念について、以下を自問してください:

この概念は 何をする のか？（何であるか、ではない）
概念間にどのような関係があるか？
核となる変換またはフローは何か？
誰かがこれを理解するために、何を「見る」必要があるか？（読むだけではなく）

ステップ2: 概念をパターンにマッピングする

各概念について、その動作を反映する視覚パターンを見つけます。各パターンのスケッチと使用上の注意は references/visual-patterns.md にあります。

概念が...の場合	このパターンを使用
複数の出力を生成する	ファンアウト（中心からの放射状の矢印）
複数の入力を1つに結合する	収束（漏斗、矢印が合流）
階層/ネストがある	ツリー（線 + 自由浮動テキスト）
一連のステップである	タイムライン（線 + 点 + 自由浮動ラベル）
ループまたは継続的に改善する	スパイラル/サイクル（開始点に戻る矢印）
抽象的な状態またはコンテキストである	クラウド（重なり合う楕円）
入力を出力に変換する	組み立てライン（前 → 処理 → 後）
2つのものを比較する	左右比較（対比を伴う並列）
フェーズに分割する	ギャップ/ブレーク（セクション間の視覚的な区切り）

ステップ3: 多様性を確保する

複数の概念を含む図表の場合: 主要な概念ごとに異なる視覚パターンを使用する必要があります。 統一されたカードやグリッドは避けてください。

ステップ4: フローをスケッチする

マークアップを書く前に、図を通して目がどのように移動するかを頭の中でトレースします。明確な視覚的なストーリーが存在する必要があります。

ステップ5: HTML/SVGを構築する

ここで初めてファイルを書き、references/starter.html から始めます。20pxグリッドでレイアウトし、何かを配置する前に主要な座標（列、行、ノードの中心）を書き留めます。大規模な図の処理方法については以下を参照してください。

ステップ6: レンダリングと検証（必須）

ファイルを作成した後、図が正しく見えるまでレンダリング・表示・修正のループを実行する必要があります。これはオプションではありません。完全なプロセスについては、以下の「レンダリングと検証」セクションを参照してください。

大規模／包括的な図表の戦略

包括的または技術的な図表の場合、SVGを一度に1セクションずつ構築します。 ファイル全体を1回のパスで記述しないでください。包括的な図表は1回の応答出力制限を超える可能性があり、収まる場合でも、セクションごとに1パス行うことで各セクションに十分な注意を払うことができます。

セクションごとのワークフロー

フェーズ1: 各セクションを構築する

references/starter.html から ファイルを作成 します: <title>、viewBox を設定し、最初のセクションを追加します。
編集ごとに 1つのセクションを追加 し、それぞれを独自の <g id="sec-..."> に配置します。このセクションのレイアウト、間隔、および既存のものとの接続方法を考えます。
説明的なidを使用 します（data-node="trigger"、id="sec-backend"）。これにより、セクション間のエッジが読みやすくなります: data-from="trigger" data-to="router"。
svgの先頭にHTMLコメントとして 座標計画を保持 します（列のx、行のy、セクション境界）。後続のすべてのセクションとすべてのエッジはそこから読み取られ、推測せずに間隔を修正する方法です。

フェーズ2: 全体をレビューする

完成したファイル全体を読み、以下を確認します:

すべての data-from/data-to が、存在する data-node を指定しているか？
間隔はバランスが取れているか、一部のセクションが窮屈で他はまばらになっていないか？
viewBox はすべてを含み、約40pxのマージンがあるか？

フェーズ3: レンダリングと検証（以下を参照）

セクション境界

...（翻訳により省略）

[truncated for translation]

HTML 図表作成ツール