svg-figure

SVG 图示

用于 SVG 示意图和图表（流程图、流程示意图、系统图、解剖插图）的规范，并确保元素一致性：文本与框的边界对齐、箭头指向目标、线条按 z 轴顺序从形状下方穿过。输出的 SVG 旨在由 figures:scientific-figure 技能组合为面板，并由 figures:figure-qa Agent 的 SVG 分支进行验证。

何时使用此技能

对于新的编程工作，请改用 figures:svg-primitives。 它以机械方式保证以下所有规范——文本自动适配框、曲线上的箭头尖端始终与切线正确对齐、绘制顺序确定无误，而且如果违反任何不变量，Canvas.save(validate='strict') 会报错。本技能中的 examples/schematic_from_primitives.py 是规范的编程示例。

在以下情形使用此技能：

• 你要手动编写 SVG，或使用 Inkscape 之类的编辑器编写，并需要遵循 figure-qa Agent 所期望的规范。
• 你使用非 Python 工具生成 SVG，并想了解其应采用何种形态。
• 你在查看外部协作者手工编写的 SVG，并想了解其布局语法。
• 你在调试 figure-qa 对非 svg-primitives 生成的 SVG 的检查结果。
• 图形是示意图（框、箭头、标签），而不是根据数值绘制的数据图——绘图请使用 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 工具生成 SVG。figures:svg-primitives 会以机械方式强制执行所有规范；本节是底层 SVG 规范的参考，也是 figure-qa Agent 验证任意 SVG 输入时所依据的规范。

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"> 的尺寸为 20 mm × 10 mm，而 <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. 箭头指向目标

正确的箭头应恰好终止于目标形状的边缘，且箭头尖端应沿路径的末端切线方向。以下两种模式效果良好：

直线箭头（线条 + 标记）：

<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)"/>

在 mm-viewBox 约定下，markerWidth="3" markerHeight="3" 会生成约 3 mm 的箭头。根据描边宽度调整尺寸（约为描边宽度的 3–4 倍是一个不错的经验值）；对于 0.8 mm 的描边，markerWidth="6" 会产生过大的箭头。

refX="9" 会将标记的参考点放在三角形尖端附近，因此 x2,y2 就是视觉上的箭头尖端。箭头在视觉上恰好终止于目标的 x = 55 处。

曲线箭头（立方路径 + 标记）：

<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 Agent 可识别的、与 svgpathtools 兼容的完整模式，请参阅 references/arrow-patterns.md。

由 figures:svg-primitives 自动完成：Arrow.connect(src, dst, curve='straight'|'cubic'|'orthogonal-h'|'orthogonal-v') 会通过路径求交，将直线和立方曲线的端点吸附到方框轮廓上（正交路线则使用基数锚点之间的中点作为路径点），并生成 <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. 选择一种调色板并保持一致

如果示意图与图标一同提供，请沿用 figures:transparent-icons 主题规范中的调色板。对于独立示意图，references/svg-guidelines.md 列出了 QA Agent 的 --palette 标志支持的色盲友好调色板（okabe-ito、tol-bright）。轴线、刻度和网格线使用的近灰色（#888、#999、#ccc）不受调色板合规要求限制，可自由用于装饰元素。

figures:svg-primitives 中采用相同约定：将十六进制颜色直接传递给 LabeledBox(fill=..., stroke=...) 和 Arrow.connect(stroke=...)。

组合到面板中

创作完成后，该 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') 过程中运行——在文件写入之前，它就能检查相同的不变量（以及更多内容）。这两种验证器互为补充：figure-qa 适用于任何 SVG；svg-primitives 验证仅适用于它生成的 SVG。

移交给 Illustrator 或 Affinity Designer

如果协作者会在 Adobe Illustrator 或 Affinity Designer 中编辑图形，SVG 就是可编辑的主文件，任何 PDF 都只是派生的印刷文件；转换后的 PDF 会以碎片化的文本段形式打开（Illustrator 会将其保留为逐段的点文本；Affinity 则会通过启发式方法重建文本框，导致布局偏移）。创作时应考虑编辑器的导入特性： 每个区域使用顶层 <g id="...">（导入后会成为具名组；SVG 中没有任何内容可以映射为 Illustrator 图层）， 每行使用一个 <text>，并设置 text-anchor="start" 和计算得出的左边缘（Illustrator 导入时会忽略 text-anchor）， 只使用一个具体的 font-family 和数字形式的 font-weight（不要使用字体栈或 @font-face）， 将子图内嵌为 <g transform>（不要使用嵌套的 <svg> 或 SVG data-URI <image>）， 并将箭头头部直接绘制为填充路径（不要使用 <marker>，Illustrator 存在一个已知问题）。 完整清单、各编辑器行为对照表、印刷 PDF 派生方法（Inkscape 文本转路径、Ghostscript -dNoOutputFonts）和参考资料，请参阅 references/editor-handoff.md。

编辑器准备处理

上述大多数规则在创作时无需额外成本，应直接作为默认设置（分组、单一字体系列、原点为 0 的 viewBox、不使用 data URI、不使用嵌套的 <svg>）。 设计主文件中保留了两个有意设置的例外，因为 QA 验证依赖它们： <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 箭头头部转换为路径端点处旋转后的几何图形（遵循 marker 的 viewBox 缩放、refX/refY、orient 和 markerUnits），将 middle/end 锚点解析为测量得出的左边缘，将嵌套的 <svg> 视口展平为经过变换的组（完整支持 preserveAspectRatio），将 SVG data-URI 图像内嵌为带命名空间 id 的矢量组，在缺少 xlink:href 的任何 <image> 上复制 href 到 xlink:href，将字体栈缩减为首选字体系列，将 px 字体大小转换为用户单位（比例由根元素的 width/viewBox 推导，因此也能正确转换 mm 文档），并对无法修复的结构发出警告（<style> 块、@font-face、dominant-baseline、滤镜、foreignObject、textPath、font 简写，以及 marker-start/marker-mid）。 此处理步骤具备幂等性，适用于任何 SVG，而不仅限于这些技能生成的文件，因此旧图形也能和新图形一样得到处理。 设计主文件仍可通过 QA 验证；交给设计师的是 -editable.svg 副本。

其他资源

• examples/schematic_from_primitives.py — 使用 svg-primitives 的编程示例（推荐作为起点）。
• examples/schematic.svg — 手工编写的参考原理图。
• references/svg-guidelines.md — 元素一致性规则和调色板建议。
• references/arrow-patterns.md — 直线、曲线和分段箭头的绘制方法；QA Agent 可识别的 svgpathtools 兼容几何。
• references/text-alignment.md — 文本边界框的计算、基线行为和常见故障模式（溢出、下伸部截断、锚点反转）。
• references/editor-handoff.md — 面向 Illustrator / Affinity Designer 可编辑交接的创作规则、各编辑器的 SVG 导入行为，以及打印 PDF 的生成方法（文本转轮廓、嵌入字体、PDF 图层）。
• scripts/editor_prep.py — 机械式交接处理：固化标记、解析文本锚点、扁平化嵌套视口、内联 SVG 数据 URI、规范化字体。具备幂等性；适用于任何 SVG。