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

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 and enforced by a canonical controller in template-motion.html. Every animated diagram must import this template unchanged, with behavior verified by the 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 of animation.md

<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 of animation.md

<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 of animation.md

<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 of animation.md

<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	Reference documentation defining mode contracts and accessibility requirements	skills/diagram-design/references/animation.md
template-motion.html	Canonical HTML template containing the scoped animation controller and CSS variables	skills/diagram-design/assets/template-motion.html
verify-motion.py	Validation script that enforces correct semantics and rejects non-canonical controllers	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). 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 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 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. Attempting to combine modes causes validation failures in 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 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 specification.

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