図のデザイン
自己完結型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）のいずれかを使用します。
使用しない場合：
- 簡単なユニコード図 → wiretextなどの別のプレーンテキストツールを使用してください。このスキルは提供しません。
- もののリスト → 表または箇条書き。
- 属性のみのBefore/After → 表。トポロジ変更 → アーキテクチャ差分。
- 単一シェイプの「図」 → 単に文を書いてください。
描く前に自問してください：「読者は、よく書かれた段落よりもこれから多くを学べるか？」 もし「いいえ」なら、描かないでください。
3. 選択：意味論的パターン、次にビジュアルタイプ
振る舞い、状態、強制、リスクが意味を持つ場合、最初にreferences/semantic-patterns.mdを読み込み、1つのプライマリパターンを選択してください。次に、レイアウトに最も近いビジュアルタイプを選択します。パターンが一致しない場合は、タイプを直接選択します。
| 振る舞いのトリガー | 意味論的パターン → 最も近いタイプ |
|---|---|
| ファンイン、キュー深度、有限容量、ボトルネック | ファンインキュー/ボトルネック → データフロー |
| ステージ全体での繰り返しの質問/入力/ガバナンス/出力スロット | セマンティックスロット付きステージフレームワーク → プロセス |
| 会話や緩い入力が構造化された永続的な成果物になる | 非構造化入力 → 構造化成果物 → データフロー |
| 2つのルールトレースがPass/Fail/Skipped/Not-reachedと最初の分岐を必要とする | ペアのポリシー評価トレース → フローチャート |
| 信頼境界と許可/禁止されたイングレスまたはデプロイパス | セキュアなペーブドロード → アーキテクチャ |
| 強制される場所でグループ化された制御 | ガバナンス/制御カタログ → レイヤースタック |
| 防御が以前のギャップを補償し、残留リスクが伝播する | 補償するセキュリティレイヤー → レイヤースタック |
| 階層的でIDアドレス可能な分解であり、ブロックごとのI/O、制約、およびコードリンクが必要 | トレーサブルなブロック分解 → ツリー |
| 1つのサブジェクトがフェーズを進行し、待機、リトライ、キャンセル、終了状態を経る | ライフサイクルフェーズマップ → ステートマシン |
パターンはセマンティックプリミティブとそのより厳しい予算を所有し、タイプはレイアウト文法を所有します。モーションが要求された場合、または順序変更を実質的に明確にする場合にのみreferences/animation.mdを使用します。静的がデフォルトのままです。
ビジュアルタイプガイド（45種類）
| 表示したいもの… | 使用するタイプ | リファレンス |
|---|---|---|
| 1枚のスナップショットでのコンポーネント+接続。ネストされた管理 vs トラフィックスコープ | アーキテクチャ | 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変数、アイテムごとにドット）のバリエーション | 散布図 | 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タイプ、制約、インデックス、カラムレベルのFK | データベーススキーマ図 | type-db-schema.md |
経験則：
- 3列のテーブルが同じことを伝える場合は、テーブルを選択してください。
- 2つのタイプが有用そうな場合、支配的な軸を選択してください。意味論的パターンは、動作固有のプリミティブを追加するかもしれませんが、2番目のレイアウト文法を追加するわけではありません。
- 複雑さの予算（§7）を超えた場合は、概要と詳細に分割してください。
描画する前に、ガイドにリンクされている選択されたタイプのリファレンスを常に読み込んでください。 上記でルーティングされた場合は、semantic-patterns.mdも読み込みます。アニメーションが選択された場合は、animation.mdを読み込みます。
描画前の確認
レンダリングする前に、選択したビジュアルタイプ（およびルーティングされた場合は意味論的パターン）、サイズプリセット、および複雑さの予算（§7）によって除外されるものを、1つの短いメッセージで計画を示してください。ユーザーに連絡可能な場合は、描画する前にリダイレクトさせてください。そうでない場合は続行し、成果物とともに前提条件をメモします。リクエストがすでにタイプ、サイズ、内容を正確に指定している場合のみ、一時停止をスキップします。
4. 共通のアンチパターン
これらは、あらゆるタイプの「AIの粗い」図面を示します：
| アンチパターン | 失敗する理由 |
|---|---|
| ダークモード + シアン/パープルのグロー | デザイン上の決定なしに「技術的に」見える |
| JetBrains Monoを包括的な「開発者」フォントとして使用 | 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 | セカンダリテキスト、デフォルト矢印、サブラベル |
ink |