Working with icons

Every device needs an icon, and the ID must exist. There is no fallback and no fuzzy matching at build time — a wrong ID is a validation error.

SearchingCopy Anchor Link

npm run marrow -- icons search firewall
npm run marrow -- icons search "layer 3 switch"
npm run marrow -- icons search wireless --max 40
npm run marrow -- icons search router --json      # for scripts and agents

Output is id — Label (category):

affinity/symbol/firewall  —  Firewall (symbol)
affinity/tile/firewall  —  Firewall (tile)
aws/security-identity/aws-network-firewall  —  AWS Network Firewall (security-identity)
azure/networking/azure-firewall-manager  —  Azure Firewall Manager (networking)
cisco/capability/firewall  —  Firewall (capability)

Check what's installed:

npm run marrow -- icons packs
# packs root: /path/to/icon-packs
# icons loaded: 2854

The ID shapeCopy Anchor Link

  affinity / tile / switch-multilayer
  ────┬───   ─┬──   ────────┬────────
   pack     category      name

Filenames become the search keywords, which is why descriptive names matter when you add your own pack.

The packsCopy Anchor Link

Full licensing detail is in Icon packs.

Installing the vendor packsCopy Anchor Link

npm run marrow -- icons fetch              # all three, with a consent prompt
npm run marrow -- icons fetch aws --yes    # one pack, non-interactive

These download from AWS's, Microsoft's, and Google's own servers, once per clone. They are gitignored because the vendors permit using the icons in diagrams but not redistributing the libraries — so Marrow can't ship them, and your built HTML files (which embed the icons you actually used) are fine to share. That's the granted use.

If a topology references a pack that isn't installed, validate tells you exactly that: "pack not installed — run marrow icons fetch <pack>".

Matching packs to domainsCopy Anchor Link

The pack you choose is a statement about what kind of thing the device is. Mixing arbitrarily makes a diagram look like a clip-art collage.

• On-prem network gear → cisco. It has the deepest coverage of real network hardware, and the shapes are the visual language network engineers already read.
• Cloud zones → the matching vendor pack. An AWS VPC drawn with Cisco routers is actively misleading.
• Whitebox, mixed vendor, or vendor-neutral → affinity. Pick either symbol/ or tile/ and stay consistent within a diagram — mixing the two styles looks like an accident.
• Kubernetes → k8s.

Common Cisco picks:

cisco/switches/layer-3-switch
cisco/switches/workgroup-switch
cisco/routers/router
cisco/security/firewall
cisco/servers/file-server
cisco/servers/host
cisco/endpoints/laptop

Your own iconsCopy Anchor Link

Drop SVGs into icon-packs/<pack>/svg/<Category>/<name>.svg and run npm run marrow -- icons index. Discovery is automatic — icons index scans every folder under icon-packs/, builds its manifest.json, and indexes all categories without requiring any configuration edits. Full walkthrough: Adding an icon pack.

Icons in the outputCopy Anchor Link

Only the icons a topology actually uses are inlined into its built HTML, as sprite definitions. A diagram with 12 distinct icons carries 12, not 2,850. The output stays self-contained and offline; nothing is fetched when the file opens.