What Primitive Diagram Elements Are Available in Diagram-Design? (Annotation, Sketchy, Terminal)

Diagram-Design provides three primitive diagram elements—Annotation Callout, Sketchy Filter, and Terminal Window—that layer visual meaning and stylistic distinction over any diagram type.

The cathrynlavery/diagram-design repository ships a focused set of styling primitives designed to enhance diagrams without interfering with their core grammar. These elements act as independent overlays that can be enabled or omitted via the skill's configuration, following strict rules to preserve readability.

The Three Core Primitive Diagram Elements

Each primitive serves a distinct purpose and carries specific constraints. Below is the complete breakdown of available elements in diagram-design.

Annotation Callout

The Annotation Callout provides editorial asides that sit outside the primary diagram flow.

Key characteristics defined in primitive-annotation.md:

• Italic Instrument Serif typography
• Dashed Bézier leader line connecting text to target
• Small landing dot at connection point
• Maximum of two annotations per diagram

Constraint rules require placement in margins, dashed leaders only, and no substitution with italic Sans or Mono fonts.

SVG implementation:

<!-- Italic Instrument Serif text -->
<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>

<!-- 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"/>

<!-- Landing dot -->
<circle cx="520" cy="216" r="2" fill="#2d3142"/>

Sketchy Filter

The Sketchy Filter applies a hand-drawn, "working-sketch" aesthetic through SVG filter primitives.

Per primitive-sketchy.md, this filter:

• Uses feTurbulence with fractal noise and feDisplacementMap displacement
• Applies exclusively to shape groups—text remains crisp and unfiltered
• Exposes tunable parameters: baseFrequency, numOctaves, scale, seed

Usage rules prohibit application to dense or dark diagrams to maintain legibility.

SVG filter definition:

<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 to shape group only -->
<g filter="url(#sketchy)">
  <rect x="10" y="10" width="100" height="50" fill="#fff"/>
  <path d="M20,20 L80,20" stroke="#000"/>
</g>

<!-- Text stays outside the filtered group -->
<text x="20" y="45" font-size="12">Labels go here</text>

Terminal Window

The Terminal Window primitive wraps diagrams in a CLI-style frame, optimized for developer-tool announcements and technical social cards.

As specified in primitive-terminal.md:

• Title bar with three status dots
• Prompt line prefixed with $
• Monospace typography throughout
• Fixed terminal-* token palette (no brand inheritance)
• Single accent color maximum

HTML/CSS structure:

<div class="terminal">
  <div class="titlebar">
    <div class="dot accent"></div>
    <div class="dot"></div>
    <div class="dot"></div>
    <div class="titlebar-name">loop.sh — self-improving-loop</div>
  </div>
  <main class="frame">
    <p class="prompt"><span class="sign">$</span> diagram-design render --type loop</p>
    <h1># The self‑improving loop</h1>

    <svg><!-- diagram SVG here --></svg>
  </main>
</div>

Configuration and Enablement

All three primitive diagram elements are diagram-type agnostic. Whether rendering flowcharts, sequence diagrams, or tree structures, these primitives layer on top through skill configuration.

The SKILL.md file lists the "Hand-drawn variant" pointing to primitive-sketchy.md and the "Terminal-window primitive" as optional styling layers, confirming their first-class status in the diagram-design system.

File Reference

File	Contents
primitive-annotation.md	Full annotation callout specification including grammar, color values, and placement rules
primitive-sketchy.md	SVG filter definition, parameter tuning guide, and application constraints
primitive-terminal.md	Complete HTML/CSS terminal template with typographic scaling
SKILL.md	High-level primitive inventory and enablement guidance

Summary

• Annotation Callout adds marginal commentary with serif italics and dashed leaders—limit two per diagram
• Sketchy Filter produces hand-drawn aesthetics via SVG turbulence filters, applied only to shapes never text
• Terminal Window delivers full-page CLI framing with monospace typography and fixed color tokens
• All primitives are defined in dedicated markdown specification files and referenced from the central SKILL.md

Frequently Asked Questions

Can I use multiple primitives on the same diagram?

Yes. The primitives are designed to layer independently. According to the diagram-design source, you could apply the Sketchy Filter to shapes within a Terminal Window frame, though the Terminal primitive itself is a full-page skin that typically serves as the outermost container.

What happens if I apply the Sketchy Filter to text elements?

This violates the specification in primitive-sketchy.md. The filter must apply only to shape groups; text elements must remain outside filtered groups to preserve legibility. The turbulence displacement would otherwise render typography unreadable.

Are there limits to how many annotations I can add?

Yes—primitive-annotation.md strictly limits annotations to two per diagram. This constraint preserves visual hierarchy and prevents marginal clutter from competing with the primary diagram grammar.

Can I customize the Terminal Window colors beyond the single accent?

No. The Terminal primitive enforces a fixed terminal-* token palette with only one accent color permitted. As documented in primitive-terminal.md, there is no brand token inheritance to maintain consistent CLI aesthetics across all terminal-styled outputs.

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