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

> Explore diagram-design primitives like annotation callouts, sketchy filters, and icons. Add editorial notes, hand-drawn styles, and scalable symbols to your diagrams with this YAML-based tool.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-13

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```yaml
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.

```svg
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-icons.md). The generator embeds the corresponding symbol via the `<use>` element.

```yaml
- { 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-annotation.md) — Visual style, placement rules, and limits for annotation callouts.
- [`skills/diagram-design/references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) — Master skill description that aggregates all primitives into the diagram grammar.
- [`assets/icons.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md).

### Can I customize the intensity of the sketchy filter?

Yes. The filter defined in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md), [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md), and [`primitive-icons.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-icons.md). The main [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file integrates these definitions into the diagram generation pipeline.