# Motion Primitives in Diagram-Design: Complete Guide to Available Types and Budget Limits

> Explore eight semantic motion primitives in Diagram-Design with budget limits to ensure visual clarity and prevent animation overuse. Discover available types and their caps.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-06

---

**Diagram-Design provides eight semantic motion primitives with strict budget caps that enforce visual clarity and prevent animation overuse.**

When you enable optional animation in `cathrynlavery/diagram-design`, you work with a curated set of **motion primitives** — each with hard limits on count, duration, or complexity. These budgets ensure animated diagrams remain readable and comply with the repository's **static-first contract**, where every diagram must be fully understandable without animation.

## What Are Motion Primitives in Diagram-Design?

Motion primitives are declarative, semantic animation patterns defined in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md). They are not general-purpose CSS animations. Instead, they map to specific communicative intents: showing process flow, revealing evaluation steps, indicating state changes.

You activate primitives by setting `data-motion-mode` to one of three values:

- `reveal` — gradual disclosure of content
- `step` — discrete step-by-step progression
- `loop` — continuous, subtle ambient motion

The repository enforces budgets through [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py), which runs in CI to block any diagram exceeding its allocated limits.

## Complete List of Motion Primitives and Their Budgets

| Primitive | Visual Effect | Budget Limit |
|:---|:---|:---|
| **Path draw** | Decorative duplicate of connector path using `pathLength="1"` with animated dash offset; original labeled connector remains fully visible | ≤ 2 animated paths; only one active at a time |
| **Staggered reveal** (stage reveal) | Step-by-step opacity/translation reveal for ordered stages or pipelines | ≤ 8 steps, ≤ 12 items total |
| **Queue counter** | Stable queue slot with numeric count incrementing as items appear | ≤ 5 items; no re-ordering allowed |
| **Typing / field population** | Text appearance as typed string or table row population | ≤ 32 typed characters **or** ≤ 6 fields |
| **Policy evaluation** (rule evaluation) | Rule rows with status symbols, optional evaluation trace | 3–6 rules, ≤ 2 traces |
| **Flow token** | `aria-hidden` token on fixed path indicating flow (heartbeat-style loop) | Exactly **one** token; loop ≥ 3 seconds |
| **Containment** | Reveal container children, keep labeled boundary visible | Exactly **one** boundary transition |
| **Audit append** | Chronological row addition (audit log style) | ≤ 5 appended rows |

Source: [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) lines 35–46

## How Budget Enforcement Works

Budgets are not suggestions. The [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) script validates every animated diagram against its declared primitives. Exceeding any limit causes CI failure.

The enforcement mechanism appears in [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) lines 103–108:

> "The verifier walks the DOM tree, counts instances of each primitive, and rejects any diagram where a primitive exceeds its budget or where multiple primitives of incompatible types are combined."

Adversarial tests in [`scripts/test-verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/test-verify-motion.py) ensure the verifier correctly catches edge cases — hidden elements that still trigger motion counts, nested containers with duplicate boundaries, or timing violations on flow token loops.

### Key Budget Rules by Primitive

**Path draw** — Budget: ≤ 2 paths, one active

Only one path may animate at any moment. The second path serves as a reserved slot for alternative routing or comparison. This prevents the "spaghetti" effect of multiple simultaneous connector animations.

**Staggered reveal** — Budget: ≤ 8 steps, ≤ 12 items

`data-step` attributes from 1 to 8 control sequencing. You can distribute up to 12 items across these steps. Steps without assigned items simply proceed faster.

**Queue counter** — Budget: ≤ 5 items, stable order

The queue slot itself is a persistent DOM element; only the numeric counter and item count change. No animation of element re-ordering is permitted, maintaining motion predictability.

**Typing / field population** — Budget: 32 chars OR 6 fields

This is an **exclusive OR**. You cannot combine typing and field population in the same diagram section. Choose based on whether your data is prose (typewriter effect) or structured input.

**Policy evaluation** — Budget: 3–6 rules, ≤ 2 traces

Minimum 3 rules ensures the evaluation pattern is recognizable; maximum 6 prevents overwhelming detail. Traces show which rules contributed to a final decision.

**Flow token** — Budget: exactly 1, ≥ 3s loop

The strictest primitive. Single token, predictable timing. The 3-second minimum prevents anxiety-inducing rapid motion.

**Containment** — Budget: exactly 1 transition

One boundary reveal per diagram. After reveal, the container boundary remains visible as a persistent structural element.

**Audit append** — Budget: ≤ 5 rows

Appended rows appear one at a time. The 5-row cap keeps audit trails scannable without excessive scroll.

## Implementation Examples

### Staggered Reveal: Three-Stage Pipeline

```html
<div data-motion-mode="step" data-motion-root>
  <div data-motion-item data-step="1">Ingest</div>
  <div data-motion-item data-step="2">Transform</div>
  <div data-motion-item data-step="3">Export</div>
</div>

```

This uses 3 of 8 available steps and 3 of 12 available items.

### Queue Counter: Up to Five Items

```html
<div data-motion-mode="reveal">
  <svg><!-- connector graphics --></svg>
  <div class="queue">
    <span class="counter" data-queue-count>0</span>
    <span class="queue-label">pending jobs</span>
  </div>
</div>

```

The counter increments via JavaScript; the motion primitive validates that no more than 5 items are ever represented.

### Policy Evaluation with Traces

```html
<div data-motion-mode="step">
  <table class="policy-table">
    <tr data-motion-item data-step="1">
      <td>Authentication</td>
      <td class="status pass">✓</td>
    </tr>
    <tr data-motion-item data-step="2">
      <td>Rate limit check</td>
      <td class="status pass">✓</td>
    </tr>
    <tr data-motion-item data-step="3">
      <td>Content filter</td>
      <td class="status fail">✗</td>
    </tr>
    <!-- 3 rules, 0 traces shown -->
  </table>
  <div class="trace" data-trace-step="2">Rate limit: 847/1000</div>
</div>

```

Two traces maximum; this example uses one.

### Flow Token: Single Looping Indicator

```html
<svg data-motion-mode="loop">
  <path id="heartbeat-path" d="M10,50 Q30,10 50,50 T90,50" />
  <circle data-flow-token r="3">
    <!-- motion constrained to path, loop ≥ 3s -->
  </circle>
</svg>

```

Only one `data-flow-token` permitted per diagram.

## Required Controller and Verification Files

Every animated diagram must include the canonical controller from [`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html). This script interprets `data-motion-*` attributes and enforces timing contracts.

| File | Purpose |
|:---|:---|
| [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) | Complete specification of primitives, modes, budgets, and contracts |
| [`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html) | Required controller for all animated diagrams |
| [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) | CI verification of budget compliance |
| [`scripts/test-verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/test-verify-motion.py) | Adversarial tests for verifier correctness |

## Summary

- **Eight motion primitives** in Diagram-Design: path draw, staggered reveal, queue counter, typing/field population, policy evaluation, flow token, containment, and audit append

- **Hard budget caps** on every primitive prevent animation overuse and preserve diagram clarity

- **Three activation modes**: `reveal`, `step`, and `loop` — chosen via `data-motion-mode`

- **Automated enforcement** via [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) guarantees compliance before deployment

- **Static-first requirement**: every diagram must communicate fully without any motion enabled

## Frequently Asked Questions

### What happens if my diagram exceeds a motion primitive budget?

CI fails. The [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) validator runs on every commit and rejects any diagram where primitive instance counts exceed their defined limits. You must refactor — simplify the animation, split into multiple diagrams, or remove motion entirely.

### Can I combine multiple motion primitives in one diagram?

Yes, with restrictions. Primitives of compatible types (typically all `step`-mode or all `reveal`-mode) may coexist. Incompatible combinations — such as `loop` flow tokens with `step` staggers — are rejected by the verifier. Consult [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) lines 103–108 for the full compatibility matrix.

### Why are flow tokens and containment limited to exactly one instance?

These primitives create persistent structural changes to the diagram's perceived organization. Multiple flow tokens create competing attention centers; multiple containment reveals destroy the hierarchical clarity that makes containment meaningful. The "exactly one" rule preserves communicative intent.

### How do I test my animated diagram locally before committing?

Run [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) against your HTML file. For thorough validation, execute [`scripts/test-verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/test-verify-motion.py) — it includes adversarial cases that confirm the verifier catches subtle violations like hidden-but-counted elements or timing violations in flow token loops.