# How to Add Annotation Callout Primitives to Diagrams: A Complete Guide to Editorial Annotations > Learn to add annotation callout primitives to diagrams with this comprehensive guide. Master editorial annotations using SVG elements for clearer visuals. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-09-12 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-annotation.md) and governed by the design system rules in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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 (``) 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 (``) filled with `#2d3142` that marks the anchor point on the diagram. ```svg no imports, no configuration ``` ## 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. ```json { "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: ```bash 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/example-nested.html) file in the repository assets demonstrates this integration with two properly positioned callouts. ```html no imports, no configuration ``` 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/primitive-annotation.md) and are governed by [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md) to ensure consistent margin placement across different diagram sizes.