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

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, 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 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. 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 located at skills/diagram-design/assets/icons.html.

Adding Icons to Architecture Components

Architecture diagrams, defined in 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.

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, 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.

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.

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 or the live browser interface before deployment.

Summary

• Icons are defined in 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. 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.

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

Currently, the system only recognizes icon names present in 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.

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