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.

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.

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