svg-primitives

SVG Primitives

Build mm-precise SVG schematics in Python with three mechanical guarantees:

1. Text never overflows its container — labeled shapes auto-size to fit measured text bbox + padding.
2. Arrowheads stay tangent-correct — arrows emit <marker orient="auto"> so the renderer rotates the head along the path's terminal tangent; works on straight lines and cubic Beziers.
3. Paint order is deterministic — layers paint in registration order; connectors visibly pass under boxes without manual reordering.

The skill ships an end-to-end pytest suite (50+ tests) that renders SVGs and asserts these invariants on the rendered output, so the guarantees are enforced by construction rather than by hand-checking each figure.

When to use this skill

Reach for svg-primitives when:

• The figure is a schematic (boxes, arrows, labels) and you're driving it from Python — e.g. nodes come from a YAML config, or the layout depends on data.
• You need the boxes to auto-fit their labels (no hand-tuning widths).
• The figure has curved arrows that must point cleanly at their targets.
• You want deterministic z-order so connectors sit under shapes without manual element reordering.
• The output will be composed into a multi-panel figure as a panel SVG that scientific-figure/compose.py loads.

Reach for a different tool when:

• The figure is plotted from numbers (matplotlib/seaborn/plotnine) → use [[plot-styling]].
• The figure is a photographic / pictorial substrate (a brain scene, microscope setup) → use [[ai-full-figure]] for the substrate and overlay labels via Arrow/LabeledBox here.
• The figure is hand-authored SVG or the patterns are reference material for hand-authoring → use [[svg-figure]] (this skill's library-agnostic counterpart).

Quick start

from svg_primitives import Canvas, LabeledBox, Arrow

c = Canvas(width_mm=183, height_mm=80)
boxes = c.layer("boxes")
arrows = c.layer("connectors")

raw = boxes.add(LabeledBox(x=10, y=20, text="Raw EEG", font_size=7))
band = boxes.add(LabeledBox.next_to(raw, side="E", gap=10, text="Bandpass\nfilter", font_size=7))
ica = boxes.add(LabeledBox.next_to(band, side="E", gap=10, text="Independent component\nanalysis", font_size=7))

arrows.add(Arrow.connect(raw, band))                          # straight, snapped to edges
arrows.add(Arrow.connect(band, ica))                          # straight
arrows.add(Arrow.connect(ica, raw, curve="cubic", bow=14,     # feedback arc
                          stroke="#C45146"))                  # red — gets its own red marker

c.save("eeg.svg", output_png=True)