VISUAL DESIGN
Ten diagram forms rendered by a single budget-aware engine. Every SVG is sized to its display width — fonts render at their declared size with no scaling. The system measures labels, allocates space, and degrades gracefully when content exceeds the budget.
viewBox width equals display width. An SVG designed for 800 pixels renders its 14-pixel labels at exactly 14 pixels — no scaling math, no mismatch between authored size and rendered size. The diagram fills its container and fonts stay crisp.
The Confluence content area is roughly 860 pixels wide with the sidebar open. Setting a diagram's width to 800–900 means the SVG fits without scaling. Larger values force the browser to shrink the image — an 1100-pixel SVG in an 860-pixel container scales fonts to 78% of their authored size. That's the trap the budget system avoids.
The engine measures every label, calculates node widths, allocates gaps for edge text, and picks a font size that makes everything fit. When space is generous, labels render at the preferred 14 pixels. When space is tight, fonts scale down to a floor of 11 pixels. If that's still not enough, labels truncate with ellipsis. The degradation cascade is always: preferred size → scale down → floor → truncate.
Heuristic text-width estimation using character-width tables for system sans-serif. No DOM, no canvas — pure arithmetic, ±5% accuracy.
Available width minus gaps, divided among nodes. Font size adjusts to maximize readability within the remaining space.
Preferred 14px → scale to fit → 11px floor → truncate with ellipsis. Every label stays readable; none silently overflow.
Four steps in 900 pixels of budget. Labels render at the preferred 14-pixel size with room to spare. Edge labels fit comfortably.
Seven steps in 800 pixels. The budget compresses — font size scales down, edge labels compete with nodes for space. Long labels may truncate. This is the system working hardest.
Vertical pipelines take a narrow width budget (300–500px) and let depth carry the content. Useful for sidebar-style diagrams and tall processes.
Three forms for processes that unfold in order. Pipelines for linear flows. Sequences for temporal message exchange between participants. Swimlanes for cross-functional handoffs between actors.
Temporal message flow between participants. Lifelines, typed messages (sync, async, reply), and self-loops. The canonical form for API call chains and distributed system interactions.
Cross-functional processes with horizontal swim lanes. Steps belong to lanes (actors or systems), edges cross boundaries to show handoffs. Where sequence diagrams show time, swimlanes show responsibility.
Two forms for structures that branch outward. Fanouts for one-to-many dispatch. Trees for multi-level hierarchies with parent-child relationships.
One source fans out to multiple targets via labeled edges. Event propagation, message routing, dependency graphs — anywhere one input produces multiple outputs.
Multi-level hierarchy with parent-child relationships. Supports multiple roots (forest), top-down or left-right layout. Org charts, class inheritance, feature decomposition.
Three forms for relationships between things. Topologies for network graphs. Layer stacks for tiered architectures. Seam maps for domain boundaries and integration contracts.
Network of connected systems. Nodes grouped by function, edges show relationships with labeled protocols. The form for service meshes, data flows, and API dependency maps.
Stacked abstraction layers with items inside each. Arrows show how layers connect. The canonical form for three-tier architecture, protocol stacks, and infrastructure tiers.
Domain boundaries connected by integration seams. Areas in a row, shared state below as an integration spine. The interesting question is where systems meet and what they share.
Two forms for things that change over time. State machines for entity lifecycles with transitions, guards, and self-loops. Cycles for continuous processes where the last stage feeds the first.
States with labeled transitions, self-loops, guards, and initial/terminal markers. The canonical form for subscription lifecycles, payment flows, and feature flags.
Stages arranged in a ring with continuous flow. The last stage connects back to the first. CI/CD loops, incident response, iterative workflows — any process that repeats.
Three density levels control spacing between nodes. Tight packs elements for maximum information density. Comfortable (default) balances readability and compactness. Spacious gives every element room to breathe. Density interacts with the width budget — tight density at a wide width means larger nodes and fonts, not just less whitespace.
Every diagram renders on the base surface — the same dark canvas that anchors every page in the chromatic language. The depth field makes colored nodes luminous. Light nodes on dark canvas, always.
Set the width to match the display context. 800–900 for full-width Confluence pages. 400–500 for vertical or sidebar diagrams. The system handles everything else — font sizing, truncation, gaps.
Unlabeled edges are ambiguous edges. Every node has a title and subtitle. Every connection names its protocol. The diagram should be readable without a legend.
A diagram that needs explanation has failed. The budget system exists so geometry speaks for itself — at any width, at any density, with any labels.