# Diagram-Design Animation Modes: A Complete Guide to `none`, `reveal`, `step`, and `loop`

> Explore diagram-design animation modes: none, reveal, step, and loop. Master static, autoplay, interactive, and decorative animations for your diagrams. Learn more!

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

---

**Diagram-Design supports four mutually exclusive animation modes controlled by the `data-motion-mode` attribute: `none` for static diagrams, `reveal` for single autoplay sequences, `step` for interactive user-controlled playback, and `loop` for decorative repeating tokens.**

The diagram-design system provides an optional animation layer that attaches to any diagram without changing its static meaning. According to the `cathrynlavery/diagram-design` source code, these four modes are 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 a canonical controller in [`template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-motion.html). Every animated diagram must import this template unchanged, with behavior verified by the [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) test suite.

## The Four Animation Modes in Diagram-Design

The animation system offers **one strictly static mode** and **three animated variants**, all selected via `data-motion-mode` on the diagram's root element.

### `none`: Static Diagram Mode

**`none`** produces a complete static figure with no JavaScript execution. This mode serves as the default, print-friendly fallback, and respects `prefers-reduced-motion` accessibility preferences.

- No inline scripts or external controllers load
- Optimal for screenshots, PDF export, and reduced-motion users
- Defined at [line 11](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md#L11) of [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)

```html
<div data-motion-mode="none" data-motion-root>
  <!-- static diagram SVG/HTML here -->
</div>

```

### `reveal`: Single Autoplay Sequence

**`reveal`** triggers a deterministic autoplay run that ends on the complete frame. This mode never auto-replays and is ideal for short ordered explanations under five seconds.

- Uses CSS-only implementation for sequences ≤ 5 s
- Falls back to the scoped controller for longer sequences
- Perfect for progressive disclosure of diagram elements
- Defined at [line 12](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md#L12) of [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)

```html
<div data-motion-mode="reveal" data-motion-root>
  <!-- animated diagram SVG/HTML here -->
</div>

```

### `step`: Interactive User-Controlled Playback

**`step`** provides paused semantic states with explicit **Play, Pause, Replay, Previous, and Next** controls. This mode requires minimal inline JavaScript for the control interface.

- The canonical controller automatically injects playback controls
- Designed for teaching, policy-trace visualizations, and step-by-step comparisons
- Users maintain full control over pacing and sequence navigation
- Defined at [line 13](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md#L13) of [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)

```html
<div data-motion-mode="step" data-motion-root>
  <!-- animated diagram SVG/HTML here -->
</div>

```

### `loop`: Decorative Repeating Token

**`loop`** creates a decorative animation that repeats without changing the diagram's semantic meaning. This mode defaults to CSS-only implementation.

- Minimum 3-second cycle duration for accessibility
- Subtle flow hints that don't distract from content comprehension
- Ignores user interaction; plays continuously when visible
- Defined at [line 14](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md#L14) of [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)

```html
<div data-motion-mode="loop" data-motion-root>
  <!-- animated diagram SVG/HTML here -->
</div>

```

## Implementation Architecture

### Required Files for Animation

| File | Purpose | Location |
|------|---------|----------|
| [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) | Reference documentation defining mode contracts and accessibility requirements | [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) |
| [`template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-motion.html) | Canonical HTML template containing the scoped animation controller and CSS variables | [`skills/diagram-design/assets/template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html) |
| [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) | Validation script that enforces correct semantics and rejects non-canonical controllers | [`scripts/verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py) |

### Accessibility and Reduced Motion

The animation controller respects the `prefers-reduced-motion` media query, automatically falling back to the static frame when users have requested reduced motion (see lines 68-78 of [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md)). This ensures compliance with WCAG guidelines without requiring manual mode switching.

## Mode Selection Decision Guide

Choose your diagram-design animation mode based on these criteria:

- **Publishing static content?** → `none`
- **Brief progressive reveal (≤ 5 s, no replay)?** → `reveal`
- **Teaching or explaining with user pacing?** → `step`
- **Subtle ambient motion (≥ 3 s cycle)?** → `loop`

All four variants share identical static markup; only the `data-motion-mode` attribute value changes behavior.

## Summary

- **Four exclusive modes**: `none`, `reveal`, `step`, and `loop` cover all diagram animation needs in diagram-design
- **Single canonical controller**: All animations must use [`template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-motion.html) unchanged
- **Attribute-driven**: Set `data-motion-mode` on the root element to select behavior
- **Accessible by default**: `prefers-reduced-motion` automatically triggers static fallback
- **Verified integrity**: The [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py) test suite rejects any deviation from official contracts

## Frequently Asked Questions

### How do I disable all animations in a diagram-design project?

Set `data-motion-mode="none"` on your diagram's root element. This eliminates JavaScript execution entirely and serves as the automatic fallback when users have `prefers-reduced-motion` enabled in their system preferences.

### Can I combine multiple animation modes in one diagram?

No. The four diagram-design animation modes are **mutually exclusive** as defined in [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md). Attempting to combine modes causes validation failures in [`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py). Design separate diagrams if you need different animation behaviors for different contexts.

### What controls appear when using `step` mode?

The canonical controller in [`template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-motion.html) automatically injects five controls: **Play, Pause, Replay, Previous, and Next**. These require minimal inline JavaScript and provide full user control over semantic animation states without modifying your static markup.

### Does `loop` mode respect reduced motion preferences?

Yes, but with a caveat. While the `loop` mode itself runs continuously, the overall diagram-design system detects `prefers-reduced-motion` at the controller level and falls back to `none` behavior for all modes including `loop`. This enforcement appears in lines 68-78 of the [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) specification.