# Icon Set Architecture and Integration in Diagram-Design: A Technical Deep Dive > Explore the Diagram-Design icon set architecture. Learn how SVGs are fetched, normalized, and cached for seamless integration using a centralized manifest and currentColor. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: deep-dive - Published: 2026-09-11 --- **The Diagram-Design icon set uses a centralized manifest in [`scripts/build-icons.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/build-icons.py) to fetch, normalize, and cache SVGs from multiple upstream sources, outputting ready-to-use snippets in [`primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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. ```python # 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-icons.md), a comprehensive catalog containing fenced `` 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. ```markdown ### laptop User laptop or workstation. ```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 `` 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 `` element. ```xml ``` ```xml ``` ## Summary - The **ICONS** dictionary in [`scripts/build-icons.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-icons.md)** for code reference and **[`icons.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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 `` or `` element using the `fill` or `stroke` attribute. The icon inherits this value automatically.