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

> Discover the four essential diagram primitives annotation callout sketchy filter terminal window and icon set available in diagram design to enhance your visuals without structural changes.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: api-reference
- Published: 2026-08-15

---

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

```yaml

# 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:

```bash
diagram-design render --input sample.yaml

```

### Applying the Sketchy Filter

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

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-sketchy.md).

### Wrapping Diagrams in Terminal Chrome

Enable the terminal aesthetic using the CLI flag:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-terminal.md).

### Inserting Icons from the Primitive Set

Reference icons by name in your node definitions:

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