Skip to content
UXClaim
Design Systems

Spine Diagrams

Generate clean architecture diagrams as SVG with deterministic output, designed for LLM integration and presentation-ready layouts.

View source More in Design Systems

What it does

Spine Diagrams is a Python library that generates architecture and system-design diagrams as SVG files. It’s purpose-built for LLM-generated output and creates publication-ready visualizations without external dependencies.

How it works

You describe your diagram as a Python dict or JSON file specifying lanes (containers), nodes (components), and connections (relationships). The engine renders a 1600px-wide SVG with intelligent orthogonal arrow routing through a single shared “spine” between rows. Arrows never overlap container bodies, labels never collide, and the output is deterministic—same config always produces identical SVG.

Key features

Layout intelligence: Supports 2-row (source/target) and 3-row (classic tier) layouts. Skip-row connections automatically sidestep through margin channels to avoid middle-row overlap. Aspect-ratio aware (16:9 default for slides, plus 4:3 and custom ratios). Vendor integration: 220+ built-in technology icons with auto-detection from labels. AWS, GCP, Azure, Salesforce, Stripe, Kafka, and more come with brand colors auto-applied. Zero complexity: Single stdlib-only Python script—drop it into any project, no npm, no matplotlib.

Use cases

Product teams documenting system architectures, UX researchers explaining technical workflows, design systems teams creating infrastructure diagrams, product managers sharing integration patterns with stakeholders. Works in presentation decks, documentation sites, and design specifications.

Who benefits

Design and product teams who need to communicate system complexity visually without wrestling with diagram tools. Anyone using Claude Code can trigger diagram generation with natural language prompts.

Frequently asked questions

How do I install Spine Diagrams?
Download `dist/spinediagrams.skill` from the GitHub repository and unzip it into `~/.claude/skills/`. It then works automatically in Claude Code sessions when you request diagrams. Or use it directly in Python by importing `svg_engine.py` into your project—it's a single file with no dependencies.
What diagram layouts does Spine Diagrams support?
Two-row layouts (source and target) by default, three-row layouts for classic tiered architectures, and skip-row sidestep connections that bypass middle rows. Extra vertical room is used for arrow spacing automatically based on connection density.
Does Spine Diagrams require external tools?
No. It's pure Python stdlib—no matplotlib, graphviz, or node toolchain required. The entire renderer is a single script that produces SVG output directly.
How do I describe a diagram to Spine Diagrams?
Define a Python dict or JSON with three main sections: `lanes` (containers with position and styling), `nodes` (components within lanes with status), and `connections` (arrows between nodes with labels). Include a `title` and optional `aspect` ratio for presentation format.
Can Spine Diagrams detect technology icons automatically?
Yes. It includes 220+ built-in icons for common technologies and auto-detects them from node labels. If a technology isn't found, the render audit lists which nodes need icons so you can add them manually or suppress detection for non-technology elements.
What status colors are available for diagram nodes?
Six status options: `existing` (slate, unchanged), `new` (cyan, being built), `transitioning` (amber, partially moved), `retiring` (red, decommissioned), `operational` (green, fully live), and `readonly` (light grey, no writes).
Is Spine Diagrams deterministic?
Yes. The same configuration always produces identical SVG output. No randomization or LLM involvement in the render loop, so diagrams are stable for version control and reproducible documentation.
Can I use Spine Diagrams without Claude Code?
Yes. Run it as a standalone Python script via CLI (`python svg_engine.py config.json output.svg`) or import it directly in your code. Works with any Python project that needs to generate diagrams programmatically.

Glossary

Single-spine routing
An arrow routing algorithm where all connections between rows pass through one shared zone (the spine) between them. Prevents arrows from crossing over container bodies and ensures labels don't collide.
Skip-row sidestep
A connection path that bypasses a middle row (row 1) by routing through a margin channel on either side. Used for direct connections from row 0 to row 2 in three-tier layouts without overlapping the middle tier.
Lane
A container or logical grouping in a diagram that holds nodes. Lanes occupy specific columns and rows and can span multiple columns. Typically represent platforms, systems, or architectural tiers.
Node status
A metadata label for diagram components indicating their operational state: existing (unchanged), new (in development), transitioning (partially moved), retiring (decommissioned), operational (live), or readonly (present but no writes).

More in Design Systems

All →
Design Systems

Claude Code Agent Design Kit

AI-powered multi-agent design system generator that creates production-ready UI components, design tokens, and documentation from natural language briefs.

MichelSR25
Design Systems

Claude Code Design Kit

AI-powered multi-agent design system generator that creates production-ready UI components, design tokens, and documentation from natural language descriptions.

MichelSR25
Design Systems

Claude Design Studio Toolkit

AI-powered design co-pilot with responsive UI engine, design tokens, accessibility validation, and multi-agent workflows for code-first design teams.