How to Add Annotation Callouts to Diagrams in diagram-design

Diagram-design provides a dedicated annotation callout primitive consisting of three SVG elements—italic serif text, a dashed Bézier leader, and an optional landing dot—allowing you to add editorial asides to diagram margins.

The cathrynlavery/diagram-design repository implements a specialized annotation system for technical diagrams. Adding annotation callouts to diagrams requires understanding the specific SVG primitive defined in the design system's reference documentation. This guide demonstrates both manual SVG insertion and the SKILL CLI workflow for positioning callouts in diagram margins.

Understanding the Annotation Callout Primitive

According to primitive-annotation.md in the repository's reference documentation, every annotation callout comprises exactly three SVG components. The system reserves the Instrument Serif italic font exclusively for these callouts, distinguishing editorial text from primary diagram labels.

The three mandatory elements include:

• A styled italic serif text label positioned in the diagram margins
• A dashed Bézier leader line connecting the text to the relevant diagram element
• An optional landing dot that provides a visual anchor at the leader's endpoint

The design system enforces strict limits: you may add a maximum of two annotation callouts per diagram. Additionally, the leader line must use a specific dash pattern (stroke-dasharray="4,3") to visually distinguish it from primary arrows and connectors.

Adding Callouts via Direct SVG Insertion

For precise control over positioning, insert the three-element SVG fragment directly into your diagram source. According to the source code in skills/diagram-design/references/primitive-annotation.md, place the callout outside the active diagram area to avoid overlapping primary content.

<!-- 1. Italic Instrument Serif text (the callout body) -->
<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 (optional) -->
<circle cx="520" cy="216" r="2" fill="#2d3142"/>

The <text> element must specify font-family="'Instrument Serif', serif" and font-style="italic" to comply with the style guide. The <path> element requires stroke-dasharray="4,3" to maintain the visual distinction between annotation leaders and primary diagram arrows. Adjust the x and y coordinates to position the callout in available margin space such as top-right or bottom-left corners.

Adding Callouts Using the SKILL CLI

The SKILL command-line interface automates callout generation when you use the diagram-design command. As documented in SKILL.md, the callout primitive appears under "Core SVG Primitives" and supports shorthand syntax in markdown-based diagram descriptions.

Create a SKILL markdown file (e.g., my-diagram.md) with the following syntax:

> *no imports, no configuration*  
> ^{callout}

Then execute the pipeline:

diagram-design my-diagram.md --output diagram.svg

The engine translates the ^{callout} marker into the standard three-element SVG fragment, automatically positioning it in a free corner while respecting the two-callout maximum limit. This approach ensures consistent typography and styling without manual SVG editing.

Design Constraints and Style Guidelines

The style-guide.md file enforces the visual properties of annotation callouts to maintain consistency across all diagrams. All callout text must use Instrument Serif in italic style with the color token #2d3142.

Key constraints include:

• Maximum count: Two callouts per diagram maximum
• Typography: Instrument Serif italic only, 14px size
• Leader style: Dashed line with stroke-dasharray="4,3" and 40% opacity (rgba(45,49,66,0.40))
• Landing dot: 2px radius circle in #2d3142 (optional but recommended)

These rules ensure that annotation callouts remain visually subordinate to primary diagram elements while still readable in the margins.

Summary

• Diagram-design implements annotation callouts as a three-part SVG primitive defined in primitive-annotation.md
• Each callout requires Instrument Serif italic text, a dashed Bézier leader, and an optional landing dot
• The system limits diagrams to a maximum of two annotation callouts
• You can add callouts manually via SVG fragments or automatically using the SKILL CLI with ^{callout} markers
• Style guidelines in style-guide.md mandate specific colors, fonts, and dash patterns to distinguish callouts from primary arrows

Frequently Asked Questions

What font is required for annotation callouts in diagram-design?

The style-guide.md mandates Instrument Serif in italic style for all annotation callouts. The SVG text element must specify font-family="'Instrument Serif', serif" and font-style="italic" to comply with the design system requirements.

How many annotation callouts can I add to a single diagram?

The design system restricts each diagram to a maximum of two annotation callouts. This limit prevents margin clutter and maintains visual focus on the primary diagram content while allowing essential editorial asides.

Can I customize the dash pattern of the callout leader line?

No, the primitive-annotation.md specification requires a fixed dash pattern of stroke-dasharray="4,3" for the leader line. This standardized pattern visually distinguishes annotation leaders from primary diagram arrows and connectors.

Does diagram-design support callouts in PNG output?

Yes, when you run the SKILL pipeline with PNG output options, the SVG callout elements render as raster graphics in the final output. The diagram-design command processes the SVG primitives into the requested format while preserving the styling defined in style-guide.md.

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