Motion Modes for Diagrams in Diagram Design: The Complete Technical Guide

Diagram Design supports four distinct motion modes—none, reveal, step, and loop—that control animation behavior through the data-motion-mode attribute, validated by the scripts/verify-motion.py linter.

The Diagram Design repository provides a declarative framework for adding animation to SVG-based diagrams using HTML data attributes. Understanding the available motion modes for diagrams ensures your implementations pass validation and meet accessibility standards defined in the project's animation reference.

Available Motion Modes for Diagrams

The motion system is defined in skills/diagram-design/references/animation.md and enforced by the validator in scripts/verify-motion.py. The MODES constant (referenced in line 279 error messages) defines the permitted values for the data-motion-mode attribute.

None (Static Mode)

The none mode renders diagrams as completely static images. No JavaScript is injected, making this ideal for print compatibility and reduced-motion preferences.

Reveal (Autoplay Once)

The reveal mode triggers a single-play animation immediately on page load. This mode reveals the entire diagram sequence once without user interaction.

Step (Progressive Disclosure)

The step mode enables staggered, step-by-step animations using the data-motion-item attribute with integer data-step values. This creates presentations where elements appear in a defined sequence.

Loop (Continuous Animation)

The loop mode creates repeating animations suitable for carousels, rotating diagrams, or ambient motion effects that cycle indefinitely.

Validation in verify-motion.py

The motion validator located at scripts/verify-motion.py enforces strict compliance with the allowed modes. When validation fails, the script raises an error indicating that data-motion-mode must be one of the sorted MODES set. This ensures only the four documented modes are deployed in production diagrams.

Implementation Examples

The controller logic in assets/template-motion.html interprets these modes and applies the appropriate animation classes.

Static diagram without motion:

<div data-motion-root data-motion-mode="none">
  <svg><!-- diagram markup --></svg>
</div>

Reveal on page load:

<div data-motion-root data-motion-mode="reveal">
  <svg><!-- diagram markup --></svg>
</div>

Step-by-step sequence:

<div data-motion-root data-motion-mode="step">
  <g data-motion-item data-step="1">First element</g>
  <g data-motion-item data-step="2">Second element</g>
  <g data-motion-item data-step="3">Third element</g>
</div>

Continuous loop:

<div data-motion-root data-motion-mode="loop">
  <svg><!-- rotating carousel markup --></svg>
</div>

Summary

• Diagram Design implements four motion modes (none, reveal, step, loop) controlled via the data-motion-mode attribute.
• The scripts/verify-motion.py linter validates all mode values against the internal MODES constant.
• Static rendering uses none mode for print-safe output without JavaScript.
• Step mode requires data-motion-item and data-step attributes for sequencing.
• Implementation details are documented in skills/diagram-design/references/animation.md and executed via assets/template-motion.html.

Frequently Asked Questions

What are the valid values for data-motion-mode in Diagram Design?

The attribute accepts exactly four values: none, reveal, step, and loop. These are defined in the animation reference documentation and enforced by the validator in scripts/verify-motion.py.

How does the step mode handle animation sequencing?

Step mode uses child elements with data-motion-item attributes paired with integer data-step values. The controller triggers these items sequentially according to their step order, creating progressive disclosure effects.

Which file validates motion mode attributes?

The scripts/verify-motion.py script performs validation, checking that data-motion-mode values exist within the permitted MODES set. Invalid values trigger a validation error referencing the allowed modes list.

How do I disable motion entirely for print compatibility?

Set data-motion-mode="none" on the root element. This prevents JavaScript injection and renders the diagram as a static image, ensuring compatibility with print media and respecting reduced-motion preferences.

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