# How to Add Custom or Branded Icons to Diagram‑Design: A Complete Guide
> Learn to add custom or branded icons to diagram design. Register SVG symbols or embed PNGs directly to enhance your diagrams with this complete guide.
- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-14
---
**You can add custom or branded icons to diagram‑design by either registering an SVG symbol in the icon library (referenced as `icon:name`) or embedding a custom PNG/image directly as a node in your source diagram.**
As of the latest release, diagram‑design supports two distinct pathways for incorporating non‑standard graphics: the **icon reference system** for scalable, theme‑aware symbols, and the **image embed system** for raster logos and photographs. This guide explains both approaches using actual source code locations from the `cathrynlavery/diagram-design` repository.
---
## Understanding the Two Icon Systems
Before adding icons, choose the approach that matches your asset type:
| Approach | Best For | Output Element | Source File |
|----------|----------|----------------|-------------|
| **Icon reference** (`icon:name`) | Brand logos, UI symbols, scalable graphics | `` | [`icons.html`](https://github.com/cathrynlavery/diagram-design/blob/main/icons.html) symbol definitions |
| **Custom image** | Photographs, complex raster logos, legacy assets | `` | Draw.io `image` style nodes |
Both systems are handled by [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py), which processes source diagrams and emits the appropriate SVG elements.
---
## Method 1: Adding Custom Icons to the Icon Library
The **icon library** stores reusable SVG symbols that automatically inherit the diagram’s color scheme. This is the preferred method for branded icons you’ll use repeatedly.
### Step 1: Define the SVG Symbol
Open [`skills/diagram-design/assets/icons.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/icons.html) and add a new `` block:
```html
```
Follow these conventions from the primitive icon system:
- Use `viewBox="0 0 24 24"` for consistency with built‑in icons.
- Apply `fill="currentColor"` or `stroke="currentColor"` so the icon adapts to theme colors.
- Keep paths optimized; the built‑in AWS icon uses this same pattern.
### Step 2: Reference in Your Diagram
In Mermaid YAML or Draw.io metadata, use the `icon` field:
```yaml
- { id: api-gateway, name: "API Gateway", icon: mybrand }
```
The renderer, per `type‑it‑state.md`, generates:
```svg
```
### Step 3: Verify in drawio_extract.py
The parser at lines 268‑279 of [`scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/drawio_extract.py) detects `shape.startswith("icon:")` and routes to the symbol reference path:
```python
if shape.startswith("icon:"):
icon_name = shape[5:] # strip 'icon:' prefix
svg_element = f''
```
---
## Method 2: Embedding Custom PNGs and Raster Images
For logos or graphics that cannot be converted to SVG paths, embed them as **image nodes**.
### In Draw.io Source Files
Set any shape’s style to `image` and provide a URL or data‑URI:
```xml
```
Or use a base64‑encoded data‑URI for self‑contained diagrams:
```xml
shape=image;image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34...
```
### How the Importer Handles Images
Per [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md), the importer creates an `image` node type:
| Property | Value |
|----------|-------|
| `type` | `image` |
| `src` | Original image URL or data‑URI |
| `preserveAspect` | `true` (default) |
The export stage renders this as a standard SVG `` element:
```svg
```
### Important Limitations
- **Embedded images are not recolored** — they render exactly as provided, ignoring the diagram’s theme.
- **Missing images fallback** to a labeled rectangle; the tool never retains broken references.
---
## Registering Icons in the Primitive Catalog
To make custom icons discoverable, document them in [`skills/diagram-design/references/primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-icons.md). The built‑in catalog follows this format:
```markdown
| Icon | ID | Source |
|------|----|--------|
| AWS | `aws` | Official brand kit |
| Azure | `azure` | Microsoft design resources |
| MyBrand | `mybrand` | Custom addition |
```
This reference file is not enforced at runtime but aids maintainability and collaboration.
---
## Complete Workflow Example
Here’s an end‑to‑end example combining both methods:
**1. Register a custom SVG icon:**
```html
```
**2. Create a diagram YAML file:**
```yaml
diagram:
title: "Acme Corp Infrastructure"
nodes:
- { id: frontend, name: "Web App", icon: acmecorp }
- { id: legacy, name: "Legacy DB", icon: image, src: "assets/legacy-db.png" }
edges:
- { from: frontend, to: legacy }
```
**3. Run the generator:**
```bash
python -m diagram_design generate infrastructure.yaml --output out.svg
```
The resulting `out.svg` contains both the themed `