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

> Explore Diagram-Design's primitive elements: Annotation Callout, Sketchy Filter, and Terminal Window. Enhance diagrams with unique visual meaning and style.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: getting-started
- Published: 2026-08-14

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```svg
<!-- 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```svg
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```html
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file lists the "Hand-drawn variant" pointing to [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md) | Full annotation callout specification including grammar, color values, and placement rules |
| [`primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-sketchy.md) | SVG filter definition, parameter tuning guide, and application constraints |
| [`primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md) | Complete HTML/CSS terminal template with typographic scaling |
| [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-terminal.md), there is no brand token inheritance to maintain consistent CLI aesthetics across all terminal-styled outputs.