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

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. 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, 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 lines 35–46

How Budget Enforcement Works

Budgets are not suggestions. The 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 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 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

<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

<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

<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

<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. This script interprets data-motion-* attributes and enforces timing contracts.

File	Purpose
skills/diagram-design/references/animation.md	Complete specification of primitives, modes, budgets, and contracts
skills/diagram-design/assets/template-motion.html	Required controller for all animated diagrams
scripts/verify-motion.py	CI verification of budget compliance
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 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 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 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 against your HTML file. For thorough validation, execute 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.

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