How to Add Annotation Callout Primitives to Diagrams: A Complete Guide to Editorial Annotations

Annotation callout primitives in Diagram Design consist of three SVG elements—italic Instrument Serif text, a dashed Bézier leader, and a landing dot—that must be placed in diagram margins with a strict limit of two per diagram.

The cathrynlavery/diagram-design repository treats annotation callouts as a distinct primitive type that provides editorial asides without disrupting the primary diagram grammar. These callouts are defined in skills/diagram-design/references/primitive-annotation.md and governed by the design system rules in SKILL.md, ensuring consistent visual hierarchy across all generated diagrams.

Understanding the Annotation Callout Primitive Grammar

The annotation callout primitive decomposes into exactly three SVG components according to the reference specification.

The text element uses italic Instrument Serif at 14px with the color #2d3142. This font style is reserved exclusively for callouts under the design system rules.

The leader is a quadratic Bézier curve (<path>) with stroke-dasharray="4,3" to differentiate it from solid diagram arrows. It uses a semi-transparent stroke (rgba(45,49,66,0.40)) at 1px width.

The landing dot is a 2px radius circle (<circle>) filled with #2d3142 that marks the anchor point on the diagram.

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

Implementing Callouts via Draw.io JSON

When working with Draw.io source files, you define callouts using a specific JSON structure that the import engine translates into the SVG primitive.

The JSON requires a type field set to "callout", a text string, a position field (commonly top-right or bottom-left), and an optional color palette selector.

{
  "type": "callout",
  "text": "no imports, no configuration",
  "position": "top-right",
  "color": "neutral"
}

The import-drawio script processes this JSON and injects the corresponding SVG coordinates based on the position field. The color field maps to the palette definitions in the primitive reference (neutral, focal, or tertiary).

Adding Callouts Using the CLI

The command-line interface provides a direct method for injecting annotation callout primitives during the import process.

Use the --callout flag with the import-drawio command followed by your annotation text and the --position specifier:

diagram-design import-drawio diagram.drawio \
  --callout "no imports, no configuration" \
  --position top-right

To add a second callout, execute the command again with a different position such as bottom-left. The CLI automatically generates the correct SVG coordinates and styling according to primitive-annotation.md.

Design System Constraints and Validation

The Diagram Design system enforces strict constraints on annotation callout primitives to maintain visual clarity.

Placement rules mandate that callouts must sit in the margins—typically top-right or bottom-left—and never intrude into the active diagram area where they could confuse the primary grammar.

Quantity limits restrict each diagram to a maximum of two callouts. Exceeding this threshold causes the validator to reject the build, as additional callouts shift the tone from editorial signal to commentary.

Font reservation according to SKILL.md section 5 exclusively reserves italic Instrument Serif for annotation callouts; other diagram elements must not use this combination.

The scripts/verify-drawio-import.py validator checks these constraints during the build process, raising errors if:

• More than two callouts are detected
• Callout positioning overlaps the active diagram bounds
• Non-italic Instrument Serif fonts are used for annotations

Complete HTML Integration Example

When the build process completes, the annotation callout primitives render as inline SVG within the final HTML output. The example-nested.html file in the repository assets demonstrates this integration with two properly positioned callouts.

<!-- Annotation top-right -->
<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>
<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"/>
<circle cx="520" cy="216" r="2" fill="#2d3142"/>

<!-- Annotation bottom-left (coordinates adjusted) -->

This structure ensures that editorial notes remain visually distinct from the diagram's functional elements while maintaining the system's typographic hierarchy.

Summary

• Annotation callout primitives require three SVG elements: italic Instrument Serif text, a dashed Bézier leader (stroke-dasharray="4,3"), and a landing dot.
• Source definitions live in skills/diagram-design/references/primitive-annotation.md and are governed by SKILL.md design system rules.
• Implementation supports both JSON configuration for Draw.io files and CLI flags (--callout) for direct injection.
• Strict constraints limit diagrams to two margin-based callouts using exclusively italic Instrument Serif at #2d3142.
• The validator at scripts/verify-drawio-import.py enforces quantity, placement, and typography rules during the build process.

Frequently Asked Questions

What is the maximum number of annotation callout primitives allowed per diagram?

The design system permits a maximum of two annotation callout primitives per diagram. This limit is enforced by verify-drawio-import.py, which rejects builds containing additional callouts to prevent editorial commentary from overwhelming the visual grammar.

Can I place an annotation callout inside the main diagram area?

No, annotation callout primitives must be placed exclusively in the margins, commonly top-right or bottom-left. The primitive-annotation.md specification explicitly prohibits placing callouts inside the active diagram area to avoid confusion with functional diagram elements.

Why must annotation callouts use Instrument Serif italic?

According to SKILL.md section 5, the design system reserves italic Instrument Serif exclusively for annotation callout primitives. This typographic reservation creates immediate visual distinction between editorial asides and primary diagram content, ensuring users recognize callouts as supplementary rather than structural information.

How does the CLI handle callout positioning coordinates?

The import-drawio command translates the --position flag (e.g., top-right, bottom-left) into specific SVG x and y coordinates based on the canvas dimensions. The script references the coordinate mapping defined in primitive-annotation.md to ensure consistent margin placement across different diagram sizes.

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