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

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.

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

The canonical list of animation modes appears in 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. 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.

Static rendering with no motion:

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

Single autoplay reveal sequence:

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

Interactive step-by-step navigation with control bindings:

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

<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 checks that a diagram’s animation adheres to mode specifications and the timing budget constraints. 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 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 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 and 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.

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 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. 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.

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