spinagram

Diagrams as code, delivered editable everywhere.
Write a few lines of Python. Get SVG, PNG, PowerPoint with native shapes, and Figma, FigJam or Excalidraw scenes you can keep editing.

Documentation · Getting started · Python guide · Examples

Why spinagram

• Editable output, not screenshots. PowerPoint slides get native shapes with the text inside and connectors bound to the boxes, so moving a box drags its arrows along. Figma gets real frames and nodes.
• Python that reads like the picture. users >> lb >> api, groups as with blocks, loops and functions for the repetitive parts. YAML works too, for generated diagrams.
• No coordinates needed. spinagram sizes every box from its text and icon, nests groups such as an AWS Region, a VPC and its zones, and places everything with one of four layout engines.
• Brand once, render anywhere. A theme directory holds colours, fonts, styles, icons and page chrome.
• Thousands of icons. AWS, GCP, Azure, Kubernetes, CNCF, OCI, OpenStack, Terrastruct, Devicon, SVG Logos, self-hosted and network packs download on first use. Add your own from a folder, npm or GitHub.
• Edit with the mouse. spinagram serve has a canvas editor for YAML diagrams: drop icons and provider zones from a palette, drag, group and connect, and edit properties, while the YAML file stays the source of truth.
• Built for reviews. spinagram check catches text overflow, spinagram serve previews live, and numbers can come from a facts file with their provenance in every render.

Quick start

pip install "spinagram[all]"            # or: uv add "spinagram[all]"

Say what is connected to what. spinagram sizes, places and styles everything:

from spinagram import Diagram

d = Diagram("Q01", "Web app on AWS", subtitle="No coordinates, laid out automatically")

users = d.box("Users", icon="aws:users")
with d.group("us-east-1", style="aws-region", direction="right"):
    with d.group("VPC", style="aws-vpc", direction="right"):
        lb = d.box("Load balancer", icon="aws:alb")
        api = d.box("API", text="FastAPI on ECS", icon="terrastruct:python")
        with d.group():  # no style: a light "soft" zone
            db = d.box("Orders DB", text="PostgreSQL", icon="terrastruct:postgres")
            cache = d.box("Cache", text="Redis", icon="terrastruct:redis")
    s3 = d.box("Uploads", text="S3 bucket", icon="aws:s3")

users.to(lb, "HTTPS") >> api
api.to(db, "SQL")
api >> [cache, s3]

d.save("out/", formats=["svg", "png", "pptx"])

• d.box(...) adds a node; its size comes from its text and icon. No coordinates needed.
• a >> b draws an arrow, a.to(b, "label") a labelled one, a >> [b, c] fans out.
• with d.group(...) nests nodes in a zone (an AWS Region, a VPC, or any style from your theme).
• d.save() writes the files; in Jupyter the diagram shows inline. spinagram serve file.py previews it live.

id: Q01
title: Web app on AWS
subtitle: No coordinates, laid out automatically
groups:
  - id: region
    label: us-east-1
    style: aws-region
    direction: right
    children:
      - id: vpc
        label: VPC
        style: aws-vpc
        direction: right
        children: [lb, api, data]
      - s3
  - {id: data, children: [db, cache]}
nodes:
  - {id: users, title: Users, icon: "aws:users"}
  - {id: lb, title: Load balancer, icon: "aws:alb"}
  - {id: api, title: API, text: FastAPI on ECS, icon: "terrastruct:python"}
  - {id: db, title: Orders DB, text: PostgreSQL, icon: "terrastruct:postgres"}
  - {id: cache, title: Cache, text: Redis, icon: "terrastruct:redis"}
  - {id: s3, title: Uploads, text: S3 bucket, icon: "aws:s3"}
edges:
  - "users -> lb: HTTPS"
  - lb -> api
  - "api -> db: SQL"
  - api -> cache
  - api -> s3

spinagram render examples/quickstart.yaml -f svg,png,pptx -o out/

Need pixel-exact slides instead? Give nodes coordinates (manual layout), or freeze an automatic layout with spinagram layout spec.py -o frozen.yaml and tune it by hand.

Flowcharts, state machines, activities and CSS

Flowchart, StateMachine and Activity builders add the symbols and verbs of behavior diagrams (decisions, forks and joins, swimlanes, composite states) laid out by a built-in layered engine, and with d.state_machine(...) puts one inside any diagram. A CSS subset styles everything: d.stylesheet("brand.css"), class_="critical", edge.async { stroke-dasharray: 6 4 }. spinagram check --styles explains which rule set each value, spinagram serve has a click-to-inspect styles panel and re-renders when a stylesheet is saved. See behavior diagrams, CSS styling and CSS by backend (what SVG, PowerPoint and Figma do with each property). examples/showcase has AWS, Kubernetes and Google Cloud reference architectures styled only with CSS.

Outputs

Learn more

The documentation (searchable) covers:

• Automatic layout: groups and the flex, dot, elk and d2 engines
• Icon packs (AWS, Google Cloud, Azure, Kubernetes, CNCF projects, AI, about 2,000 technology logos, languages, self-hosted and network gear) and themes
• Annotations: legends, numbered steps, callouts and designed notes
• Facts: numbers with traceable sources
• Figma and FigJam hand-off, and Excalidraw scenes
• CLI, the live UI and its canvas editor
• Edit API: patch a diagram's YAML from Python with the canvas's edit operations
• AI agent skills: spinagram skills install --agent claude|codex|cursor|gemini|copilot|… teaches your coding agent to write and style diagrams
• MCP server: spinagram mcp install -a claude|codex|cursor|gemini|copilot|opencode lets any MCP agent render, check and preview diagrams without a shell
• Release notes: what's new in each version
• Extending with your own backends and layout engines

Development

uv sync --all-extras && uv run pytest
cd docs && bun install && bun run dev  # docs at http://localhost:3000

uv sync builds the Rust engine in rust/, so it needs a Rust toolchain. See Development for the UI frontend, docs and releases.

Changelog and license

See CHANGELOG.md for what changed in each release. spinagram is released under the MIT License. Icon packs are downloaded from their upstream projects on first use and keep their own licenses (listed by spinagram icons list).