Diagram Studio
JSON仕様書を鮮明な図に変換します。外観は完全に設定可能です:
- 手書き風: rough.jsの揺れと手書きフォント。
- クリスプベクター: 揺れなし、サンセリフまたはセリフフォント、ソフトシャドウ。
- その中間も可能。
すべてのテキストはアウトラインに変換されるため、SVGとPNGはどこでも同じように見えます。リンターが重なり、あふれたテキスト、境界線上のラベル、ボックスを通過する矢印を検出します。
すべてバンドルされています: Node 18+のみ必要で、npm installやネットワークは不要です。
SKILL_DIR はこのスキルフォルダ(このファイルを含むフォルダ)の絶対パスを意味します。
node SKILL_DIR/scripts/render.mjs diagram.json --out out/ # → out/diagram.png (2x), .svg, .report.json, .tiles/
0. Codex、Claude Code、または他のエージェントで実行する場合
- SKILL_DIR:
- Codexでは、スキルの短いパスをスキルルートテーブルで展開します(例:
r0/diagram-studio/SKILL.md→~/.codex/skills/diagram-studio)。 - Claude Codeでは、通常
~/.claude/skills/diagram-studioです。 - スクリプトは必ずその絶対パスで呼び出してください。
- Codexでは、スキルの短いパスをスキルルートテーブルで展開します(例:
- 画像の参照は必須です: オリジナル、グリッド、タイル、比較画像。
- Codex: PNGパスを指定して
view_imageツールを使用してください。render.mjsはname.preview.png(≤ 1400 px)を生成するので、自分でリサイズする必要はありません。詳細はname.tiles/*.pngを使用してください。 - Claude Code: Readツールを使用してください。
- リンターの出力だけでレンダリングを判断しないでください。
- Codex: PNGパスを指定して
- サンドボックス対応:
nodeのみ必要です。ネットワーク呼び出しやインストールはありません。- 出力は
--outに配置します。ワークスペース内(例:./diagram-out)に保持してください。 - WebP/HEIC変換はシステムの一時ディレクトリに出力されます。
- ユーザーがパスではなく画像を貼り付けた場合: 添付ファイルのパスが確認できればそれを使用します。そうでなければファイルパスを尋ねてください。ツールは実際のファイルを必要とするためです。
- 完了時: PNG、SVG、JSONの絶対パスをリストアップして、ユーザーが開けるようにしてください。
1. ジョブを選択する
| ユーザーの希望 | ジョブ | 次を読む |
|---|---|---|
| 「この画像をより鮮明に/高解像度に/きれいに」、「赤raw / 再構築 / 复刻 / 高清重建 して」 | A. 画像から再構築。 忠実性優先:特に指示がなければ元のスタイルを保持 | references/rebuild-from-image.md (必須) |
| 「この図を美化/整理 / 美化 して」 | A + 洗練。 Aと同じですが、次に階層、スペーシング、配置を改善 | references/rebuild-from-image.md |
| 説明、コード、メモからの新しい図 | B. 新規図 | references/spec.md |
| 異なる外観(「手書き風にして」「フラットな企業向けに」「ブループリントに」「論文用に」) | C. スタイル変更 | references/style-guide.md |
特定の画像に対しては、デフォルトでそのスタイルに合わせます: 手書き風は手書き風のまま、フラットはフラットのまま、色とフォントカテゴリもそのまま維持します。ユーザーが依頼した場合にのみ外観を変更します。プリセットは出発点であり、制限ではありません。styleOverrides、カスタムパレット、カスタムフォントファイル("fonts")を使用すれば、ほとんどすべての外観を再現できます。要求が真に曖昧な場合(例えば、参照スタイルなしで「美化して」)にのみ、忠実度レベルについて質問してください。それ以外の場合は、デフォルトで 忠実 + より鮮明 にします。
templates/ 内の最も近いテンプレートから始めてください。テンプレートを作業フォルダにコピーし、そのコピーを編集します。プレビューは assets/gallery/ にあります。テンプレートはパターンであり、内容ではありません。そのテキストをすべて置き換え、改行と矢印はソースと完全に同じに保ってください。--expect は置き忘れや言い回しの変更を検出します。
| テンプレート | 内容 |
|---|---|
dense-rebuild.json | 高密度アーキテクチャ画像の再構築:明示的な座標、カード、パネル、マージされたコネクタ、インラインラベル |
pipeline-rag.json | 左から右へのパイプライン:connect、rightOf、自動フィットパネルを含む行 |
layered-architecture-zh.json | 中国語の階層化アーキテクチャ:belowで積み重ねられた行、ファンイン矢印、シリンダー |
flowchart-decision.json | フローチャート:ピル、ひし形、Yes/No分岐、ループバック矢印 |
agent-loop.json | サイクル:曲線矢印、バッジ、楕円ハブ |
auto-layout.json | 座標なし:ELK自動レイアウトとグループ |
2. ループ(すべてのジョブ)
-
まずインベントリを作成します。 すべてのテキスト文字列をそのままリストアップし(
texts.txtとして保存、1行につき1つ)、すべてのノード、すべての矢印(from → to、ラベル)、すべてのグループをリストアップします。何も発明したり削除したりしません。 -
テンプレートから始めて
name.jsonを記述します。 -
レンダリング:
node SKILL_DIR/scripts/render.mjs name.json --out OUT --expect texts.txt -
すべてのERRORを修正します。各エラーには具体的な
→による修正方法が付随します。WARNは意図的でない限り修正し、意図的である場合は該当する要素または矢印に"ignore": ["code"]を追加して抑制します。 -
確認:
OUT/name.pngとOUT/name.tiles/*.pngを確認し、オリジナルと比較します(scripts/compare.mjs)。prompts/visual-review.mdのチェックリストを実行してください。リンターは意味、バランス、忠実度を判断できません。 -
エラーが0になり、読みやすくなるまで(通常2~4ラウンド)ステップ3~5を繰り返します。
-
成果物を納品:
name.png: 2x。印刷用には--scale 3を使用。name.svg: ベクター。name.json: 後で編集できるように保持。
保持した点と改善した点を1行追加します。
3. 60秒でわかる仕様
{
"canvas": { "width": 1600 },
"style": "marker",
"title": "Checkout Service",
"subtitle": "{blue:clients} · {purple:services} · {green:data}",
"elements": [
{ "id": "web", "title": "Web app", "icon": "app-window", "x": 120, "y": 220 },
{ "id": "api", "title": "API", "color": "purple", "emphasis": true, "rightOf": "web", "gap": 160,
"lines": ["`POST /checkout`", { "text": "validates cart", "muted": true }] },
{ "id": "db", "type": "cylinder", "title": "Orders DB", "color": "green", "below": "api", "gap": 120 },
{ "id": "core", "type": "panel", "title": "Backend", "color": "purple", "contains": ["api", "db"] },
{ "id": "n1", "type": "note", "text": "Idempotent by **order id**", "rightOf": "core", "gap": 40 }
],
"arrows": [
{ "from": "web", "to": "api", "label": "HTTPS" },
{ "from": "api", "to": "db", "label": "INSERT", "color": "green" }
]
}
-
要素タイプ:
box(デフォルト)、pill、ellipse、circle、diamond、cylinder、note、card、panel、text、icon、badge、image、path(カスタムSVG形状)、およびレイアウトヘルパーのrow、column、group。 -
各要素の配置 は次のいずれかを使用:
- 左上隅は
x/y、中央はcx/cy。 below/above/rightOf/leftOfにgapを追加。contains。子要素に合わせてパネルを自動フィットします。
サイズは自動です。オリジナルに完全に一致させるには
w/hを設定します。 - 左上隅は
-
テキスト:
titleは太字で、\nで改行します。linesは本文行です。テキスト内のマークアップ:**bold**`code`(コードフォントを使用){green:span}と{muted:span}->(矢印グリフとして描画)
中国語と英語は自由に混在できます。要素ごとに
size、textSize、font、textColor、alignを設定できます。 -
色 はファミリー(
blue purple green orange red teal yellow pink gray navy)、シェード(blue.tint)、#hexまたはプレーンなCSS名(whiteなど)で指定し、color、fill、stroke、textColorで設定します。 -
矢印 は
fromとtoを接続:- 辺を固定し、
"id.right"または"id.right+20"でそれに沿ってスライド。 - ラベル:
label。labelPos(above、below、left、right、またはinline)で配置し、labelAtで微調整。 - 外観:
dash、color、width、head(end、start、bothまたはnone)。 - パス:
via点、points(正確なポリライン)、または"route": "curve"。
- 辺を固定し、
すべてのキーは references/spec.md にあります。
4. 外観:スタイル、パレット、フォント、エフェクト
-
スタイルプリセット:
- 手書き風:
marker(デフォルト)、neat、excalidraw、sketchy、whiteboard、pencil、blueprint、chalk。 - クリスプ:
clean、paper。
任意のプリセットフィールドは
styleOverridesでオーバーライド可能:roughness(0 = 完全に直線)とbowingfillStyle(solid、hachure、cross-hatch、dotsまたはnone)strokeScale、cornerRadiusshadow(none、softまたはhard)font、cjkFont、codeFont、background
- 手書き風:
-
パレット:
marker、pastel、excalidraw、mono、academic、colorblind、modern、blueprint、chalkboard、midnight。オリジナルの色を正確に再現するには、node SKILL_DIR/scripts/palette.mjs original.pngを実行し、結果を貼り付けます。 -
フォント:
- 手書き:
shantell、kalam、caveat、patrick、architects。 - サンセリフ:
inter。セリフ:serif。モノ:mono。 - CJK:
kai(手書き)、kuaile(遊び心)、sans-sc(クリーン)。 - 独自の
.ttf/.otf/.woff:"fonts": {"brand": {"regular": "Brand.ttf", "bold": "Brand-Bold.ttf"}}、その後"font": "brand"。
- 手書き:
-
カタログ:
assets/gallery/styles.png、palettes.png、fonts.png。scripts/catalog.mjsで再生成。 -
アイコン: 1500以上のLucideアイコン。
node SKILL_DIR/scripts/icons.mjs search 数据库 robot queueで検索、icons.mjs sheet a,b,cでプレビュー。 -
オリジナル画像ツール:
grid.mjs: オリジナルに座標を重ねて表示。赤い軸ラベルを読み取ります。ピクセル位置は使用しません。fontmatch.mjs: すべてのフォントのサンプルテキストを、オリジナルの拡大切り抜きと並べて表示。palette.mjs: オリジナルの色を抽出。crop.mjs: ロゴ、写真、スクリーンショットを切り抜いてimage要素として埋め込み。compare.mjs: 並べて比較。--crop x,y,w,hを追加して、両方の画像を同じ領域にズーム。
-
ダークまたは代替バージョン: 同じ仕様を維持し、
palette(midnight、blueprintまたはchalkboard)またはstyleのみを変更し、別の--nameでレンダリング。 -
スライド用(PPT、Keynote):
"canvas": {"aspect": "16:9"}で画像をスライド比率にパディング。"background": "transparent"でアルファ付きPNG。SVGは直接貼り付けも可能。
5. 明確さのルール(常に適用)
- 単語はそのまま 保持: ラベル、コード識別子、中国語の用語。特に指示がない限り、テキストを発明、翻訳、削除しない。
- 階層を可視化:
- ボックスごとに太字のタイトル。
- 識別子は本文または
codeテキストとして。 - 説明は
mutedテキストとして。 - セクションタイトルはそのセクションの色で。
- 色には意味がある: 領域または役割ごとに1つのファミリーを一貫して使用。矢印ラベルは矢印の色を継承。
- 余裕を持たせる:
- ラベル付き矢印で結合された形状間は ≥ 60 px、それ以外は ≥ 24 px。
- パネルは
containsでフィット。 - 境界線上にラベルを配置しない。
- 縮小時も読みやすい:
- テキスト ≥ 18 px(デフォルト: タイトル 30、本文 25、ラベル 24)。
- キャンバス幅 1400–2200 px、アスペクト比 1:2 ~ 3:1。リンターはそれ以外を警告。
- 6ノード以上の長いチェーン: 2~3行に蛇行配置するか、ELK
"direction": "DOWN"を使用。非常に長い1行にはしない。
- 交差を少なく、遠回りをしない。
viaを追加する前に整列と並べ替えを行う。 - 再構築ジョブでは 再設計せず洗練: 配置、スペーシング、階層は改善するが、トポロジー、読みの順序、スタイルのアイデンティティは維持。
6. 完了条件
-
render.mjsが 0エラー を報告。残っている警告は意図的であり、ignoreで抑制されている。 - すべてのインベントリ文字列が存在し、正確にスペルされている(
--expect texts.txtがパスすること)。 - PNGとタイルを確認し、再構築の場合はオリジナルと並べて比較:同じ構造、同じスタイルのアイデンティティ、より鮮明。
- PNG、SVG、JSON を、「保持した点 / 改善した点」の短いメモとともに納品した。
7. トラブルシューティング
node: command not found: Node 18+ をインストール。他には何も必要ありません。- WebP、HEIC、BMP、TIFF入力は、
sips、magick、dwebp、ffmpeg、Python PIL が利用可能な場合に自動変換されます。それ以外の場合は、ユーザーにPNGまたはJPEGを依頼してください。 - 文字が
?と表示される: バンドルされたフォントは、ラテン文字、GB2312中国語、一般的な記号をカバーしています。言い回しを変更するか、その文字を含むフォントを登録してください。 - 各リンターコードとその修正方法については、
references/troubleshooting.mdを参照してください。