Diagram Design Animation Modes: The Complete Guide to None, Reveal, Step, and Loop

Diagram Design supports four distinct animation modes—none, reveal, step, and loop—that control how diagrams render from completely static prints to interactive step-wise presentations.

The cathrynlavery/diagram-design repository defines a strict, accessibility-first animation system for technical diagrams. These animation modes are declared via the data-motion-mode attribute on the root diagram element, with each mode enforcing specific constraints around performance, user control, and the static-first enhancement contract.

The Four Animation Modes

Diagram Design constrains motion to four well-defined behaviors documented in skills/diagram-design/references/animation.md. Only one mode may be active per figure, and the system defaults to static rendering unless motion is explicitly requested.

None (Static Mode)

The none mode renders diagrams as completely static images with no JavaScript execution, CSS animations, or playback controls. This is the default behavior for all diagrams and serves as the foundation for the static-first contract.

Use this mode for print exports, screenshots, reduced-motion accessibility fallbacks, and any context where JavaScript is unavailable. The implementation requires no additional assets—only the raw SVG or HTML markup.

Reveal (Autoplay Once)

The reveal mode executes a single, deterministic autoplay sequence that runs once on page load and stops on the final frame. Short animations (≤ 5 seconds) use CSS-only transitions, while longer sequences inject the scoped controller from skills/diagram-design/assets/template-motion.html.

This mode suits brief explanatory sequences such as policy evaluation steps or process overviews where the author controls the narrative timing but the viewer watches passively.

Step (Interactive Playback)

The step mode provides paused, user-controlled playback through Previous, Next, Play, Pause, and Replay controls. Minimal inline JavaScript binds these controls to the current step index, allowing audiences to navigate complex diagrams at their own pace.

This is the canonical choice for teaching materials, policy trace diagrams, and comparative analyses where viewers must control the information flow. The standard controller script handles all state management and keyboard accessibility.

Loop (Continuous Decoration)

The loop mode drives decorative elements that cycle continuously without altering the diagram's semantic meaning. implemented with CSS-only animations running ≥ 3 seconds per cycle, this mode adds subtle flow hints—such as pulsing arrows or moving tokens—while maintaining full readability of the static frame.

This mode cannot carry critical information; it exists only to guide the eye through complex layouts.

Technical Implementation

Each animation mode requires specific markup patterns and respects strict motion budgets: ≤ 8 steps, ≤ 12 animated items, and total duration ≤ 8 seconds. The diagram must render completely in its final static state before any enhancement scripts execute.

The canonical controller lives in template-motion.html and must be used verbatim. Any deviation causes the verification suite to fail, ensuring consistent behavior across all diagrams in the repository.

Code Examples

Static diagram with no motion:

<div class="diagram" data-motion-mode="none">
  <!-- SVG markup here -->
</div>

Reveal animation that plays once on load:

<div class="diagram" data-motion-mode="reveal">
  <!-- SVG markup here -->
</div>

Step-wise animation with playback controls:

<div class="diagram" data-motion-mode="step">
  <!-- SVG markup here -->
</div>
<!-- Controller injects the following controls automatically -->
<button data-motion-action="play">Play</button>
<button data-motion-action="pause">Pause</button>
<button data-motion-action="prev">Previous</button>
<button data-motion-action="next">Next</button>
<button data-motion-action="replay">Replay</button>

Continuous decorative loop:

<div class="diagram" data-motion-mode="loop">
  <!-- SVG markup with CSS-animated decorative token -->
</div>

Validation and Verification

The scripts/verify-motion.py script enforces mode compliance across the codebase. This validator checks that diagrams satisfy the static-first contract, respect motion budget limits, and use only the approved controller implementations. The companion test suite in scripts/test-verify-motion.py exercises the verifier against both valid diagrams and adversarial examples to prevent regression.

Summary

• Four animation modes control Diagram Design behavior: none (static), reveal (autoplay once), step (interactive controls), and loop (continuous decoration).
• Static-first contract requires every diagram to render completely before JavaScript enhancement.
• Motion budgets limit complexity to 8 steps, 12 items, and 8 seconds total duration.
• Canonical controller in template-motion.html must be used verbatim for step and reveal modes.
• Verification suite in verify-motion.py ensures compliance across the repository.

Frequently Asked Questions

How do I choose between reveal and step animation modes?

Use reveal when you want the diagram to tell a linear story automatically—ideal for short process explanations where the viewer should watch passively. Use step when the audience needs to pause, review, or navigate non-linearly through complex policy traces or comparisons.

What happens if I exceed the motion budget limits?

The verify-motion.py script will reject diagrams exceeding the 8-step, 12-item, or 8-second limits. These constraints ensure accessibility compliance and prevent cognitive overload or performance degradation on low-end devices.

Can I combine multiple animation modes in one diagram?

No. The data-motion-mode attribute accepts only one value per figure, and the system enforces mutual exclusivity. For complex presentations requiring both autoplay and manual control, create separate diagram instances or use the step mode with auto-advance configurations.

How does the static-first contract affect accessibility?

The contract guarantees that diagrams are fully meaningful without JavaScript, satisfying WCAG requirements for progressive enhancement. Users with reduced-motion preferences or screen readers receive the complete static diagram immediately, while motion enhancements layer on only when explicitly requested and supported.

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