diagram-design 2026のSVG/PNG書き出しがおかしいとき、AI構成図をどう検収する？

症状：HTMLプレビューは正しいのにSVGやPNGが崩れる場合は、元のHTML、書き出しファイル、描画環境を順に照合してください。図の意味が正しいかは、コードや設計資料で別途確認します。 この手順は、プレビューの見た目だけでは納品物を合格と判断できない場合に役立ちます。

エンジニア：Agentが生成した図を、文書やコードリポジトリに載せる人。 文書の管理者：複数形式の書き出しと読みやすさを確認する人。 プラットフォーム担当者：図表の検収をCIに組み込みたい人。

diagram-designのSVG・PNG書き出し検収は、異常が出た工程から始めます

書き出しに問題があるように見えたら、最初に確認するのは図の修正ではなく、異常の発生箇所です。元のHTML、ブラウザーでの表示、SVG、PNGを同じ入力からそろえ、どの段階で差が現れたかを記録します。diagram-designの公式リポジトリとREADMEおよび書き出し手順を参照し、実際に使ったコマンドや対応形式は手元のファイルと公式説明で確かめてください。

症状から調査先を選ぶ

出力先、実行したコマンド、利用したバージョン、入力ファイルを記録してください。これらが不明なままでは、プレビューと納品ファイルの差が書き出し処理によるものか、環境差によるものかを再現しにくくなります。diagram-designの書き出しコマンドの説明に照らして、実際の手順を確認しましょう。

SVGの構造とスタイルは、実ファイルで確かめます

SVGは画像として開いて終わりにせず、テキストとしても確認します。表示範囲を指定する情報が図全体を含んでいるか、文字が出力に残っているか、参照される定義が見つかるかを確認してください。SVGの構造と要素の関係はW3CのSVG仕様を参照できます。

スタイルが消えた、あるいは見た目が変わったときは、SVG内のstyle要素とCSSの内容を調べます。MDNのSVG style要素の説明を手がかりに、書き出し後のファイルに必要なスタイルが保持されているか、参照先が正しいかを確認してください。IDの重複や参照切れが疑われる場合も、ファイルの実際の内容を根拠に判断します。

注意：公式資料に明記されていないレンダラーやAgentとの互換性を前提にしないでください。特定の環境で再現した問題は、その環境、入力、出力ファイルを添えて切り分けます。

PNGは描画環境の違いとレイアウトの問題を分けます

PNGはピクセル画像のため、HTMLプレビューと異なる環境で書き出すと、フォントや拡大率、余白の切れ方、色の見え方に差が出る場合があります。まず元のHTMLに同じ差があるかを調べ、差がなければ、ローカルと納品先で同じ入力を使って再出力し、結果を並べて確認します。

ブラウザーで画面をキャプチャする工程を使う場合は、PlaywrightのページスクリーンショットAPIの説明を参照し、実行時のページと出力画像を記録します。フォントの違いが原因なら描画環境をそろえ、図の要素自体が画像の端で切れているなら、元のレイアウトや表示範囲を修正します。症状だけを見て、すべてをPNG書き出し処理の不具合と決めつけないことが重要です。

実務では、手元のプレビューが整っていたためにPNGをそのまま資料へ貼り、納品先で文字の折り返しや端の切れが見つかることがあります。書き出したファイルそのものを、最終的に使う文書や表示環境で開いて確認すれば、プレビューと成果物の取り違えを防げます。

図の線が示す意味は、コードや設計資料に照らして判断します

ファイルが正常に開き、SVGやPNGの見た目も整っていても、図の内容が正しいとは限りません。ノード、矢印、ラベルをコード、インターフェースの約束、要件、設計資料と照合し、根拠を示せない関係は確定情報にしないでください。Agentが補ったコンポーネントや接続は、確認済みの事実ではなく、確認が必要な仮説として扱います。

長所

• ファイルの問題と、構成図の内容の問題を別々に追えます。
• 接続の根拠をたどれるため、見た目だけを基準にした誤検収を避けられます。

注意点

• 視覚的な確認だけでは、コードにない関係を検出できません。
• 自動検査だけでは、設計上の意味や資料との整合性まで保証できません。

CIでは機械的な失敗と人による判断を分けます

自動化するのは、生成工程が実行できたか、期待するファイルが出力されたか、ファイルを開けるかといった機械的な確認です。GitHub Actionsを使う場合は、ワークフロー成果物の保存方法を参考に、HTML、SVG、PNG、実行ログを後から確認できる形で保存します。

人が確認するのは、文字が読めるか、図全体が欠けていないか、ノードと線の意味が資料に合っているか、最終的な文書で使用できるかです。CIの検査に失敗したら、出力だけを差し替えて済ませず、入力とログを残して、同じ条件で再現できる状態にします。

確認の分担を明確にします。自動検査はファイル生成や構造上の異常を見つけ、人による確認は可読性と意味の正確さを判断します。

よくある疑問

HTMLのプレビューは正しいのに、PNGだけ違って見える場合

同じHTMLを同じ条件で表示し、差がフォント、拡大率、色、切り抜きのどこにあるかを分けて確認します。ローカルと納品先の描画環境で同じ入力から画像を作り、差が環境に追従するかを見ます。実行コマンドと出力画像を保存し、ブラウザー上のプレビューだけで検収しないでください。

SVGに必要な内容が残っているかを調べる方法

SVGをテキストとして開き、表示範囲、文字、スタイル、定義と参照先を確認します。参照されるIDが存在するか、同じIDが重複していないかも調べます。問題があれば元のHTMLと出力SVGを比べ、公式の書き出し説明と実ファイルの両方を根拠に原因を絞ります。

書き出しに成功しているのに、線の意味が違う場合

画像の見た目ではなく、線が示す関係をコード、インターフェース仕様、設計資料と照合します。根拠を確認できない接続は「要確認」とし、Agentが補った内容を確定情報として扱わないでください。検証した根拠も記録すれば、あとから図を更新するときに再確認できます。

図表の検収をCIに組み込む方法

生成コマンドの実行、成果物の有無、SVGやPNGを開けること、ログの保存は自動化できます。失敗時に入力HTMLと出力ファイル、実行ログを保存すれば原因を追いやすくなります。一方、文字の読みやすさや構成上の関係は、人が資料と照合して判断する工程として残します。

まずは手元のHTMLと書き出しファイルを照合し、故障箇所が描画環境にあるのか、図の意味にあるのかを切り分けてください。Agentの実行環境を一時的に用意したい場合は、日本向けのkvmboot利用案内も選択肢になりますが、レンタル環境が書き出し不具合そのものを解決するわけではありません。継続的な重負荷運用や物理接続が必要なら、自前のMacなどを含めて比較し、短期の検証や一時的な実行環境が必要な場合に限って検討してください。運用条件の確認にはkvmbootのヘルプセンターを参照できます。