technical-svg-diagrams

ブログ記事やドキュメント向けに、一貫したスタイルの技術的な SVG 図を生成します。SVG と併せてアクセス可能なテキスト説明を使用するか、意味のあるインライン図にはタイトル／説明とアクセス可能な名前を付けてください。色だけに頼らないでください。すべての図で、グリッド背景、等幅フォント、控えめな色と意味に応じたアクセント、すっきりとした幾何学的な形状を用いた統一されたビジュアル言語を使用します。

<quick_start>

1. 必要な図の種類（アーキテクチャ、フロー、コンポーネント）を特定します
2. テンプレートとカラーパレットについては、references/svg-patterns.md を読みます
3. 確立されたパターンを使って SVG を生成します
4. 説明的なファイル名を付けて、目的のディレクトリに保存します
5. エクスポートは依頼された場合にのみ行い、利用可能なブラウザーのスクリーンショットツールまたは cairosvg を使用します </quick_start>

<design_system>

カラーパレット

用途	色	16進数
背景	薄いグレー	#fafafa
グリッド線	控えめなグレー	#e5e5e5
プライマリテキスト	ダークグレー	#333
セカンダリテキスト	ミディアムグレー	#666
控えめなテキスト	グレー	#666
枠線／矢印	グレー	#ccc
成功／肯定	緑	#27ae60
エラー／否定	赤	#e74c3c
プライマリアクセント	青	#3498db
警告／サンドボックス	オレンジ	#f39c12
プロセスステップ	紫	#9b59b6

タイポグラフィ

• フォントファミリー： すべてのテキストに monospace を使用します
• タイトル： 14px 太字、#333
• サブタイトル／タグ： 12px、#666、角括弧で囲みます [ LIKE_THIS ]
• ラベル： 10～11px、要素に合った色
• 注記： 最終的な表示／エクスポートサイズに合わせます。意味のある内容を 7～8px に縮小するのではなく、読みやすいテキストを目指してください。最終的な背景でコントラストを確認します。

共通要素

グリッド背景：

<pattern id="grid" width="20" height="20" patternUnits="userSpaceOnUse">
  <path d="M 20 0 L 0 0 0 20" fill="none" stroke="#e5e5e5" stroke-width="0.5"/>
</pattern>

矢印マーカー：

<marker id="arrow" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
  <path d="M0,0 L0,6 L9,3 z" fill="#ccc"/>
</marker>

ノード（内側に点がある円）：

<circle cx="X" cy="Y" r="35" fill="none" stroke="#ccc" stroke-width="2"/>
<circle cx="X" cy="Y" r="18" fill="#COLOR"/>

ボックスコンテナー：

<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#ccc" stroke-width="2"/>

破線コンテナー（サンドボックス／分離）：

<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#f39c12" stroke-width="2" stroke-dasharray="5,3"/>

ラベルボックス：

<rect x="X" y="Y" width="W" height="H" fill="none" stroke="#ccc" stroke-width="1"/>
<text x="CX" y="CY" font-family="monospace" font-size="11" fill="#666" text-anchor="middle">LABEL_NAME</text>

</design_system>

<diagram_types>

アーキテクチャ図

システムコンポーネントを左から右へ示す水平フローです。

用途： 変更前後の比較、システム概要、データフロー

構成：

• 左上にタイトルとタグ
• コンポーネントを左から右へ配置
• 矢印でコンポーネントを接続
• 下部の注記で要点をまとめる

寸法： 800x350 ～ 800x400

フロー図

プロセスのステップを上から下へ示します。

用途： 実行フロー、リクエストのライフサイクル、手順を追ったプロセス

構成：

• 上部にタイトルとタグ
• 破線の垂直ガイド線
• 多角形の矢印付きヘッドでステップを接続
• 分岐にはひし形の判断ノード
• 開始／終了状態には楕円

寸法： 600x700（ステップ数に応じて高さを調整）

コンポーネント図

単一コンポーネントの内部に焦点を当てた図です。

用途： 内部構造、入れ子になった要素、詳細な内訳の表示

構成：

• 外側のコンテナボックス
• 意味に応じた色を使った内側の要素
• コンテナーの上または下にラベルを配置 </diagram_types>

## 図の作成

1. 種類と寸法を決める

   • アーキテクチャ：800x350-400、横向き
   • フロー：600x700+、縦向き
   • コンポーネント：内容に応じて調整

2. SVG 構造を設定する

   <svg viewBox="0 0 WIDTH HEIGHT" xmlns="http://www.w3.org/2000/svg">
     <defs>
       
       
     </defs>
   
     
     <rect width="WIDTH" height="HEIGHT" fill="#fafafa"/>
     <rect width="WIDTH" height="HEIGHT" fill="url(#grid)"/>
   
     
     <text x="40" y="40" font-family="monospace" font-size="14" fill="#333" font-weight="bold">TITLE</text>
     <text x="X" y="40" font-family="monospace" font-size="12" fill="#666">[ TAG ]</text>
   
     
   
     
     <text x="CENTER" y="BOTTOM" font-family="monospace" font-size="10" fill="#666" text-anchor="middle">summary note</text>
   </svg>
   

3. references/svg-patterns.md のパターンを使ってコンポーネントを追加する

4. 矢印で接続する

   • 主要なフローには実線を使用する
   • 二次フロー／戻りフローには破線を使用する
   • 応答の矢印には opacity="0.5" を使用する

5. ラベルを追加する

   • コンポーネント名には SCREAMING_SNAKE_CASE を使用する
   • アクションラベルには lowercase_snake_case を使用する
   • テキストを中央揃えにするには text-anchor="middle" を使用する

6. 内容がわかるファイル名で保存する

   • diagram-before.svg、diagram-after.svg
   • diagram-flow.svg、diagram-architecture.svg

<success_criteria> 図が完成したと判断する条件：

• 一貫したカラーパレットを使用している
• すべてのテキストが等幅フォントである
• グリッド背景が適用されている
• 角括弧付きのタグを含むタイトルがある
• コンポーネントが矢印で適切に接続されている
• ラベルが明確で、適切な位置に配置されている
• 下部に概要の注記がある
• SVG が有効で、正しく描画される
• ラスター出力が必要な場合は、PNG または WebP にエクスポートされている </success_criteria>

## エクスポート形式

SVG の作成後、必要に応じてラスター形式にエクスポートします。

ブラウザー自動化による PNG

ピクセル単位で正確に描画するには、利用可能なブラウザー自動化環境を使用してください。実行環境にブラウザーツールも agent-browser 実行ファイルもない場合は、処理を中断したり新しいツールをインストールしたりせず、代わりに以下の cairosvg の手順を使用してください。

手順 1：HTML ラッパーを作成する

# Resolve this to the directory of the loaded skill, not the current project.
SVG_SKILL_DIR="/path/to/loaded/technical-svg-diagrams"
SVG_CAPTURE_DIR="$(mktemp -d)"
bun run "$SVG_SKILL_DIR/scripts/create-html.ts" --svg diagram.svg --output "$SVG_CAPTURE_DIR/diagram.html" --width 1600

オプション：

• --padding <px> — SVG の周囲に追加する 0 以上のパディング（デフォルト：40、0 も指定可能）
• --width <px> — 描画する SVG の幅（デフォルト：1600）
• --background <color> — 検出された背景を上書きする 16 進数、名前付き、rgb()、または hsl() の色

アセットを埋め込んだ自己完結型 SVG を使用してください。ラッパーは SVG 画像モードを使用するため、スクリプトは実行されず、外部リソースも利用できません。実際のラスター出力を確認してください。背景検出機能は、ルートのスタイルとキャンバス全体を覆う長方形には対応しますが、任意の SVG 描画や合成には対応しません。複雑な画像には明示的な背景を指定してください。Bun または TypeScript の型ストリッピングに対応した最新の Node でスクリプトを実行します。すでにインストールされているランタイムを使用してください。

手順 2：高解像度 PNG をキャプチャする

# Load agent-browser's installed core skill first; use a unique task session.
SVG_CAPTURE_SESSION="svg-capture-$$"
agent-browser --session "$SVG_CAPTURE_SESSION" open "file://$SVG_CAPTURE_DIR/diagram.html"
agent-browser --session "$SVG_CAPTURE_SESSION" set viewport 1800 1200
agent-browser --session "$SVG_CAPTURE_SESSION" wait --fn 'document.querySelector("img").complete && document.querySelector("img").naturalWidth > 0'
agent-browser --session "$SVG_CAPTURE_SESSION" screenshot .container diagram.png
agent-browser --session "$SVG_CAPTURE_SESSION" close

手順 3：クリーンアップする

rm "$SVG_CAPTURE_DIR/diagram.html"
rmdir "$SVG_CAPTURE_DIR"

cairosvg による WebP

軽量で、ブラウザーは不要です。agent-browser が利用できない場合に最適です。

uvx --from cairosvg cairosvg diagram.svg -o diagram.png --output-width 1600
uv run --with pillow python -c "from PIL import Image; Image.open('diagram.png').save('diagram.webp', 'WEBP', lossless=True)"
rm diagram.png

エッジやテキストを正確に保つ必要がある場合は、lossless=True を使用してください。ダウンロードサイズが重要な場合は、出力サイズを比較してください。ロスレス WebP が常にロッシー WebP より小さくなるとは限りません。

代替ツール（利用可能な場合）：

# ImageMagick
convert -background none -density 150 diagram.svg diagram.webp

# librsvg + cwebp
rsvg-convert -w 1600 diagram.svg -o diagram.png && cwebp diagram.png -o diagram.webp

プラットフォームに関する注意：

• macOS：cairosvg が失敗する場合は brew install cairo
• Linux：必要に応じて apt install libcairo2-dev