Icon packs

Vendor icon sets are downloaded on first use into ~/.cache/spinagram/icons (override with SPINAGRAM_CACHE; set SPINAGRAM_OFFLINE=1 to never download) and referenced as pack:name:

nodes:
  - {id: db, title: Orders DB, icon: "aws:rds"}
  - {id: gke, title: Cluster, icon: "gcp:gke"}

Names are kebab-case file names (aws:amazon-ec2), with short aliases (aws:ec2, aws:s3, aws:alb, gcp:gke, azure:aks, …). For general software architecture use terrastruct: technologies by plain name (terrastruct:python, terrastruct:postgres, terrastruct:redis, terrastruct:kafka, terrastruct:sqs), generic glyphs by category (terrastruct:tech-server, terrastruct:infra-firewall, terrastruct:db). See examples/software_architecture.yaml.

An icon can also be a file path, resolved relative to the spec.

AI, cloud native and technology logosCopy Anchor Link

ai covers the AI stack: providers (ai:openai, ai:anthropic, ai:google, ai:mistral, ai:deepseek), models and assistants (ai:claude, ai:gemini, ai:copilot), agents and IDEs (ai:claude-code, ai:cursor, ai:codex), serving and platforms (ai:ollama, ai:vllm, ai:bedrock, ai:azure-ai, ai:vertex-ai, ai:hf) and frameworks (ai:langchain, ai:langgraph, ai:llama-index, ai:mcp).

cncf has every CNCF project by its folder name (cncf:harbor, cncf:argo, cncf:prometheus, cncf:opentelemetry, cncf:envoy, cncf:istio, cncf:helm, cncf:flux, cncf:falco), plus cncf:cncf itself. The bare name is the colour icon; -horizontal and -stacked are the logos with the name, and -black any form in one colour. The project's white artwork is used on dark fills. Aliases: k8s, otel, argocd, fluxcd. A project published only as a logo (cncf:kanister) resolves to that logo.

logos names a technology the way it is spelled (logos:gitlab, logos:jfrog, logos:oracle, logos:jenkins, logos:sonarqube, logos:terraform, logos:vault, logos:dynatrace, logos:redhat). The bare name is the square icon when the set has one, else the full logo; -logo is always the full logo (logos:gitlab-logo).

These three packs are downloaded from GitHub on first use, like selfhosted. A name can exist in more than one pack (selfhosted:harbor, cncf:harbor); prefer cncf for CNCF projects and logos for vendors, and keep one pack per diagram where you can, so the logos share one style. See examples/showcase/delivery_ai.py.

devicon has languages, frameworks and developer tools in their original colours: devicon:rust, devicon:go, devicon:python, devicon:kafka, devicon:postgresql. Add -plain or -line for the flat and outline styles, -wordmark for the logo with the name.

Aliases you add to a pack in your registry (alias:) work at once, without downloading the pack again.

Homelab, private cloud and networkCopy Anchor Link

selfhosted covers what runs in a homelab or private cloud: hypervisors (selfhosted:proxmox, selfhosted:vmware-esxi, selfhosted:xcp-ng, selfhosted:nutanix), firewalls and routers (selfhosted:opnsense, selfhosted:pfsense, selfhosted:mikrotik, selfhosted:unifi), storage (selfhosted:truenas-scale, selfhosted:unraid, selfhosted:synology) and the apps on top (selfhosted:k3s, selfhosted:traefik, selfhosted:pihole, selfhosted:home-assistant). Short aliases: pve, pbs, esxi, vsphere, nsx, pihole, hass, nginx-pm, omv, wg. Where the source has light artwork (proxmox-light.svg), it is used automatically on dark fills. The first download takes a couple of minutes (about 3,600 files).

network draws generic network gear the same way across a diagram:

Symbols include router, switch, switch-multilayer, firewall, loadbalancer, server, servercluster, storage, nas, vm, wifi, wlc, client, laptop, ip-phone, printer, cloud and globe, with aliases fw, lb, l3-switch, ap, vm-host, wan and internet. Find the rest with spinagram icons search. See the homelab and campus network diagrams in examples/showcase.

Managing packsCopy Anchor Link

spinagram icons list                       # packs, version, download state
spinagram icons fetch aws k8s              # pre-download (default: all)
spinagram icons search "load balancer"     # find names in downloaded packs
spinagram icons add brand --dir ~/brand/icons                     # local folder
spinagram icons add tabler --npm @tabler/icons@3.19.0 --include 'package/icons/outline/*'
spinagram icons add mine --github org/repo@v1.2 --include 'svg/*' --project   # ./spinagram-icons.yaml
spinagram icons add corp --npm @team/icons@1.0.0 --registry https://artifactory.example/api/npm/npm-virtual/
spinagram icons import node_modules/@team/icons/spinagram-icons.yaml   # a package can ship its own descriptor
spinagram icons remove brand

Pack formatCopy Anchor Link

A pack is YAML (built-ins live in src/spinagram/icon_packs/):

• source: a zip URL, an npm package, a github repo/ref, a listing (an index page: url + pattern regex naming each file), or a local dir, plus include globs.
• rules: regex → name template, with optional tone: dark and aliases.
• strip: regexes that derive short aliases.
• alias: a curated alias map; a target may itself be a derived alias.
• current_color: {light: "#000000", dark: "#ffffff"} paints SVGs drawn in currentColor (they would render black everywhere) and adds a dark-fill copy to those without a dark variant.

Registries merge built-in < ~/.config/spinagram/icons.yaml < ./spinagram-icons.yaml < $SPINAGRAM_ICON_PACKS. A theme can map its own names onto packs: icons: {alias: {ec2: "aws:ec2"}}.

Vendor artwork keeps its owner's terms (each pack lists license and homepage).

PNG → SVG iconsCopy Anchor Link

With the vector extra installed, PNG icons are traced into SVG automatically: theme icons, icons referenced by path and PNG icon packs (oci, openstack). A traced icon is only used when it is faithful: it is rendered back with resvg at the source size and compared over grey (mean Δ ≤ 8 and ≤ 1 % of pixels off by more than 128); photos and heavy gradients stay PNG. Results are cached by content hash. PowerPoint gets the SVG with the original PNG as its fallback.

spinagram vectorize icons/ -o vector/      # batch, with a score table (--force writes rejects too)
SPINAGRAM_VECTORIZE=0 spinagram render …   # turn it off; or icons: {vectorize: false} in a theme / pack