Figmaや重量級エディタなしで美しいダイアグラムを作成

アプリケーションアーキテクチャやAPI呼び出しシーケンスを描画する必要があるたびに、同じ問題に直面します。Figmaを開いて、半時間かけて角の丸みやフォント、グレーの濃淡を調整するか、あるいはClaudeやChatGPTにMermaidコードを生成してもらえますが、色味がけばけばしいりでレイアウトもおかしな標準的なダイアグラムになってしまいます。

diagram-designリポジトリの作者であるKatherine Laveryは、自身のブログを維持しながらこのルーティンに遭遇しました。毎回ピクセルを手動で移動する代わりに、Claude Code、Pi、Codex向けの指示セットを作成しました。このプロジェクトは、LLMをサードパーティライブラリやJavaScript、重いビルドなしでスタンドアロンのHTMLとSVGを生成する整った植字システムに変えます。

ダイアグラム生成のアプローチを変える理由

このプロジェクトの主なアイデアは、厳格なデザインルールです。通常のプロンプトでは混沌としたブロックが生成されます。diagram-designルールのセットは、モデルに4ピクセル単位のグリッドへの準拠、要素の密度制御、アセントカラーを1〜2のメインノードのみに使用することを強制します。

新しいDSLを学んだり、構文を解明したりする必要はありません。エージェントにサービスアーキテクチャを表示するよう依頼すると、埋め込みSVGを含む готовый HTMLファイルを出力します。ブラウザで直接開いたり、記事内に貼り付けたり、プレゼンテーションにインポートしたりできます。

ツールの4つの主な機能

最初の機能は自動ブランドオンボーディングです。エージェントにサイトのリンク付きでコマンドを渡します。スクリプトはメインページをダウンロードし、スタイルを解析して、背景色、テキスト色、アセントカラーを探し、フォントを読み取ります。設定を保存する前に、ツールはWCAG AA基準に対してコントラストを自動的にチェックします。選択した背景色でテキスト色が見にくい場合、システムは調整されたパレットを提案します。

2番目の機能は既存のダイアグラムの再描画です。.drawio、.mmdファイル、またはMarkdown内に直接含まれているMermaidダイアグラムがある場合、それらをエージェントに送信します。ツールは指定されたフォーマットと対象読者向けにダイアグラムを作り変えます：

• タスクに応じたフォーマットの変更：Figma用のSVG、スライド用のPNG、Webページ用のHTML。
• メディアに応じたサイズの調整：ドキュメント内の狭いイラストからプレゼンテーション用の16:9フォーマットまで。
• 詳細レベルの制御によるノード数の調整：20ブロックを含む元のダイアグラムを7つの主要要素に自動的に削減可能。
• 読者に合わせた用語の複雑さの調整：API Gatewayのような技術用語を、マネージャー向けの「API入口」のような表現に改名。

3番目の機能は27種類の可視化タイプへの対応です。ギャラリーにはアーキテクチャダイアグラム、ERダイアグラム、シーケンスダイアグラム、タイムライン、2x2マトリックス、ファンネルなど、すべてが揃っています。

4番目の機能は組み込みのアクセシビリティです。生成されたSVGファイルにはrole="img"タグ、有効なaria-labelledby属性、一意の識別子プレフィックスが含まれています。同じページで複数のこのようなSVGを安全に埋め込むことができ、DOMの競合がありません。

利用可能な可視化タイプの例

27種類のダイアグラムタイプそれぞれに、ライトミニマリスト、ダークミニマリスト、説明カード付きのエディトリアルの3つのスタイルバリエーションがあります。

アーキテクチャ コンポーネント + 接続	フローチャート 決定ロジック	シーケンス 時間経過に伴うメッセージ
ステートマシン 状態 + 遷移	ER / データモデル エンティティ + フィールド	タイムライン 軸上のイベント
スイムレーン 部門横断フロー	象限 2軸配置	ネスト 包含による階層
ツリー 親 → 子	組織図 所有 + ルーティング	ベン図 集合の重なり
レイヤースタック 積み上げられた抽象化	ピラミッド / ファネル 順位付き階層またはドロップオフ	コンサルタント2×2 シナリオマトリックス · 名前付きセル
レーダー / スパイダー 多軸比較	ループ フライホイール · ハブを囲むステーション	IT現状 レガシーランドスケープ · 最新化
ハイレベル クラスタ上のエンドツーエンドスタック	棒グラフ カテゴリ比較	折れ線グラフ 時間経過によるトレンド
ガント タイムライン上のタスクとフェーズ	散布図 分布と相関	プロセス 複数アクターの逐次的ワークフロー
メダリオン 多層データストレージ	データフロー 役割スコープのパイプラインステップ	DP統合 ソース → コア → コンシューマー
DPセキュリティマトリックス 役割ごとのアクセス権限

スキルアーキテクチャの仕組み

このプロジェクトは「プログレッシブコンテキスト開示」の原則を使用しています。SKILL.mdファイルは目次としてのみ機能します。フローチャートを描画するよう依頼すると、AIは他の26種類のダイアグラムの説明を読み込まずに、type-flowchart.mdファイルのみを読み込みます。

これにより、エージェントの作業コンテキストが不必要な情報で乱雑になるのを防ぎます。応答はより速く生成され、モデルは他のダイアグラムタイプのマークアップルールに惑わされません。

リポジトリ構造は論理的に整理されています：

• references/フォルダには、各ダイアグラムタイプの説明、スタイルガイド、固有のプリミティブが含まれています。
• scripts/には、.drawioファイルとMermaidファイルから構造を抽出するPythonパーサーが含まれています。
• assets/には、ライブ例を確認できる生成されたギャラリーサイトがあります。

インストールと実践的な使用

始めるには、サポートされているAIアシスタントの1つが必要です。

Claude Codeでは、プラグインは次のコマンドで接続します：

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

Piでは、インストールはさらに簡単です：

pi install https://github.com/cathrynlavery/diagram-design

インストール後、通常の会話言語でタスクを формулировкаできます：

"Сделай архитектурную диаграмму приложения: фронтенд, бэкенд, база данных Postgres и кэш Redis."
"Нарисуй последовательность авторизации с обновлением токена при ошибке 401."
"Перерисуй схему из файла platform.drawio для презентации инвесторам, оставь только 6 главных блоков."

完成版のエクスポートは標準的な呼び出しで行います：

/diagram-design:export path/to/diagram.html --png-only --scale=3

スクリプトはPlaywright経由でHeadless Chromiumを起動し、余計なスタイル要素なしでクリーンなレンダリングを生成します。

このプロジェクトが役立つ人

このリポジトリは、開発者、テクニカルライター、スタートアップ創設者にとって優れたヘルパーです。記事を頻繁に書いたり、スライドを準備したり、コードリポジトリのドキュメントを更新したりする場合、このプロジェクトは手作業を何時間も節約してくれます。

ただし、作者はすぐに制限事項も示しています。通常のリスト、before/after比較テーブル、単一ブロックダイアグラムの作成にはこのツールを使用しないでください。このようなタスクには、標準的なテキストやMarkdownのテーブルの方がより迅速で明確です。