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

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, the annotation primitive uses three SVG elements:

<!-- 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 defines a reusable filter:

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

HTML Structure and Tokens

From template-terminal.html and primitive-terminal.md:

<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 and applied via markdown flags when invoking the skill:

Flag	Primitive	Source File
annotation	Annotation callout	primitive-annotation.md
sketchy	Sketchy filter	primitive-sketchy.md
terminal	Terminal window	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	Annotation grammar, colors, anti-patterns
skills/diagram-design/references/primitive-sketchy.md	SVG filter definition and tuning parameters
skills/diagram-design/references/primitive-terminal.md	Terminal skin specification and guidelines
skills/diagram-design/SKILL.md	Central manifest with invocation flags
skills/diagram-design/assets/template-terminal.html	Executable HTML wrapper template
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
• 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.

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