技術ブログの図をSVGで作る仕組みを整えた 技術ブログの図をSVGで作る仕組みを整えた

はじめに

ローカルLLMの連載を書くうちに、図が 16 枚たまりました。

最初は毎回その場で作っていたのですが、同じ迷いを繰り返すので ルールとして書き出すことにしました。配色をどうするか、 文字を何 px にするか、そもそも図を入れるべきか。

この記事は、そのルールと、固めるまでに踏んだ失敗の記録です。

なぜ SVG なのか

図はすべて手書きの SVG です。ツールは使っていません。

• テキストなので差分が読める。 数値を1つ直したとき、何が変わったか git で分かる
• 記事と一緒にバージョン管理できる
• 拡大しても崩れない
• 作図ツールのファイル形式に縛られない

代わりに座標を自分で計算する手間がかかります。 そこが今回いちばん失敗した場所でもありました。

置き場所を決める

使っている静的サイトジェネレータ（Astro）の規約に合わせて、こうしました。

public/img/blogs/<記事のファイル名.md>/<図の名前>.svg

記事からはこう参照します。

![代替テキスト](/img/blogs/2026-09-26-blog-svg-figures.md/shrink-trap.svg)

フォルダ名に .md まで含めるのが既存記事の慣習だったので踏襲しています。 一見おかしいのですが、記事ファイルと図フォルダが1対1で並ぶので、 記事を消すときに図も迷わず消せます。

図の名前は内容がわかる英小文字ケバブケース（shrink-trap、zero-origin）。 連番は使いません。 記事を書き足したときに番号がずれて困るからです。

配色は 1 度決めて使い回す

毎回悩まないよう、既存記事のスタイルに合わせて固定しました。

用途	色
アクセント（主役・1 系列目）	#0d9488
注意・2 系列目	#d97706（文字は #b45309）
見出し・本文	#334155
補足	#64748b
目盛り	#94a3b8
枠線・グリッド	#cbd5e1 / #e2e8f0
背景	#f8fafc

3 色目が必要なときは #4f46e5 を足します。

この 3 色は色覚多様性での見分けやすさとコントラストを検証ツールにかけて 全項目通ることを確認しました。目分量で「たぶん大丈夫」と判断しないための一手間です。

4 色目が欲しくなったら、まず色を足すのではなくグルーピングを見直す。 色で区別しなければ読めない図は、たいてい詰め込みすぎです。

失敗 1: 文字が小さすぎて、全図を作り直した

最初、目盛りを 10.5px、キャプションを 11.5px で作りました。 編集中の画面では普通に読めていました。

狭いプレビュー枠で記事を開いたら、読めませんでした。 12.5px / 11.5px を下限と決めて、全図を作り直しました。

……という話を書こうとして、念のため実際に測ってみたら、理解が間違っていました。

画面幅	図の表示幅	倍率	11.5px の実寸
478 px	327 px	0.41 倍	4.7 px
768 px	705 px	0.88 倍	10.1 px
1024 px 以上	848 px	1.06 倍	12.2 px

デスクトップでは縮んでいませんでした。 むしろ 1.06 倍に拡大されています。 本文カラムの上限が 848px で、幅 800 の SVG はそれより小さいからです。

縮むのは狭い画面でした。478px のとき 0.41 倍まで落ちて、 11.5px は 4.7px になります。これは読めません。

つまり最初に「読めない」と感じたのは、たまたま狭いプレビュー枠で見ていたからでした。 対処（文字を大きくする）は結果的に正しかったのですが、 理由を取り違えたまま全図を直していたことになります。

上の図の 3 行は、いまあなたの画面幅での実際の大きさです。 スマホで読んでいるなら、10.5px の行は読めないはずです。

役割	px
図タイトル	15（bold）
強調した数値	14〜17（bold）
等幅（パス・コマンド）	13
本文・ラベル	12.5
目盛り	11.5

配色の検証ツールは色は見てくれますが、 縮んだ結果が読めるかは教えてくれません。

そして今回分かったとおり、実機で見るだけでも足りません。 「どの画面幅で見たか」で結論が変わります。 デスクトップだけ見て「読める」と判断すると、スマホの読者に読めない図を出します。

失敗 2: 棒グラフの原点が、目盛りの途中にあった

もうひとつ、もっと悪い間違いです。

グリッド線を「5, 10, 15, 20, 25」の位置に引いて、 バーの起点を**いちばん左のグリッド線（=5）**に置いていました。 0 が軸の外にある状態です。

結果、すべての棒が 5 だけ水増しされて見えていました。 22.12 と 5.56 の比が、見た目では 4 倍ではなく 2.4 倍に見えます。

たちが悪いのは、それらしく見えてしまうことです。 目盛りもバーも個別には正しく描けているので、実機で並べて見るまで気づきませんでした。

対策はこうしました。

グリッド線の座標とバーの起点を、同じ計算式から出す。

x0 = 290          # 0 の位置
scale = 16.8      # 1 単位あたりの px
グリッド線: x0 + 値 * scale
バーの幅  : 値 * scale   （起点は必ず x0）

別々に手で書いていると、片方だけ直したときにずれます。

グラフを描くときの約束

失敗から決めたルールです。

• 棒グラフは必ず 0 から。 目盛りの原点とバーの起点を一致させる
• 軸は 1 本だけ。 単位の違う量を左右の軸に分けない。分けたいなら図を 2 枚にする
• 値ラベルは全点に付けない。 端点・最大・最小など意味のある点だけ
• 2 系列以上なら凡例を必ず置く。 色だけで区別させない
• 基準線や「期待値」は彩度のないグレー破線。 データと見分けられるように
• 棒は高さ 20〜26px・角丸 4px、線は 2px、マーカーは r=4 に背景色の縁取り

「単位の違う 2 つを 1 枚に詰めない」は、実際に守って良かったルールです。 ファイルサイズと生成速度を並べたい回があり、素直に**小倍数（2 枚並べ）**にしました。 左右に別の軸を置いていたら、読者に「どちらの軸か」を毎回考えさせることになります。

図を入れる判断

なんでも図にしません。 入れる基準をこう決めています。

入れる価値があるもの

• 構造・位置関係（何がどこにあるか、どこまでが自動でどこからが手作業か）
• 量の比較（内訳、大小関係）
• 時間変化と、そこで起きた想定外

入れないほうがよいもの

• 手順の羅列 — 箇条書きのほうが速い
• コマンドの出力 — コードブロックのほうが正確
• 文章 1 行で済む関係

1 記事あたり 2〜4 枚が目安です。 16 枚を 8 記事で割ると平均 2 枚で、だいたいこの範囲に収まっています。

代替テキストに数値を入れる

alt は「〜の図」で終わらせず、図から読み取れる事実を書きます。

悪い例。

![構成図](...)

いまの書き方。

![掃除前に残っていたもの。本体 0.01 GB だけがアンインストーラの守備範囲で、
バックエンド 1.21 GB・モデル 67.58 GB の計 68.84 GB は手で消す必要がある](...)

長くなりますが、画像が表示されない環境でも内容が伝わるのと、 検索に引っかかるのと、自分で後から探すときに効きます。

確認の手順

最後に必ずやることを決めています。

1. ブラウザで実寸表示して目で見る。 文字の重なり・はみ出し・軸ズレは、 検証ツールでは出ない
2. 狭い画面幅でも見る。 デスクトップだけでは足りない。 400px 前後まで絞って、目盛りが読めるか確かめる
3. 数値が本文と一致しているか照合する
4. alt に主要な数値が入っているか確認する

2 を測るなら、ブラウザのコンソールで一行です。

const w = document.querySelector('article img').getBoundingClientRect().width;
console.log({ 倍率: w / 800, '11.5pxの実寸': 11.5 * w / 800 });

ローカルで見るだけなら、public を静的配信すれば足ります。

npx --yes serve -l 4321 <プロジェクト>/public

この「実機で見る」を省いた回に、上の失敗 2 つを両方やりました。 作った直後の自分は、自分の図が読めてしまうので当てになりません。

まとめ

• 図は手書き SVG。差分が読めて、記事と一緒に管理できる
• 配色は 1 度決めて検証ツールにかけ、あとは使い回す
• 表示倍率は画面幅で変わる。 デスクトップでは 1.06 倍だが、 狭い画面では 0.41 倍まで落ちる。文字は 12.5 / 11.5px が下限
• 棒グラフの原点とグリッドは同じ式から出す。 別々に書くとずれる
• 図を入れるかどうかは判断する。 手順やコマンド出力は文章のほうが速い
• 実機で、しかも狭い画面幅でも見る

この記事を書きながら、自分のルールの根拠が間違っていたことに気づきました。 「本文カラムで 0.8 倍に縮む」と思い込んでいたのが、測ったら 1.06 倍だったわけです。 対処は合っていたので実害はありませんでしたが、 正しい対処と正しい理解は別物だと分かりました。

理由を間違えたまま直したルールは、条件が変わったときに機能しません。 ルールを書き出す価値は、手順が残ることより、 根拠が書かれていて後から検証できることのほうにありそうです。