What Primitives Are Available for Diagram Creation in Diagram Design: The Complete Reference

The cathrynlavery/diagram-design skill provides four reusable diagram primitives—Annotation callout, Sketchy filter, Terminal-window, and Icon set—that layer visual effects on top of any underlying diagram geometry without altering the structure itself.

The cathrynlavery/diagram-design repository defines a modular approach to technical diagramming through composable visual primitives. These primitives, documented in the skills/diagram-design/references/ folder, allow you to augment architecture diagrams, flowcharts, and sequence diagrams via the command-line interface or YAML configuration keys.

The Four Core Diagram Primitives

According to SKILL.md and the reference documentation, the diagram primitives are optional layers that modify presentation while preserving the base diagram logic.

Annotation Callout

The Annotation callout primitive adds editorial marginalia using italic Instrument Serif text connected by a dashed Bézier leader. This primitive lives in the diagram margins and is ideal for side-notes, “as-you-type” explanations, or short warnings that do not interfere with the main flow.

As specified in skills/diagram-design/references/primitive-annotation.md, the callout renders as a distinct visual element separate from the diagram nodes and edges.

Sketchy Filter

The Sketchy filter applies an SVG turbulence-plus-displacement filter that gives every stroke a hand-drawn appearance. This effect is implemented in skills/diagram-design/references/primitive-sketchy.md and is particularly effective for essays, blog posts, or narrative contexts where an informal, sketched aesthetic is preferred.

The filter manipulates the SVG output directly, adding randomized displacement to straight lines to simulate organic drawing tools.

Terminal-Window

The Terminal-window primitive wraps the entire diagram in a faux terminal interface. As documented in skills/diagram-design/references/primitive-terminal.md, this wrapper includes a title bar with three dots, a $ prompt line, and monospaced typography throughout.

This primitive is optimized for developer-oriented announcements, CLI-product posts, and technical social cards where command-line authenticity is required.

Icon Set

The Icon set primitive provides a library of 55 monochrome IT and cloud icons defined in skills/diagram-design/references/primitive-icons.md. Icons are referenced by name (e.g., icon:aws, icon:kubernetes, icon:server) and automatically inherit the diagram’s current color (currentColor).

The library covers essential infrastructure components including laptops, servers, databases, and Kubernetes clusters, enabling consistent visual vocabulary across technical diagrams.

How to Apply Diagram Primitives

You enable these primitives via the diagram-design CLI or by adding specific keys to your diagram definition YAML. The following examples demonstrate practical usage for each primitive.

Enabling Annotation Callouts

Add an annotation block to your YAML to automatically trigger the primitive:

# sample.yaml – a simple flowchart with an editorial note

type: flowchart
nodes:
  - id: start
    label: Start
  - id: end
    label: End
edges:
  - from: start
    to: end
annotation:
  text: "This path represents the happy‑path execution."
  position: top‑right   # optional placement hint

Render the diagram with the annotation layer applied:

diagram-design render --input sample.yaml

Applying the Sketchy Filter

Use the --primitive flag with the sketchy argument to enable the hand-drawn effect:

diagram-design render --input diagram.yaml --primitive sketchy

This command wraps the output SVG in the turbulence filter defined in skills/diagram-design/references/primitive-sketchy.md.

Wrapping Diagrams in Terminal Chrome

Enable the terminal aesthetic using the CLI flag:

diagram-design render --input diagram.yaml --primitive terminal

The resulting SVG incorporates the faux terminal UI elements—title bar, prompt line, and monospace text—specified in skills/diagram-design/references/primitive-terminal.md.

Inserting Icons from the Primitive Set

Reference icons by name in your node definitions:

type: architecture
nodes:
  - id: web
    label: Web Server
    icon: server   # pulls the `server` icon from primitive‑icons.md

  - id: db
    label: Database
    icon: database
edges:
  - from: web
    to: db

The CLI resolves the icon key against the 55-icon catalog in skills/diagram-design/references/primitive-icons.md and injects the corresponding SVG snippet.

Summary

• Four primitives available: Annotation callout, Sketchy filter, Terminal-window, and Icon set.
• Documentation location: All primitives are specified in skills/diagram-design/references/primitive-{name}.md files.
• Activation methods: Via CLI flags (--primitive sketchy, --primitive terminal) or YAML configuration keys (e.g., annotation: block, icon: properties).
• Visual scope: Primitives affect presentation only; they do not modify the underlying diagram geometry or logic.
• Icon library size: 55 monochrome IT/cloud icons available for immediate use.

Frequently Asked Questions

How do I combine multiple diagram primitives in a single render?

You can apply multiple primitives simultaneously by including both CLI flags and YAML configuration keys in the same command. For example, you might enable the Terminal-window wrapper via --primitive terminal while defining icons in your YAML file. The skill processes these layers independently, allowing you to stack the Sketchy filter on top of a Terminal-window wrapped diagram.

Where is the complete list of available icons documented?

The complete catalog of 55 icons is documented in skills/diagram-design/references/primitive-icons.md. This file maps icon names (such as aws, kubernetes, server, and database) to their SVG definitions and specifies that all icons inherit the currentColor property for consistent theming.

Can I use the Annotation callout primitive with any diagram type?

Yes, the Annotation callout is designed to work across all diagram types including architecture diagrams, flowcharts, and sequence diagrams. Because it lives in the margins with a dashed Bézier leader pointing to the relevant content, it does not interfere with node positioning or edge routing defined in the base diagram geometry.

What is the performance impact of the Sketchy filter on SVG file size?

The Sketchy filter applies an SVG turbulence-plus-displacement filter at render time, which adds filter definitions to the output markup. While this increases file size slightly compared to clean vector output, the effect is calculated during the diagram-design render process and does not impact runtime performance of the resulting SVG.

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