Icon Set Architecture and Integration in Diagram-Design: A Technical Deep Dive

The Diagram-Design icon set uses a centralized manifest in scripts/build-icons.py to fetch, normalize, and cache SVGs from multiple upstream sources, outputting ready-to-use snippets in primitive-icons.md that inherit colors via currentColor for seamless diagram integration.

The cathrynlavery/diagram-design repository implements a robust icon set architecture that transforms disparate third-party SVG libraries into a unified, diagram-ready collection. By defining a structured manifest and normalization pipeline, the project ensures consistent rendering across icons sourced from Tabler, Simple Icons, Devicon, and direct URLs. Understanding this architecture reveals how the build system generates both documentation and integration artifacts.

Core Architecture of the Icon Set

The ICONS Manifest Structure

In scripts/build-icons.py, the architecture centers on a nested dictionary named ICONS (lines 60‑74) that acts as the single source of truth. Each top-level key represents a category—such as Compute, Network, or Brand—mapping to a list of tuples containing the slot name, source identifier, upstream name, and description.

# scripts/build-icons.py – lines 60-74

ICONS: dict[str, list[tuple[str, str, str, str]]] = {
    "Compute": [
        ("laptop", "tabler", "device-laptop", "User laptop or workstation."),
        ("phone",  "tabler", "device-mobile", "Mobile phone or tablet client."),
    ],
    "People": [
        ("user",   "tabler", "user",          "End user or single actor."),
    ],
}

Multi-Source Icon Provenance

The architecture abstracts five distinct upstream providers through string identifiers in the manifest. Tabler provides general UI icons under MIT license, while Simple Icons supplies brand silhouettes as CC0. The system also supports Devicon for developer tools, logz for additional logos, and raw URL sources for niche tools like Hop or Pentaho. Lines 47‑53 construct the appropriate download endpoint for each type, enabling a unified fetch interface despite differing upstream APIs.

Build Pipeline: Fetching and Normalization

Local Caching Strategy

The build script implements an intelligent cache at scripts/vendor/icons/ to avoid redundant network requests. When processing an icon, the script checks for existing files (lines 10‑13); if absent, it executes the relevant fetch_* function to retrieve the SVG and stores it locally (lines 27‑30). This ensures reproducible builds and offline capability after the initial run.

SVG Normalization for Consistency

Because upstream icons vary in viewBox, fill rules, and stroke styles, the pipeline forces standardization to 24×24 pixels and replaces all color values with currentColor. The function normalize_tabler() strips placeholder paths and re-wraps elements with standard attributes, while normalize_devicon() and normalize_logz() convert fills to currentColor. This guarantees that every icon inherits the parent SVG or group element's color palette, enabling dynamic theming without inline styles.

Integration Methods and Generated Artifacts

The Markdown Catalog (primitive-icons.md)

The script emits skills/diagram-design/references/primitive-icons.md, a comprehensive catalog containing fenced <svg> snippets for every slot. Each entry includes the icon's description and source attribution, allowing developers to copy-paste code directly into diagram files. For example, the laptop slot renders a 24×24 SVG with stroke="currentColor", ready for immediate use.

### laptop

User laptop or workstation.

```svg
<svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24"
     fill="none" stroke="currentColor" stroke-width="1.5"
     stroke-linecap="round" stroke-linejoin="round">
    <path d="M3 5a1 1 0 0 1 1 -1h16a1 1 0 0 1 1 1v10a1 1 0 0 1 -1 1h-16a1 1 0 0 1 -1 -1v-10"/>
    <path d="M7 20h10"/>
    <path d="M9 16v4"/>
    <path d="M15 16v4"/>
</svg>

Source: Tabler Icons / device-laptop (MIT)

### The HTML Gallery (icons.html)

For visual discovery, the script generates [`skills/diagram-design/assets/icons.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/icons.html) using the `GALLERY_TEMPLATE` (lines 75‑95). This responsive grid displays every icon with its slot name, enabling designers to browse the set before selecting the appropriate identifier.

### Embedding Icons in Diagrams

Integration relies on the `currentColor` inheritance mechanism. Developers insert the generated `<svg>` snippet inside a parent group element; the icon automatically adopts the group's fill or stroke properties. For scaling or positioning, wrap the snippet in a `<g transform="translate(x,y) scale(n)">` element.

```xml
<!-- Simple inline use -->
<g fill="#2d3142">
  <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24"
       fill="none" stroke="currentColor" stroke-width="1.5">
      <path d="M3 5a1 1 0 0 1 1 -1h16a1 1 0 0 1 1 1v10..."/>
  </svg>
</g>

<!-- Scaling and positioning -->
<g transform="translate(200,150) scale(2)">
  <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="currentColor">
      <path d="M10.204 …"/>
  </svg>
</g>

Summary

• The ICONS dictionary in scripts/build-icons.py defines a category-based manifest sourcing from Tabler, Simple Icons, Devicon, logz, and URLs.
• A caching layer at scripts/vendor/icons/ minimizes network requests during builds.
• Normalization functions standardize viewBox and force currentColor for universal theme support.
• Generated artifacts include primitive-icons.md for code reference and icons.html for visual browsing.
• Icons integrate via copy-paste SVG snippets that inherit parent color through currentColor.

Frequently Asked Questions

How does Diagram-Design handle icons from different upstream licenses?

The manifest tracks source provenance, and the build pipeline respects the original licenses (MIT, CC0) while normalizing the SVGs. The generated primitive-icons.md includes attribution for each icon, ensuring compliance when integrating into diagrams.

What is the default size of normalized icons in the icon set?

All icons are normalized to a 24×24 pixel viewBox unless the source requires special handling. This standardization ensures consistent alignment and scaling when multiple icons appear in the same diagram.

Can I add custom icons that are not in the predefined sources?

Yes. The architecture supports the url source type in the ICONS manifest, allowing specification of direct SVG URLs for tools not covered by Tabler, Simple Icons, Devicon, or logz. The normalize_url() function processes these identically to standard sources.

How do I change the color of an icon when using it in a diagram?

Because the normalization pipeline forces currentColor for all fills and strokes, you simply set the color on a parent <g> or <svg> element using the fill or stroke attribute. The icon inherits this value automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}