# Diagram-Design Primitives: Complete Guide to Annotation, Sketchy, Icons, and Terminal Variants

> Explore diagram-design primitives including annotation callouts, sketchy filters, icons, and terminal variants. Enhance your diagrams with these SVG primitives from cathrynlavery/diagram-design.

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

---

**The diagram-design skill provides three optional SVG-based primitives—annotation callouts, sketchy filters, and terminal window overlays—that you can apply to any diagram type via markdown flags.**

The **cathrynlavery/diagram-design** repository defines a modular primitive system for adding editorial, aesthetic, and contextual variants to generated diagrams. These primitives are optional overlays defined in dedicated reference files and invoked through simple flags in the skill manifest.

## Annotation Callout Primitive

The **annotation callout** adds marginal editorial notes without competing with the main diagram grammar. It combines italic typography with a dashed Bézier leader line.

### Visual Specification

According to [`primitive-annotation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md), the annotation primitive uses three SVG elements:

```svg
<!-- 1️⃣ Italic Instrument Serif label -->
<text x="904" y="36" fill="#2d3142"
      font-size="14" font-style="italic"
      font-family="'Instrument Serif', serif"
      text-anchor="end">no imports, no configuration</text>
<!-- 2️⃣ Dashed Bézier leader -->
<path d="M 820 44 Q 700 84 520 216"
      fill="none"
      stroke="rgba(45,49,66,0.40)"
      stroke-width="1"
      stroke-dasharray="4,3"/>
<!-- 3️⃣ Landing dot -->
<circle cx="520" cy="216" r="2" fill="#2d3142"/>

```

### When to Use Annotation Primitives

- Marginal commentary or "aside" notes
- Maximum of **2 callouts per diagram**

### When to Avoid

- Inside the active diagram area
- With solid-stroke leaders (confuses with normal arrows)

## Sketchy Filter Primitive

The **sketchy filter** applies a hand-drawn "editorial" look using SVG turbulence and displacement effects. It wobbles every stroke while preserving text crispness.

### SVG Filter Implementation

The implementation in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) defines a reusable filter:

```svg
<defs>
  <filter id="sketchy" x="-2%" y="-2%" width="104%" height="104%">
    <feTurbulence type="fractalNoise"
                  baseFrequency="0.02"
                  numOctaves="2"
                  seed="4"/>
    <feDisplacementMap in="SourceGraphic" scale="1.5"/>
  </filter>
</defs>

<!-- Apply only to shape groups – keep text crisp -->
<g filter="url(#sketchy)">
  <rect x="10" y="10" width="80" height="50" fill="#eb6c36"/>
  <path d="M20 20 L70 20" stroke="#2d3142"/>
</g>
<text x="15" y="30" fill="#2d3142" font-family="Geist Mono">Label</text>

```

### Appropriate Contexts

- Essays, blog posts, and newsletters
- "Working-sketch" diagrams that signal non-final status

### Inappropriate Contexts

- Technical documentation requiring precision
- Dense label layouts (text becomes noisy)
- Dark backgrounds (wobble artifacts appear)

## Terminal / CLI-Window Variant

The **terminal variant** wraps diagrams in a fixed-skin overlay: title bar with three dots, `$` prompt, and monospace typography. It uses a dedicated token palette (`terminal-*`) defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

### HTML Structure and Tokens

From [`template-terminal.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-terminal.html) and [`primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md):

```html
<div class="terminal">
  <div class="title-bar">
    <span class="dot"></span><span class="dot"></span><span class="dot"></span>
    <span class="title"># Project Demo</span>

  </div>
  <pre class="prompt"><span class="accent">$</span> npm run build</pre>
  <!-- Diagram SVG goes here – it inherits the `terminal-ink` color for text -->
</div>

```

### Terminal CSS Token Palette

The variant automatically injects these variables:

- `--terminal-page`
- `--terminal-paper`
- `--terminal-bar`
- `--terminal-border`
- `--terminal-ink`
- `--terminal-muted`
- `--terminal-soft`
- `--terminal-accent`
- `--terminal-accent-tint`

### Recommended Use Cases

- Dev-tool announcements and CLI-product posts
- Technical social cards requiring terminal aesthetics

### Limitations

- **Not brand-matched**—the terminal skin overrides brand tokens
- Enforces a **one-accent rule**, limiting multi-color diagrams

## How to Invoke Primitives

All three primitives are referenced from [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and applied via markdown flags when invoking the skill:

| Flag | Primitive | Source File |
|------|-----------|-------------|
| `annotation` | Annotation callout | [`primitive-annotation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md) |
| `sketchy` | Sketchy filter | [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) |
| `terminal` | Terminal window | [`primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md) |

Primitives can be **combined** with any base diagram type (flowchart, sequence, tree, etc.).

## Key Source Files

| File Path | Role |
|-----------|------|
| [`skills/diagram-design/references/primitive-annotation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-annotation.md) | Annotation grammar, colors, anti-patterns |
| [`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 and tuning parameters |
| [`skills/diagram-design/references/primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-terminal.md) | Terminal skin specification and guidelines |
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Central manifest with invocation flags |
| [`skills/diagram-design/assets/template-terminal.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-terminal.html) | Executable HTML wrapper template |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Typography and token definitions |

## Summary

- **Three primitives** are available: annotation callouts, sketchy filters, and terminal window overlays
- All are **SVG-based** and **optionally applied** via flags in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)
- **Annotation** uses Instrument Serif italics with dashed Bézier leaders—limit 2 per diagram
- **Sketchy** applies turbulence displacement—avoid on dark backgrounds or dense layouts
- **Terminal** provides a complete CLI chrome with dedicated CSS tokens—not brand-compatible
- Each primitive has **dedicated documentation** in the `references/` directory

## Frequently Asked Questions

### What diagram types support these primitives?

Any base diagram type—flowchart, sequence, tree, or custom—supports all three primitives. The system is designed for composability; flags are passed at invocation time regardless of underlying diagram structure.

### Can I combine multiple primitives on one diagram?

Yes. You can apply `annotation` and `sketchy` together, or `terminal` with `annotation`. However, `terminal` and `sketchy` are rarely combined since the terminal skin has fixed styling that conflicts with hand-drawn aesthetics.

### Where are the icon primitives mentioned in the question?

The repository's current primitive set focuses on **annotation**, **sketchy**, and **terminal** variants. Icon-based primitives are not implemented as standalone overlays; icons should be embedded directly in diagram SVGs using the base diagram grammar.

### How do I tune the sketchy filter intensity?

Modify the `scale` attribute in `feDisplacementMap` (default: `1.5`) and the `baseFrequency` in `feTurbulence` (default: `0.02`). Higher scales increase wobble amplitude; higher base frequencies create finer grain noise. These parameters are documented with tuning guidance in [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md).