# How to Use Icons in Architecture and Sequence Diagrams with cathrynlavery/diagram-design

> Learn to add monochrome icons to architecture and sequence diagrams using cathrynlavery/diagram-design. Enhance your diagrams with custom icons that inherit theme colors for a polished look.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-18

---

**You can add 24 × 24 px monochrome icons to both architecture components and sequence diagram labels by setting the `icon:` property to a name defined in [`primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-icons.md), which automatically inherits the active theme color via SVG `currentColor`.**

The `cathrynlavery/diagram-design` repository provides a YAML-driven diagramming system where visual components gain semantic clarity through scalable iconography. Icons are centrally cataloged in [`skills/diagram-design/references/primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-icons.md) and referenced by name, enabling consistent visual language across architecture and sequence diagrams without manual SVG embedding.

## Icon Catalog and Naming Conventions

All built-in icons reside in **[`skills/diagram-design/references/primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-icons.md)**. Each entry uses an ATX heading `### <name>` (for example, `### server` or `### database`) containing a 24 × 24 px SVG snippet. The markup utilizes `stroke="currentColor"` to ensure automatic color inheritance from the parent diagram theme.

You can browse the available icons via the [icon library page](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/icons.html) located at [`skills/diagram-design/assets/icons.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/icons.html).

## Adding Icons to Architecture Components

Architecture diagrams, defined in **[`skills/diagram-design/references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-architecture.md)**, accept an `icon:` field within component definitions. The value must exactly match a heading name from [`primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-icons.md).

```yaml
components:
  - id: sql-server
    name: "SQL Server"
    sub: "on-premises · core RDBMS"
    icon: sqlserver
    color: "#7a8c47"

```

When rendered, the icon appears as a 24 × 24 px graphic to the left of the component name, inheriting the diagram’s **ink** color in light mode and **paper** color in dark mode. If the `icon:` key is omitted, the component name aligns left without graphical decoration.

## Embedding Icons in Sequence Diagram Labels

Sequence diagrams, specified in **[`skills/diagram-design/references/type-sequence.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-sequence.md)**, support icons on connector labels using the same `icon:` property. According to the rendering specification, the label width calculates as `text_w + (icon ? 30 : 12)` pixels to accommodate the icon container.

```yaml
connectors:
  - from: survey-solutions
    to: shared-drive
    label: "CSV"
    icon: csv
    style: link

```

The icon renders inside the label’s masked box, positioned to the left of the text, and adopts the connector’s style color (**accent**, **link**, or **neutral**).

## Icon Rendering, Sizing, and Theming

**Fixed Dimensions:** Icons render at a strict 24 × 24 px viewport. While custom scaling requires wrapping `<use>` elements in transformed SVG groups, the default sizing maintains visual consistency across diagram exports.

**Color Inheritance:** Because source SVGs employ `currentColor`, icons automatically adapt to the active color palette without manual configuration. Custom component colors (set via `color: "#hex"`) do not override icon strokes; icons remain theme-aware to preserve contrast.

**Draw.io Import Compatibility:** When importing from Draw.io, the `icon:` field maps to standard library references as documented in **[`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)**.

## Fallback Behavior and Validation

If the `icon:` value does not correspond to any entry in the catalog, the system silently omits the icon and renders only the left-aligned text. This non-breaking behavior ensures diagram stability, but you should validate icon names against the [primitive-icons.md catalog](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-icons.md) or the live browser interface before deployment.

## Summary

- Icons are defined in [`primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-icons.md) with 24 × 24 px SVG snippets using `stroke="currentColor"`
- Architecture components use the `icon:` field to display graphics left of the component name
- Sequence diagram connectors support `icon:` on labels, expanding the label box by 30px
- Icons inherit theme colors automatically and adapt to dark or light modes
- Invalid icon names fail silently without breaking the diagram render

## Frequently Asked Questions

### Where is the master list of available icons stored?

The complete icon catalog lives in [`skills/diagram-design/references/primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-icons.md). Each icon is defined under a level‑3 heading (e.g., `### server`) containing the SVG markup. You can also browse them visually at [`skills/diagram-design/assets/icons.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/icons.html).

### Can I use custom SVG icons not listed in the primitive catalog?

Currently, the system only recognizes icon names present in [`primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-icons.md). To use custom graphics, you must add the SVG snippet to that file under a new heading name, ensuring it uses `stroke="currentColor"` for proper theming across light and dark modes.

### How do icons affect sequence diagram label positioning?

Icons increase the label container width by 30 pixels (compared to 12 pixels without), but they do not alter connector routing logic. The routing algorithm ignores label decorations, though the expanded box prevents text overlap with adjacent diagram elements.

### What happens to icons when exporting diagrams to static formats?

Icons render as inline SVG elements during export, preserving their `currentColor` inheritance. When rasterizing to PNG or other bitmap formats, the icons adopt the active theme’s ink color at the time of generation, maintaining visual consistency with the vector output.