The primitive vocabulary
The library uses five rendering primitives. Nodes, panels, lanes, and charts are named compositions of those primitives. A shared renderer gives the compositions the same color, line, and type rules.
Scene envelope
| Field | Type | Constraint |
|---|---|---|
version |
number | Must be 1 |
width, height |
number | Each from 100 to 2400 SVG units |
title |
string | Up to 200 characters; accessible image title |
description |
string | Up to 2,000 characters; accessible explanation |
elements |
array | Up to 300 primitives, painted in array order |
Coordinates refer to the SVG viewBox. The default canvas is 720 × 400. The image scales proportionally on the page. Elements later in the array appear above earlier ones. Place connectors before nodes when you want nodes to cover connector ends.
Five rendering primitives
| Type | Required fields | Optional fields |
|---|---|---|
box |
x, y, w, h |
fill, stroke, dashed |
text |
x, y, text |
size, fill, align, mono, bold |
line |
x, y, x2, y2 |
stroke, arrow, dashed |
path |
d |
fill, stroke, arrow, dashed |
circle |
x, y, r |
fill, stroke |
Every primitive also requires its type. Coordinates must be finite numbers with an absolute value at most 10,000. Widths, heights, radii, and text sizes must be positive. The parser rejects unsupported primitive properties. A path accepts SVG drawing commands and numbers, not arbitrary markup.
Text positions use the baseline. align defaults to start; use middle or end for centered or right-aligned labels. Default text size is 15 SVG units. Text does not wrap automatically. Split a long label into multiple text primitives or widen the containing shape.
Paints are semantic tokens: ink, muted, accent, soft, surface, rule, positive, negative, and none. Theme changes resolve these tokens to colors. You cannot supply arbitrary CSS in scene JSON. Edit palette in src/lib/scene.ts to add a branded palette in source.
Geometry is explicit. Moving a box does not move its label or reroute a connector. Edit the related coordinates together. This first version has no automatic graph layout, drag-and-drop canvas, or constraint solver.
Higher-level compositions
| Composition | Construction | What stays consistent |
|---|---|---|
| Node or entity | Box + title + optional rows | Label alignment and padding |
| Boundary or lane | Large box + caption | Grouping and ownership |
| Connector | Line or path + optional arrow + label | Direction and line weight |
| Lifeline or track | Dashed line + participant or commit markers | Reading direction |
| Axis | Lines + tick labels | Baseline, scale, and units |
| Series or band | Paths, boxes, or circles | Data-to-position mapping |
| Matrix | Repeated boxes + row and column labels | Cell size and spacing |
| Text block | Repeated text + optional line numbers | Baselines and line spacing |
| Annotation | Text + optional leader | Proximity to the subject |
Keep related shapes close together and place labels beside what they describe. Avoid patterned backgrounds behind text. These constraints apply when adding a new theme as well as a new recipe. (Universal Principles of Design, pp. 374, 280.)
A complete scene
{
"version": 1,
"width": 720,
"height": 400,
"title": "One service",
"description": "An API service inside a labeled box.",
"elements": [
{ "type": "box", "x": 260, "y": 150, "w": 200, "h": 80, "fill": "soft", "stroke": "accent" },
{ "type": "text", "x": 360, "y": 196, "text": "API service", "align": "middle" }
]
}Import this scene with Import JSON, or paste it into the source editor and choose Apply scene.