svg-figure

SVG 図

SVG の模式図や図解（フローチャート、プロセス図、システム図、解剖図）の規約です。要素の一貫性を保証します。テキストはボックスの境界に沿って配置され、矢印は対象を指し、線は重なり順で図形の下を通ります。出力される SVG は、figures:scientific-figure スキルでパネルとして組み合わせ、figures:figure-qa エージェントの SVG ブランチで検証することを想定しています。

このスキルを使う場面

新規のプログラムによる作業では、代わりに figures:svg-primitives を使ってください。 以下の規約をすべて機械的に保証します。テキストはボックスに自動で収まり、矢印の先端は曲線上で正しい接線方向を保ち、描画順は決定的であり、これらの不変条件に違反すると Canvas.save(validate='strict') が例外を発生させます。このスキルの examples/schematic_from_primitives.py は、プログラムによる作成の標準的な例です。

次の場合はこのスキルを使ってください。

• SVG を手作業で作成する場合や Inkscape などのエディターを使う場合で、figure-qa エージェントが想定する規約が必要なとき。
• Python 以外のツールで SVG を出力し、その形状について知りたいとき。
• 外部の共同作業者が作成した SVG を読み、レイアウトの文法を理解したいとき。
• svg-primitives 以外で作成した SVG について、figure-qa の指摘をデバッグするとき。
• 図が数値をプロットしたものではなく、模式図（ボックス、矢印、ラベル）の場合。プロットには figures:plot-styling を使ってください。

次の場合は別のツールを使ってください。

• Python で作成する場合 → figures:svg-primitives を使います。
• データのプロットの場合 → figures:plot-styling を使います。
• 絵画的な背景（脳、顕微鏡、実験セットアップの写真風表現）の場合 → 背景には figures:ai-full-figure を使い、ラベルを figures:svg-primitives で重ねます。
• 複数のパネルで繰り返し使うアイコン風の要素が必要な場合 → figures:transparent-icons でアイコンを生成し、SVG 内で <image> 参照として配置します。

プログラムによる作成（推奨方法）

figures:svg-primitives を参照してください。このスキルの標準的な例は examples/schematic_from_primitives.py です。Canvas、LabeledBox、Arrow.connect、Annotation を使って examples/schematic.svg を再現します。実行方法：

cd plugins/figures/skills
uv run --with drawsvg --with svgpathtools --with Pillow --with fonttools \
    --with cairosvg --with lxml \
    python svg-figure/examples/schematic_from_primitives.py

手作業で作成する場合の規約

以下の手順は、SVG を手作業で記述する場合、または Python 以外のツールで出力する場合に適用されます。figures:svg-primitives はこれらをすべて機械的に適用します。このセクションは、基盤となる SVG 規約のリファレンスであり、任意の SVG 入力を検証するときに figure-qa エージェントが想定する内容です。

1. サイズ

width／height と、それに対応する viewBox を明示的に設定し、ユーザー単位が mm と一致するようにします（figures:scientific-figure が合成に使う規約と同じです）。

<svg xmlns="http://www.w3.org/2000/svg"
     width="89mm" height="60mm" viewBox="0 0 89 60">
  ...
</svg>

これで、SVG 内のすべての座標が mm 単位になります。font-size も含まれます（ポイントではなく、ユーザー単位で表す長さです）。<rect width="20" height="10"> は 20mm × 10mm、<text font-size="9"> は高さ 9 mm（約 25 pt）です。物理的なポイント数を指定するには、N pt = N × 25.4/72 mm に換算します。つまり、6 pt は font-size="2.1"、Nature の最小値である 5 pt は font-size="1.76" です。figure-qa は物理的なポイント数を報告するため、本文ラベルの font-size は約 1.8 以上にしてください。

figures:svg-primitives が自動で設定: Canvas(width_mm, height_mm) が viewBox と単位を設定します。

2. ボックスの境界に合わせたテキスト

ボックスにラベルを付ける場合、ラベルはボックスの境界矩形の内側に配置します。text-anchor="middle"とdominant-baseline="middle"を使い、ボックスの重心にテキストを配置します。

<rect x="10" y="10" width="30" height="14" fill="#F4F1DE" stroke="#1F3A5F" stroke-width="0.8" rx="1.5"/>
<text x="25" y="17" text-anchor="middle" dominant-baseline="middle"
      font-family="Helvetica, Arial, sans-serif" font-size="2.1">Cortex</text>

テキストの x 座標は、矩形のx + width/2 = 25です。y 座標はy + height/2 = 17です。角丸のrxに合わせて見た目を整えるには、y を約 0.5～1 mm 調整し、figures:figure-qaで確認してください。

バウンディングボックスの計算方法とよくある問題（テキスト幅がボックス幅を超える、ディセンダーがボックスからはみ出す）については、references/text-alignment.mdを参照してください。

figures:svg-primitivesで自動処理: LabeledBox(text=...)は、測定したテキストのバウンディングボックスから矩形のサイズを自動調整し、ラベルを中央に配置します。

3. 対象を指す矢印

正しい矢印は、対象の図形の端で正確に終わり、矢印の先端がパスの最後の接線に沿うように配置されます。次の 2 つのパターンが効果的です。

直線矢印（線＋マーカー）：

<defs>
  <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
          markerWidth="3" markerHeight="3" orient="auto-start-reverse">
    <path d="M 0 0 L 10 5 L 0 10 z" fill="#1F3A5F"/>
  </marker>
</defs>
<line x1="40" y1="17" x2="55" y2="17"
      stroke="#1F3A5F" stroke-width="0.8" marker-end="url(#arrow)"/>

markerWidth="3" markerHeight="3"を指定すると、mm の viewBox 規約で約 3 mm の矢印の先端になります。線の太さに合わせて調整してください（線幅の約 3～4 倍が目安です）。0.8 mm の線幅でmarkerWidth="6"を指定すると、先端が大きすぎます。

refX="9"を指定すると、マーカーの基準点が三角形の先端近くに配置されるため、x2,y2が見た目上の先端になります。矢印は対象の x = 55 の位置で正確に終わります。

曲線矢印（3 次ベジェ曲線パス＋マーカー）：

<path d="M 40 17 C 47 17, 47 30, 55 30" fill="none"
      stroke="#1F3A5F" stroke-width="0.8" marker-end="url(#arrow)"/>

制御点（47 17, 47 30）により、滑らかな S 字カーブになります。t=1での接線は(55,30)の方向を向きます。SVG QA チェックで矢印の先端が対象に接していることを確認してください（check_svg.pyは、先端と対象の距離が許容範囲を超えると警告します）。

QA エージェントが認識する、svgpathtools と互換性のあるパターン全体については、references/arrow-patterns.mdを参照してください。

figures:svg-primitivesで自動処理: Arrow.connect(src, dst, curve='straight'|'cubic'|'orthogonal-h'|'orthogonal-v')は、パスとの交点を使って直線および 3 次ベジェ曲線の端点をボックスの輪郭に合わせます（直交ルートでは、方位の基点間に中間ウェイポイントを使用します）。また、すべての曲線タイプで接線に沿って描画されるよう、<marker orient='auto'>を出力します。

4. 線と矢印は z オーダーで図形の下を通す

SVG は要素をドキュメント順に描画します。接続線をノードの下に見えるように描画するには、次のようにします。

<line x1="10" y1="30" x2="80" y2="30" stroke="#888" stroke-width="0.5"/>

<circle cx="45" cy="30" r="3" fill="white" stroke="#1F3A5F" stroke-width="0.8"/>

z-indexは避けてください（CSS で描画される SVG 以外には適用されません）。ドキュメント順だけを使用してください。

figures:svg-primitivesで自動処理: Canvas.layer(name)とCanvas.add_layer(Layer)を使って描画順にレイヤーを登録します。先に登録したレイヤーに追加された要素は、追加されたタイミングにかかわらず、後のレイヤーに追加された要素の背面に配置されます。

5. カラーパレット：1 つを選び、一貫して使う

模式図にアイコンを添える場合は、figures:transparent-iconsのテーマガイドにあるパレットを再利用してください。模式図のみの場合は、QA エージェントの--paletteフラグが認識する、色覚多様性に配慮したパレットがreferences/svg-guidelines.mdに記載されています（okabe-ito、tol-bright）。軸、目盛り、グリッド線の近似グレー（#888、#999、#ccc）はパレット準拠の対象外なので、装飾要素に自由に使えます。

figures:svg-primitivesでも同じ規約: LabeledBox(fill=..., stroke=...)およびArrow.connect(stroke=...)に、16 進数のカラーコードを直接渡します。

パネルへの合成

SVG を作成したら、figures:scientific-figureのパネルソースとして使用します。

from compose import Figure

Figure(width_mm=183, height_mm=60, journal="nature") \
    .add_panel("panels/data.svg", x_mm=0, y_mm=0, scale=0.5, label="A") \
    .add_panel("schematics/circuit.svg", x_mm=92, y_mm=0, scale=1.0, label="B") \
    .save("figure.svg")

模式図は通常、最終的なパネル寸法で作成し、scale=1.0で合成します。模式図にはプロットの目盛りラベルがないため、拡大縮小によって読みにくくなることはありません。

品質保証

作成後、ホストのスキル呼び出し機構を通じて figures:figure-qa を実行してください（プログラムによる実行では、以下のコマンドを使用します）。

SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT}/agents/figure-qa-scripts"
[ -d "$SCRIPTS_DIR" ] || SCRIPTS_DIR="$(find . -type d -name figure-qa-scripts -path '*/figures/agents/*' | head -1)"
uv run --with lxml --with svgelements --with shapely \
    python "$SCRIPTS_DIR/check_svg.py" schematics/circuit.svg \
    --journal nature --palette okabe-ito

SVG ブランチでは、フォントサイズ、パレットへの準拠（クローム部分のほぼグレーは対象外）、ジオメトリの数が確認され、報告されます。

figures:svg-primitives で作成した SVG では、Canvas.save(validate='warn'|'strict'|'off') の実行中にも検証が行われるため、ファイルを書き出す前に同じ不変条件（およびそれ以上）を確認できます。2 つのバリデーターは相互に補完し合います。figure-qa はあらゆる SVG を検証し、svg-primitives の検証は同ツールで生成した SVG を検証します。

Illustrator または Affinity Designer への引き継ぎ

共同作業者が Adobe Illustrator または Affinity Designer で図を編集する場合、 SVG が編集可能なマスターであり、PDF は派生した印刷用成果物です。 変換した PDF は、断片化されたテキストランとして開かれます （Illustrator ではランごとのポイントテキストとして保持されます。 Affinity ではフレームが推測によって再構成され、レイアウトがずれます）。 各エディターのインポート時の特性に合わせて作成してください。 領域ごとにトップレベルの <g id="..."> を配置する（名前付きグループとして取り込まれます。SVG 内の要素が Illustrator のレイヤーに対応することはありません）。 各行を 1 つの <text> で表し、text-anchor="start" と計算済みの左端を指定する（Illustrator はインポート時に text-anchor を無視します）。 具体的な font-family を 1 つと数値の font-weight を指定する（フォントスタックや @font-face は使用しません）。 サブ図は <g transform> としてインライン化する（ネストした <svg> や SVG のデータ URI を使った <image> は使用しません）。 矢印の先端は塗りつぶしたパスとして埋め込む（既知の Illustrator の不具合がある <marker> は使用しません）。 完全なチェックリスト、エディターごとの動作をまとめた表、印刷用 PDF の作成手順 （Inkscape のテキストからパスへの変換、Ghostscript の -dNoOutputFonts）、および参照資料については、references/editor-handoff.md を参照してください。

エディター向けの準備処理

上記のルールの多くは作成時に簡単に適用できるため、通常はそのままデフォルトにしてください （グループ、単一のフォントファミリー、原点が 0 の viewBox、データ URI なし、ネストした <svg> なし）。 QA 検証が依存しているため、デザインマスターに残す意図的な例外が 2 つあります。 <marker orient="auto"> の矢印の先端（曲線上で接線方向に合い、figures:figure-qa と figures:svg-primitives の検証で確認されます） と text-anchor="middle|end"（配置の基準となる唯一の情報源）です。 引き継ぎ用コピーを作成する際は、別途、機械的な処理でこれらを解決してください。

uv run --with lxml --with svgpathtools --with fonttools \
    python scripts/editor_prep.py figure.svg          # -> figure-editable.svg
# --check: report violations without writing (exit 1 if any)
# --font "Lato=/path/to/Lato.ttf": font file for text-width measurement
# --in-place / -o out.svg: output control

この処理では、パス終点の回転済みジオメトリに marker-end の矢印の先端を埋め込みます （マーカーの viewBox による拡大縮小、refX/refY、orient、markerUnits を反映します）。 middle/end アンカーを測定した左端に置き換え、 ネストした <svg> のビューポートを変換済みグループに平坦化し （preserveAspectRatio を完全にサポートします）、 SVG データ URI 画像を名前空間付き ID のベクターグループとしてインライン化し、 href がないすべての <image> で href を xlink:href に複製し、 フォントスタックを先頭のファミリーに絞り、 フォントサイズの px をユーザー単位に変換します （比率はルート要素の width/viewBox から算出されるため、mm 単位のドキュメントも正しく変換されます）。 また、修正できない構造 （<style> ブロック、@font-face、dominant-baseline、フィルター、 foreignObject、textPath、font ショートハンド、 marker-start／marker-mid）について警告します。 この処理は冪等で、これらのスキルで作成した SVG に限らず、あらゆる SVG に適用できるため、 既存の図にも新しい図と同じ処理を行えます。 デザインマスターは QA で検証できる状態に保たれ、デザイナーには -editable.svg コピーを渡します。

追加リソース

• examples/schematic_from_primitives.py — svg-primitives を使用したプログラムによるサンプルです（まずはこちらから始めることをおすすめします）。
• examples/schematic.svg — 手作業で作成した参考用の回路図です。
• references/svg-guidelines.md — 要素の一貫性に関するルールと、カラーパレットの推奨事項です。
• references/arrow-patterns.md — 直線、曲線、分割された矢印の作成例と、QA エージェントが認識する svgpathtools 互換のジオメトリです。
• references/text-alignment.md — テキストのバウンディングボックスの計算、ベースラインの動作、よくある不具合（はみ出し、ディセンダーの欠落、アンカーの反転）について説明します。
• references/editor-handoff.md — Illustrator / Affinity Designer に編集可能な状態で引き渡す際の作成ルール、各エディターの SVG インポート動作、印刷用 PDF の作成（テキストのアウトライン化、フォントの埋め込み、PDF レイヤー）について説明します。
• scripts/editor_prep.py — 引き渡し前の機械的な処理を行います。マーカーを埋め込み、テキストアンカーを解決し、入れ子になったビューポートをフラット化し、SVG データ URI をインライン化して、フォントを正規化します。冪等性があり、あらゆる SVG で動作します。