Skip to content

Icon catalog

The official Azure Architecture Icons package is not committed. scripts/fetch-icons.mjs downloads it (V24, Azure_Public_Service_Icons_V24.zip from the Azure Architecture Center), extracts the service SVGs by category folder (NNNNN-icon-service-<Name>.svg) and the group icons into assets/azure-icons/ (git-ignored; override with ARCHIFY_AZURE_ICONS) and rebuilds data/catalog.json through src/catalog-build.mjs. A small zero-dependency ZIP reader (src/zip.mjs) does the extraction.

The official Power Platform icons (https://learn.microsoft.com/power-platform/guidance/icons) are fetched by the same script (POWER_URL, override with ARCHIFY_POWER_ICON_URL, skip with --no-power). The zip's <Name>_scalable.svg files are renamed through POWER_NAMES and extracted to assets/azure-icons/power-platform/; they appear in the catalog as category power-platform with ids copilot-studio, agent-365, ai-builder, dataverse, power-apps, power-automate, power-pages and microsoft-power-platform (the Azure package's own power-platform icon keeps that id). They have no draw.io Azure-library equivalent, so the draw.io export embeds them as SVG, and the cost engine reports them as not estimated.

Microsoft Fabric icons (https://learn.microsoft.com/fabric/fundamentals/icons) come from the docs-samples/Icons.zip in microsoft/fabric-samples (a ~30 MB npm package; override with ARCHIFY_FABRIC_ICON_URL, skip with --no-fabric). fetch-icons.mjs keeps the five workload icons (48 px colour: fabric, fabric-power-bi, fabric-real-time-intelligence, fabric-data-engineering, fabric-data-science) and every 64 px item icon (fabric-lakehouse, fabric-data-agent, fabric-semantic-model, fabric-event-house, fabric-eventstream, …) as category fabric. The Fabric workload "OneLake" has no icon of its own; use the lakehouse icon.

The official Dynamics 365 icons (https://learn.microsoft.com/dynamics365/get-started/icons) are fetched the same way (D365_URL, ARCHIFY_D365_ICON_URL, --no-d365): the <Name>_scalable.svg files are renamed through D365_NAMES to dynamics-365-<app> ids (dynamics-365-business-central, dynamics-365-sales, dynamics-365-customer-service, dynamics-365-field-service, dynamics-365-finance-and-operations, …; the product family icon is dynamics-365) in category dynamics-365. Aliases: business-central, bc, d365, d365-sales…

Catalog (data/catalog.json)

{ "generatedFrom": "Azure Architecture Icons V24",
  "categories": […], "services": [ { "key": "App-Services", "id": "app-services", "name": "App Services", "category": "compute", "file": "compute/10035-icon-service-App-Services.svg" } ],
  "groups": [ { "key": "Subscription", "dark": false, "file": "…" } ],
  "general": [ { "id": "users", "name": "Users", "file": "general/…" } ] }

Currently 625 services (539 Azure, 8 Power Platform, 62 Fabric and 16 Dynamics 365), 97 general icons and 8 group icons. Ids are slugs of the file name with azure-/microsoft- prefixes removed. GROUP_ICON_KEYS in catalog-build.mjs maps group kinds to icons (Subscription, Resource-Group, Management-Group, Region, VNet, Subnet, NSG, Availability-Set). Azure has no separate "resource" icon tier, so catalog.resources is empty.

data/aliases.json maps friendly names (functions, aks, cosmos, apim, front-door) to service ids; a separate map exists for general icons.

Resolution (src/catalog.mjs)

  • resolveIcon(ref) accepts a service id or alias, a full key, res:<id>, or gen:<id>; it returns { kind: "service" | "resource" | "general", entry } or null.
  • searchIcons(query, limit) ranks whole-word and word-prefix matches (so "ses" does not hit "databases"); aliases always qualify.
  • didYouMean(ref) powers the suggestions in validation errors (Levenshtein).
  • iconFile(entry) and groupIconFile(key, dark) return absolute paths.

Adding or changing icons

  1. Update the package URL in scripts/fetch-icons.mjs (and THIRD_PARTY_NOTICES.md release number).
  2. npm run icons:fetch, then npm test.
  3. Add aliases for new popular services in data/aliases.json.
  4. Re-run npm run drawio:map if draw.io has new Azure icons, and check every catalog service maps to a draw.io Azure icon in the tests.
  5. Re-render examples; icons are embedded in every page.

Never alter icons

Microsoft's terms for the Azure icons forbid cropping, flipping, rotating, distorting or recolouring. The renderer embeds files unmodified; only gradient ids are prefixed to avoid collisions, and symbol ids are sanitised to selector-safe characters.