# diagram-design Animation Modes: The Four Built-in Types Explained

> Explore the four animation modes in cathrynlavery/diagram-design: none, reveal, step, and loop. Understand how data-motion-mode controls SVG diagram animations.

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

---

**The cathrynlavery/diagram-design repository defines four distinct animation modes—`none`, `reveal`, `step`, and `loop`—that control how SVG diagrams behave through the `data-motion-mode` attribute, with specifications documented in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md).**

The diagram-design animation system prioritizes **static-first rendering** and accessibility compliance. Each mode serves a specific purpose, from generating print-ready static figures to providing interactive step-by-step walkthroughs, all while respecting user motion preferences and strict timing budgets.

## The Four Animation Modes Defined in [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)

The canonical list of animation modes appears in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) at lines 11–14. Only one mode may be assigned per diagram via the `data-motion-mode` attribute.

### `none` Mode (Static/Default)

The `none` mode renders a complete, stable figure with **no JavaScript execution**. This default state is ideal for printing, PDF exports, screenshots, or when users have enabled reduced-motion preferences. The diagram loads as pure HTML/SVG without controller scripts, ensuring maximum compatibility and performance for static documentation.

### `reveal` Mode (Single Autoplay)

The `reveal` mode triggers a **single deterministic autoplay sequence** that concludes with the full diagram visible. For animations lasting ≤ 5 seconds, the implementation uses pure CSS; longer sequences utilize the scoped controller found in [`template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-motion.html). The animation never restarts automatically, making it suitable for brief ordered explanations where motion adds clarity but looping would distract.

### `step` Mode (Interactive Navigation)

The `step` mode presents the diagram as a series of **paused semantic states** controlled by the user. Minimal inline JavaScript—binding to `data-motion-controls`—provides Play, Pause, Replay, Previous, and Next functionality. This mode targets teaching scenarios, policy trace comparisons, and step-by-step walkthroughs where the viewer dictates the pacing.

### `loop` Mode (Decorative Repetition)

The `loop` mode displays a **decorative token that repeats** without altering the diagram’s semantic meaning. Running for ≥ 3 seconds and implemented via CSS keyframes by default, this mode provides quiet visual hints or aesthetic flows where repetition adds value without conveying new information. Only `loop` repeats; `reveal` and `step` conclude at their final states.

## How to Configure Animation Modes in Your Diagrams

Apply the `data-motion-mode` attribute to your SVG or container element. The following examples demonstrate the HTML structure required for each mode, following the canonical controller pattern from [`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html).

Static rendering with no motion:

```html
<svg data-motion-mode="none" ...>
  …static diagram content…
</svg>

```

Single autoplay reveal sequence:

```html
<svg data-motion-mode="reveal" ...>
  …diagram with data-motion-item attributes…
</svg>

```

Interactive step-by-step navigation with control bindings:

```html
<div data-motion-mode="step" data-motion-root>
  <svg ...>
    …diagram with data-motion-item data-step="1" …>
  </svg>
  <div data-motion-controls>
    <button data-motion-action="play">▶︎</button>
    <button data-motion-action="pause">⏸</button>
    <button data-motion-action="prev">←</button>
    <button data-motion-action="next">→</button>
    <button data-motion-action="replay">⟲</button>
  </div>
</div>

```

Decorative looping animation:

```html
<svg data-motion-mode="loop" ...>
  …diagram with a decorative element that repeats via CSS keyframes…
</svg>

```

## Static-First Architecture and Constraints

The diagram-design animation system enforces several architectural rules to ensure reliability and accessibility. The **static-first contract** requires that the full semantic diagram exists in the HTML/SVG before any motion is applied; animations may only hide or transform elements under the `.motion-ready` class.

**Accessibility** is handled through `prefers-reduced-motion: reduce` media queries. When detected, diagrams automatically default to `none` mode, hiding all controls and announcing via a status region that playback is unavailable.

The **timing budget** is controlled through CSS custom properties: `--motion-fast`, `--motion-step`, `--motion-hold`, and `--motion-total` (capped at ≤ 8 seconds). The system prohibits random delays, spring physics, or indefinite loops. Additionally, **scoped state** ensures that control actions affect only the nearest `[data-motion-root]`, preventing ID collisions and timer interference between multiple diagrams on the same page.

## Validating Animation Implementations

The repository provides two scripts to enforce compliance with the animation contract. **[`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py)** checks that a diagram’s animation adheres to mode specifications and the timing budget constraints. **[`scripts/lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/lint-skin.py)** validates the diagram’s skin for required motion attributes and accessibility rules, ensuring that `data-motion-item` and `data-step` attributes are correctly implemented before deployment.

## Summary

- **Four modes available**: `none`, `reveal`, `step`, and `loop`, documented in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) lines 11–14.
- **Default behavior**: `none` mode requires zero JavaScript and respects reduced-motion preferences automatically.
- **Implementation**: Use `data-motion-mode` attributes and the canonical controller from [`template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-motion.html) for interactive modes.
- **Timing limits**: Total animation duration must not exceed 8 seconds; `loop` modes must run at least 3 seconds.
- **Validation**: Use [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) and [`lint-skin.py`](https://github.com/cathrynlavery/diagram-design/blob/main/lint-skin.py) to check compliance before publishing diagrams.

## Frequently Asked Questions

### Can I combine multiple animation modes in a single diagram?

No, the diagram-design system allows only one `data-motion-mode` value per diagram. Each mode represents a mutually exclusive behavioral contract—`none` for static output, `reveal` for single-play sequences, `step` for interactive navigation, or `loop` for decorative repetition. Attempting to mix modes would violate the static-first architecture defined in [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md).

### How does diagram-design handle accessibility for users sensitive to motion?

The system automatically detects `prefers-reduced-motion: reduce` and serve the static frame equivalent to `none` mode. All motion controls are hidden, and a live region announces that playback is unavailable. This ensures that users with vestibular disorders or motion sensitivity receive a fully functional, non-animated diagram without requiring manual configuration.

### What is the maximum allowed duration for diagram animations?

The timing budget enforces a hard limit of **8 seconds** total duration via the `--motion-total` CSS custom property. Additionally, `loop` modes must run for at least 3 seconds to prevent distracting rapid flicker, while `reveal` modes switch from CSS-only to scoped JavaScript controllers when exceeding 5 seconds. The [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) script validates these constraints automatically.

### Where can I find the reference implementation for animation controllers?

The canonical HTML and JavaScript controller resides in **[`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html)**. Copying this file verbatim guarantees compliance with the animation contract for `step` and `reveal` modes, including proper scoping of `data-motion-root`, binding of `data-motion-action` controls, and adherence to the static-first loading sequence.