Diagram-Design Primitives: Annotation Callouts, Sketchy Filter, and Icons Explained

Diagram‑Design provides three core visual primitives—annotation callouts, sketchy SVG filters, and a monochrome icon library—that enable editorial notes, hand‑drawn aesthetics, and scalable symbols in diagrams generated from YAML specifications.

Diagram‑Design is an open‑source diagramming system that transforms structured data into publication‑ready SVG graphics. According to the cathrynlavery/diagram-design source code, the tool exposes a curated set of diagram‑design primitives defined in the skills/diagram-design/references/ directory, allowing authors to enrich technical diagrams with marginal notes, stylistic filters, and standardized iconography without leaving the declarative format.

Core Primitives Available in Diagram-Design

The repository organizes primitives into three orthogonal families, each documented in a dedicated reference file and integrated via the main skill definition (SKILL.md).

Annotation Callouts

Annotation callouts are editorial notes that live in the margins of a diagram, rendered in italic Instrument Serif with a distinctive dashed Bézier leader pointing to the target element. This primitive is strictly limited to two callouts per diagram to prevent visual clutter. The styling rules, placement logic, and leader curve specifications reside in skills/diagram-design/references/primitive-annotation.md.

Sketchy Filter

The sketchy filter applies a hand‑drawn aesthetic via an SVG turbulence filter that wobbles stroke geometry while keeping text crisp and readable. Implemented in skills/diagram-design/references/primitive-sketchy.md, the filter exposes tunable parameters—including baseFrequency, numOctaves, scale, and seed—that control the intensity and randomness of the sketch effect. This primitive is ideal for essays, blog posts, or narrative presentations where a casual, storyboard‑like appearance is preferred.

Icon Library

The icon library provides a monochrome catalog of 41+ glyphs sized at 24×24 pixels, covering infrastructure concepts such as servers, databases, clouds, Kubernetes, and Docker. Defined in skills/diagram-design/references/primitive-icons.md, these icons inherit currentColor from their parent SVG elements, ensuring automatic adaptation to brand palettes. The symbols are compiled into assets/icons.html and referenced by name using the pattern <use href="#icon-{name}"/>.

How to Implement Each Primitive

You activate primitives by modifying your diagram’s YAML specification or by applying SVG filters to the output group. The SKILL.md file defines the grammar that wires these references into the final render pipeline.

Adding Annotation Callouts

To insert a marginal note, add an entry under the annotations key in your diagram specification. The callout requires a text string and a target node ID.

annotations:
  - text: "Legacy component – soon to be retired"
    target: legacy-node

The rendering engine automatically generates the dashed Bézier leader and positions the italic Instrument Serif text in the margin.

Enabling the Sketchy Filter

Apply the filter to the top‑level <g> element of your SVG output to affect all contained shapes. Keep text elements outside the filtered group to maintain crisp typography.

<g filter="url(#sketchy)">
    <!-- shapes go here -->
</g>
<text><!-- labels stay outside the filtered group --></text>

You can adjust the wobble intensity by editing the filter parameters in primitive-sketchy.md before running the generator.

Referencing Icons

Any component or connector can specify an icon: field that maps to a name listed in primitive-icons.md. The generator embeds the corresponding symbol via the <use> element.

- { id: sql-server, name: "SQL Server", icon: sqlserver, color: "#7a8c47" }

Because the icons reference currentColor, they automatically adopt the hex value defined in the parent element’s color attribute or the surrounding CSS variable.

Choosing the Right Primitive for Your Context

Selecting the appropriate primitive depends on the communication goal and audience expectations.

• Technical documentation: Avoid the sketchy filter to maintain precision; use annotation callouts sparingly for editorial asides.
• Essays or presentations: Enable the sketchy filter for a hand‑drawn narrative tone and add annotation callouts for side remarks or commentary.
• Standard architecture diagrams: Rely on the icon library to provide immediate visual recognition for infrastructure components.

Source Files and Implementation Details

The following files in the cathrynlavery/diagram-design repository define the primitive behavior:

• skills/diagram-design/references/primitive-annotation.md — Visual style, placement rules, and limits for annotation callouts.
• skills/diagram-design/references/primitive-sketchy.md — SVG filter definition, tuning parameters, and usage guidelines for the hand‑drawn variant.
• skills/diagram-design/references/primitive-icons.md — Complete list of icon names, sources (Tabler, Simple Icons, Devicon), and embedding instructions.
• skills/diagram-design/SKILL.md — Master skill description that aggregates all primitives into the diagram grammar.
• assets/icons.html — Generated asset file containing the SVG symbol definitions referenced by the icon library.

Summary

• Diagram‑Design primitives are defined in skills/diagram-design/references/ and activated via YAML specifications or SVG filters.
• Annotation callouts support up to two marginal notes per diagram, rendered in italic Instrument Serif with dashed Bézier leaders.
• The sketchy filter applies configurable turbulence to strokes via baseFrequency, numOctaves, scale, and seed parameters.
• The icon library offers 41+ 24×24px monochrome glyphs that inherit currentColor for automatic brand theming.

Frequently Asked Questions

How many annotation callouts can I add to a single diagram?

You may add up to two annotation callouts per diagram. This limit is enforced to preserve readability and prevent marginal clutter, as specified in primitive-annotation.md.

Can I customize the intensity of the sketchy filter?

Yes. The filter defined in primitive-sketchy.md exposes SVG turbulence parameters including baseFrequency, numOctaves, scale, and seed, which you can adjust to increase or decrease the wobble effect before rendering.

Do diagram-design icons support custom brand colors?

Absolutely. All icons in the library are monochrome and inherit currentColor from their parent SVG element. You can globally recolor the entire icon set by setting a CSS variable or inline style on the parent group.

Where are the primitive definitions stored in the repository?

Each primitive is documented in a dedicated markdown file within skills/diagram-design/references/: primitive-annotation.md, primitive-sketchy.md, and primitive-icons.md. The main SKILL.md file integrates these definitions into the diagram generation pipeline.

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