図デザイン
自己完結型のHTMLファイル（インラインSVG）として図を作成します。エディトリアルなデザインシステムを備えています。
45種類のビジュアルタイプ。意味パターンは振る舞いを記述し、タイプリファレンスはレイアウトを記述します。
0. 初回セットアップ — スタイルガイドゲート
新しいプロジェクトで最初の図を生成する前に、スタイルガイドがカスタマイズされていることを確認してください。
ブランディングされたプロジェクトに、デフォルトスキンの図を黙って出荷しないでください。
最初に、references/profiles.md に従って、プロジェクトの .diagram-design マーカーを解決してください。マーカーが正常に解決されると、そのプロファイルが選択され、このゲートはバイパスされます。そのリファレンスが、失敗、保護されたデフォルト、および保存動作を管理します。
references/style-guide.md を開き、デフォルトトークンを確認してください。もし出荷時のデフォルト（紙 #f5f5f5、インク #2d3142、アクセント #bf4520）のままである場合は、一時停止してユーザーに尋ねてください:
「これはこのプロジェクトでの最初の図であり、スタイルガイドはまだデフォルトのままです。今すぐカスタマイズしますか？オプション: (a) WebサイトURL、(b) インストール済みスキル、(c) ローカルフォルダ/デザインシステム、(d) トークンを貼り付け、(e) デフォルトを維持、(f) 保存済みプロファイルを読み込み。」
その後、references/onboarding.md の該当セクションに従って分岐します。(f) の場合は references/profiles.md に従います。
スタイルガイドがカスタマイズされた後（またはユーザーが明示的にデフォルトを選択した場合）、以降の実行ではこのゲートをスキップします。先頭のプロファイルヘッダーが、コピーされたアクティブプロファイルを示します。ヘッダーがない場合、セマンティックロールの値またはタイポグラフィファミリーが出荷時のデフォルトと異なる場合は、カスタム未保存 を意味します：ゲートをスキップし、プロファイルとして保存するオプションを提供します。マーカーもヘッダーもないすべてデフォルトのトークンは、ゲートをトリガーします。オンボーディング後、references/profiles.md に従って、名前付きクライアントプロファイルとして保存するオプションを提供します。
1. 哲学
最も高品質なアクションは、たいてい削除です。
図解に適用すると:
- すべてのノードは、明確なアイデアを表します。常に一緒に移動する2つのノードは、1つのノードです。
- すべての接続は情報を運びます。レイアウトから関係が明らかな場合は、線を削除します。
- コーラルは エディトリアルであって、フラグではありません。 図あたり1～2個のフォーカルノード。5つのノードで使用すると、シグナルが消えます。
- 図は、すべてが追加されたときに完成するのではありません。何も削除できなくなったときに完成します。
目標密度: 4/10。 技術的に完全であるには十分。ガイドが必要になるほど密度が高くありません。9ノードを超える場合は、おそらく2つの図です。
2. 使用すべき時
読者が散文、表、箇条書きリストよりも視覚から多くのことを学べる場合に、45のビジュアルタイプ（§3）のいずれかを使用します。
使用すべきでない時:
- 簡単なUnicode図 → wiretextなどの別のプレーンテキストツール。このスキルはこれを提供しません。
- 物のリスト → 表または箇条書き。
- 属性のみのBefore/After → 表。トポロジ変更 → アーキテクチャデルタ。
- 1シェイプの「図」 → 単に文を書いてください。
描く前に、自問してください: 読者は、よく書かれた段落よりも、これから多くのことを学べるでしょうか？ いいえの場合、描かないでください。
3. 選択: 意味パターン、次にビジュアルタイプ
振る舞い、状態、強制、リスクが意味を持つ場合は、最初に references/semantic-patterns.md を読み込み、1つのプライマリパターンを選択します。次に、レイアウトに最も近いビジュアルタイプを選択します。パターンが一致しない場合は、タイプを直接選択します。
| 振る舞いトリガー | 意味パターン → 最も近いタイプ |
|---|---|
| ファンイン、キュー深度、有限容量、ボトルネック | ファンインキュー / ボトルネック → データフロー |
| ステージ間での繰り返される質問 / 入力 / ガバナンス / 出力スロット | セマンティックスロットを持つステージフレームワーク → プロセス |
| 会話や緩い入力が構造化された耐久性のあるアーティファクトになる | 非構造化入力 → 構造化アーティファクト → データフロー |
| 2つのルールトレースが、合格/不合格/スキップ/未到達および最初の分岐点を必要とする | ペアリングされたポリシー評価トレース → フローチャート |
| トラストバウンダリーと、許可/禁止されたイングレスまたはデプロイパス | セキュアなペーブドロード → アーキテクチャ |
| 強制される場所でグループ化されたコントロール | ガバナンス / コントロールカタログ → レイヤースタック |
| 防御が以前のギャップを補い、残留リスクが伝播する | 補償セキュリティレイヤー → レイヤースタック |
| 階層的、IDアドレス可能な分解で、ブロックごとのI/O、制約、コードリンクが必要 | トレーサブルなブロック分解 → ツリー |
| 1つのサブジェクトがフェーズを進行し、待機、リトライ、キャンセル、終端状態を経る | ライフサイクルフェーズマップ → ステートマシン |
パターンはセマンティックプリミティブとそれに課せられたより厳しい予算を所有し、タイプはレイアウト文法を所有します。アニメーションが要求された場合、または順序変更を実質的に明確にする場合にのみ references/animation.md を使用します。静的がデフォルトのままです。
ビジュアルタイプガイド（45）
| 表示したいもの… | 使用するタイプ | リファレンス |
|---|---|---|
| コンポーネントと接続を1つのスナップショットで。ネストされた管理スコープとトラフィックスコープ | アーキテクチャ | type-architecture.md |
| 同期されたBefore / Afterトポロジ間の構造変更。Changes台帳付き | アーキテクチャデルタ | type-architecture-delta.md |
| フェーズまたは部門別のレガシーITランドスケープ。Before 状態を示す | IT現状図 | type-it-state.md |
| 分岐のある決定ロジック | フローチャート | type-flowchart.md |
| アクター間の時系列メッセージ | シーケンス | type-sequence.md |
| 状態 + 遷移 + ガード | ステートマシン | type-state.md |
| エンティティ + フィールド + リレーションシップ | ER / データモデル | type-er.md |
| 時間軸上に配置されたイベント | タイムライン | type-timeline.md |
| ハンドオフを伴う部門横断プロセス | スイムレーン | type-swimlane.md |
| 2軸による配置 / 優先順位付け | クアドラント | type-quadrant.md |
| 3～5つの定量的基準で評価された複数エンティティ | レーダー / スパイダー | type-radar.md |
| 循環カテゴリにわたる1つの定量シリーズ。角度=カテゴリ、半径=マグニチュード | ポーラーチャート | type-polar.md |
| 強化サイクル。最後のステップが最初のステップにフィードバックし、ハブが状態を蓄積する | ループ | type-loop.md |
| 包含 / スコープによる階層 | ネスト | type-nested.md |
| 親 → 子の関係 | ツリー | type-tree.md |
| 人間/エージェント/チームの所有権、報告、ルーティング、エスカレーション | 組織図 | type-org-chart.md |
| 積み重ねられた抽象化レベル | レイヤースタック | type-layers.md |
| 1つのオブジェクトの部品を1軸に沿って分解：分解、開封、組み立て順序 | 分解アクソノメトリック | type-exploded.md |
| 1つのフロアまたはサイトを斜め上から見た図：家具のある部屋、フェーズ別の建物 | アクソノメトリック平面図 | type-axonometric-plan.md |
| セット間の重複 | ベン図 | type-venn.md |
| ランク付けされた階層またはコンバージョンドロップオフ | ピラミッド / ファネル | type-pyramid.md |
| カテゴリ間の定量的比較 | 棒グラフ | type-bar.md |
| 開始合計から終了合計への符号付き貢献による橋渡し（予算ブリッジ、人員デルタ） | ウォーターフォール | type-waterfall.md |
| 全体の一部。相対的なサイズがストーリーとなる | ツリーマップ | type-treemap.md |
| クロス集計データ。塗りつぶしでセルごとの値をエンコード | ヒートマップ | type-heatmap.md |
| 時間の経過に伴う連続トレンド、正確に2つの状態間の変化（スロープグラフ）、シリーズごとの1つの分布（リッジライン）、または複数のスナップショットにわたるランク移動（バンプ） | 折れ線グラフ | type-line.md |
| タイムライン上のタスクとフェーズ | ガントチャート | type-gantt.md |
| 2変数の相関または分布。バブル（3変数）、ビースウォーム（1変数、アイテムごとにドット）、ボックスプロット（グループごとの5数要約）のバリエーション | 散布図 | type-scatter.md |
| コンテナクラスタ上のエンドツーエンドデータスタック | ハイレベル | type-high-level.md |
| データハンドオフを伴うマルチアクター順次プロセス | プロセス | type-process.md |
| 品質レベルとアクセスポリシーを持つ多層データストレージ | メダリオン | type-medallion.md |
| ロールスコープのデータフロー：各パイプラインステップで誰が何をするか | データフロー | type-data-flow.md |
| データプラットフォームの統合トポロジ — ソース → コア → コンシューマ | DP統合 | type-dp-integration.md |
| ロール/コンポーネントごとのアクセス権限マトリックス | DPセキュリティマトリックス | type-dp-security-matrix.md |
| ステージ間で分割およびマージされる量。バンド幅 = 量 | サンキー | type-sankey.md |
| カテゴリ別にグループ化された、1つの観測された効果の原因（根本原因分析） | フィッシュボーン | type-fishbone.md |
| 進化に対するバリューチェーン — 何を構築し、何を購入し、何が動いているか | ウォードリーマップ | type-wardley.md |
| 状態別の仕掛中作業。WIP制限とブロックされたアイテム付き | かんばん | type-kanban.md |
| 人が体験の各段階で何をし、どのように感じるか | ユーザージャーニー | type-journey.md |
| 顧客が行うこと vs サービスが隠すこと。段階ごと、可視性のライン付き | サービスブループリント | type-service-blueprint.md |
| ソフトウェアが実行される場所 — ゾーン、ホスト、アーティファクト、レプリカ、ポート | デプロイメント | type-deployment.md |
| 何が何に依存しているか。ツリーでは表現できないファンインとサイクルを含む | 依存関係グラフ | type-dependency.md |
| 操作、継承、コンポジションを持つクラス（他のUMLルートは別途） | UMLクラス | type-uml-class.md |
| リリースでスライスされたナラティブバックボーン。カットライン付き | ストーリーマップ | type-story-map.md |
| 物理テーブル：SQLタイプ、制約、インデックス、カラムレベルの外部キー | データベーススキーマ | type-db-schema.md |
経験則:
- 3列の表で同じことを伝えられるなら、表を選んでください。
- 2つのタイプが有用に見える場合は、主要な軸を選んでください。意味パターンは、2番目のレイアウト文法ではなく、動作固有のプリミティブを追加する可能性があります。
- 複雑さの予算（§7）を超えている場合は、概要と詳細に分割してください。
描く前に、ガイドでリンクされている選択したタイプリファレンスを常にロードしてください。 上記でルーティングされた場合は、semantic-patterns.md もロードしてください。アニメーションが選択された場合は、animation.md をロードしてください。
描く前に確認
レンダリングする前に、1つの短いメッセージで計画を述べてください：選択したビジュアルタイプ（およびルーティングされた場合は意味パターン）、サイズプリセット、および複雑さの予算（§7）が強制的に除外するもの。ユーザーに連絡が取れる場合は、描く前にリダイレクトさせてください。連絡が取れない場合は、続行し、成果物の横に前提条件をメモしてください。リクエストがすでにタイプ、サイズ、コンテンツを正確に指定している場合のみ、一時停止をスキップしてください。
4. ユニバーサルアンチパターン
これらは、あらゆるタイプの「AIの粗悪な」図を示します:
| アンチパターン | 失敗する理由 |
|---|---|
| ダークモード + シアン/パープルのグロー | デザイン上の決定なしに「技術的に」見える |
| JetBrains Monoを包括的な「開発者」フォントとして使用 | モノは 技術的な コンテンツ（ポート、コマンド、URL）専用。名前はGeistサンセリフ体で。 |
| すべてのノードに同一のボックス | 階層を消去する |
| 図の領域内に浮かぶ凡例 | ノードと衝突する |
| マスキング長方形のない矢印ラベル | 線を透過する |
矢印上の垂直 writing-mode テキスト | 読めない |
| デフォルトとして3つの等幅サマリーカード | 汎用グリッド — 幅を変える |
| 任意の要素へのシャドウ | シャドウはアウト。ボーダーはイン。 |
ボックスの rounded-2xl | 最大半径6～10px、またはなし |
| すべての「重要な」ノードにコーラル | コーラルは1～2個のエディトリアルアクセントであり、シグナリングシステムではない |
| Mermaidのレンダラーレイアウトの再現 | エディトリアルレイアウトを作成する代わりに、自動間隔とルーティングをインポートする |
| §6の6つのコネクタルールの違反 | 自動不合格：斜めの傾き、ストロークに触れるラベル、後続のノードでクリップされたマスク、重なるパス、共有アタッチポイント、非エンドポイントボックスの背後を通過するトランジット |
タイプ固有のアンチパターンは、ガイドでリンクされている各タイプリファレンスにあります。
5. デザインシステム
デザインシステムはスキン可能です。 references/style-guide.md は、色、タイポグラフィ、トークン、およびデフォルトパレットの唯一の情報源です。このファイルはセマンティックロール（paper、ink、muted、accent、link、…）を命名します。ブランドを適用するには、style-guide.md を編集するか、references/onboarding.md のURLベースのフローを実行してください。
以下の仕様やタイプリファレンスで、「ink」、「accent」、「muted」などが言及されている場合は、
style-guide.mdで現在の16進数値を調べてください。
タイプリファレンスのスニペットは、プレースホルダーとしてロールを記述します：{ink}、ロールと不透明度の場合は {ink @ 0.40}、フォントの場合は {node-name}、{sublabel}、{eyebrow}、{arrow-label}、{title}、{callout}。出力する前に、すべてのプレースホルダーを style-guide.md に対して解決してください。
セマンティックロール（概要）
| ロール | 目的 |
|---|---|
paper, paper-2 | ページ背景およびコンテナ背景 |
ink | プライマリテキスト / ストローク |
muted, soft | セカンダリテキスト / ストローク |
accent | ハイライト、アクション、フォーカルエレメント |
link | クリック可能なテキストまたは要素 |
node-bg, node-border | ノード背景および境界線 |
edge, edge-muted | エッジ（線）のストローク |
arrow-fill | 矢印の塗りつぶし |
success, warning, error, info | ステータスシグナリング |
surface-elevated, surface-sunken | 表面の階層（カードなど） |
タイポグラフィ
テキストのレンダリングには、style-guide.md で定義されたフォントファミリーを使用します。デフォルト:
fontFamilyHeading: 見出し用のサンセリフ書体fontFamilyBody: 本文用のサンセリフ書体fontFamilyMono: コード、コマンド、データ用の等幅書体
サイズと間隔
style-guide.md は、スペーシング、ボーダー半径、アイコンサイズのトークンを定義します。デフォルトに依存せず、すべての値はこのファイルから解決する必要があります。
6. コネクタルール
すべての図の種類において、線と矢印はこれらの6つのルールに従わなければなりません:
- 斜め線は禁止。 すべての接続線は、正確に水平または垂直である必要があります。45度の線は許可されません。
- ラベルはストロークに触れてはいけません。 すべてのラベルには、背景に対してレンダリングされるマスキング長方形が必要であり、ラベルテキストと線の間にパディングが必要です。
- マスクは後続のノードによってクリップされてはいけません。 ラベルマスクは、z-オーダーで他のすべての要素の上になければなりません。
- パスは互いに、またはノードと重なってはいけません。 経路は交差する必要がある場合、明確なクリーニングされた交差が必要です。オーバーラップ（共線経路）は禁止されています。
- 共有アタッチポイントは禁止。 各線は、ノード上の独自の専用アタッチポイントを持たなければなりません。
- トランジットは非エンドポイントボックスの背後を通過してはいけません。 接続は、そのソースとターゲット以外のボックスの背後を通過する場合、ルーティングされるか（または回避線が追加されるか）、専用のアタッチポイントが必要です。
コネクタのスタイリングは style-guide.md に従う必要があります：ストローク幅、色（edge、edge-muted）、矢印スタイル（arrow-fill）。
7. 複雑さの予算
各図には、処理できるノードとエッジの数に暗黙の予算があります。推奨値:
- 最小限の複雑さ（1～3ノード）： 図は必要ないかもしれません。文または箇条書きを検討してください。
- 低複雑さ（4～6ノード）： 最適な範囲。クリアな関係性。
- 中複雑さ（7～9ノード）： 管理可能ですが、グループ化または明確なレイアウトが必要です。
- 高複雑さ（10～15ノード）： 危険ゾーン。分割を検討するか、サブグラフを使用してください。
- 過度の複雑さ（16+ノード）： ほぼ常に、複数の図（概要 + 詳細）に分割する必要があります。
予算を超える場合は、まず分割を検討してください。次に、図の一部を詳細図に委任することを検討してください。この図はナビゲーションとして機能する必要があります。
予算はエッジ（接続）にも適用されます。経験則として、ノードあたりのエッジ数は1～2程度に抑えてください。各ノードが5つ以上のエッジを持つ場合は、おそらく複雑すぎます。
8. 出力形式
デフォルトの出力は、レンダリングされたSVGを含む自己完結型のHTMLファイルです。サポートされる形式:
- HTML（デフォルト）： インラインSVGを含む自己完結型ファイル。ビューアに依存しません。
- SVG： スタンドアロンのSVGファイル。オブジェクトとして埋め込むか、直接表示できます。
- PNG： ラスターイメージ。埋め込みまたはドキュメントに適しています。
<format> 引数を使用して出力形式を指定するか、デフォルトに従います。
出力されるすべてのファイルは、図の内容とタイプに基づいて名前が付けられます。出力は現在の作業ディレクトリ、またはプロジェクトに応じて適切な場所に配置されます。
9. インポート
このスキルは、レイアウトをインポートするために、.drawio、Mermaid、および .excalidraw ファイルをインポートできます。
インポートワークフロー:
- ユーザーが
.drawio、.mermaid、または.excalidrawファイルを提供します。 - スキルはファイルを解析し、ノードとエッジを抽出します。
- スキルは、タイプとレイアウトの最良の一致を決定します（マッピングをガイドするために §3 を使用）。
- スキルは、デザインシステム（§5）とコネクタルール（§6）を適用して、エディトリアルレイアウトを生成します。
- 出力は、自己完結型HTMLとして（または要求に応じてSVG/PNGとして）提供されます。
インポートの制限:
- Mermaidのレンダラーレイアウト（自動間隔とルーティング）は再現されません。代わりに、エディトリアルな手動レイアウトが作成されます。
- 複雑なMermaid図（ネストされたサブグラフを持つものなど）は、手動での調整が必要になる場合があります。
- .drawio ファイルは、基本的な形状とコネクタに最適にマッピングされます。高度なカスタム形状は正しくマッピングされない場合があります。
10. プロファイルと保存
プロファイルを使用すると、デザインシステムの設定（色、フォント、サイズ）を保存および再利用できます。
プロファイルの保存:
- オンボーディング後（§0）、名前付きクライアントプロファイルとして保存するオプションを提供します。
- プロファイルは、
references/profiles.mdで定義されたスキームを使用して保存されます。
プロファイルの読み込み:
- プロジェクトに
.diagram-designマーカーがある場合、そのプロファイルが自動的に選択されます（§0）。 - ユーザーは、オンボーディング（§0）または
references/profiles.mdを通じて、保存されたプロファイルを名前で読み込むように要求できます。
プロファイルの構造:
各プロファイルには、少なくとも以下が含まれます:
- プロファイル名（クライアント名など）
- 色の値（
style-guide.mdのすべてのセマンティックロールをオーバーライド） - フォントファミリー
- トークン（間隔、ボーダー半径など）
プロファイルの詳細なフォーマットについては、references/profiles.md を参照してください。
11. 参考文献
利用可能なすべてのリファレンスとガイド:
references/style-guide.md— デザイントークンとスタイルreferences/semantic-patterns.md— 振る舞いのパターンreferences/profiles.md— プロファイルの保存と読み込みreferences/onboarding.md— 初回セットアップフローreferences/animation.md— アニメーション図
タイプリファレンスは references/ ディレクトリにあり、type-<name>.md パターンに従います。主要な45タイプのリストについては、§3のガイドを参照してください。