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

> Explore four motion modes none reveal step and loop in Diagram Design to control animation behavior using the data motion mode attribute. Learn how to animate your diagrams effectively.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) and enforced by the validator in [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template-motion.html) interprets these modes and applies the appropriate animation classes.

Static diagram without motion:

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

```

Reveal on page load:

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

```

Step-by-step sequence:

```html
<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:

```html
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) and executed via [`assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.