How to Enable Animation and Motion in Diagram‑Design: A Complete Implementation Guide

Diagram‑Design provides an optional presentation layer that adds motion to diagrams through a declarative attribute system and a canonical template that must be copied verbatim to ensure verification compliance.

To enable animation and motion in diagram‑design, you work with an isolated animation system that preserves static meaning while adding progressive enhancement. The repository cathrynlavery/diagram-design treats motion as a strictly opt‑in feature controlled through HTML data attributes, a specific inline JavaScript controller, and four supported motion modes defined in the reference documentation.

Understanding the Animation Architecture

The animation system in diagram‑design is deliberately isolated from static diagram rendering. According to the source code in skills/diagram-design/references/animation.md, all animation contracts are enumerated in a single reference file that defines four supported modes: none (default), reveal, step, and loop. This architecture ensures that animated diagrams remain accessible, respect motion budgets, and provide deterministic static fallbacks.

The skill wiring documented in skills/diagram-design/SKILL.md (lines 79‑100) routes the animation reference only when a diagram is created with motion. This means [references/animation.md] loads on demand, keeping the default workflow lightweight while allowing complex motion when required.

Key implementation files include:

• skills/diagram-design/references/animation.md – Defines motion modes, budget limits, CSS/JS requirements, and the static‑first contract.
• skills/diagram-design/assets/template-motion.html – The canonical HTML template containing the CSS and inline JavaScript controller that must be copied verbatim; any modification causes verification failure.
• skills/diagram-design/assets/example-policy-trace-animated.html – A complete working example demonstrating step‑by‑step policy traces with full accessibility markup.

Supported Motion Modes

Before implementation, select the appropriate motion mode for your use case:

1. none – Default static rendering with no animation.
2. step – Progressive disclosure where elements appear sequentially based on step attributes, supporting interactive playback controls.
3. reveal – Single deterministic autoplay that runs once on load and stops on the final frame; does not support replay.
4. loop – Continuous cycling through steps (use sparingly to respect motion budgets).

All modes respect the user's prefers-reduced-motion setting and fall back to the complete static frame when this preference is detected.

Step‑by‑Step Implementation

To enable animation and motion in diagram‑design, follow this attribute‑driven workflow:

Choose Your Motion Mode

Set the data-motion-mode attribute on the root element. For progressive disclosure, use step:

<main data-motion-root
      data-motion-mode="step"
      data-step-count="5"
      data-step-current="0">

For automatic playback without controls, use reveal:

<main data-motion-root
      data-motion-mode="reveal"
      data-step-count="3"
      data-step-current="3">

Configure the Root Element

The container requires several data attributes to establish the animation context:

• data-motion-root – Identifies the animation boundary.
• data-motion-mode – Sets the animation type (step, reveal, loop, or none).
• data-step-count – Total number of steps in the sequence.
• data-step-current – Initial step to display (0‑indexed).
• data-frame="static" – Enables static fallback handling.
• data-static-frame="complete" – Specifies which frame to render when motion is disabled.

Mark Animated Primitives

Each SVG element that should appear during a specific step requires two attributes:

• data-motion-item – Flags the element for animation control.
• data-step – Integer indicating when this element appears (1‑indexed).

<g data-motion-item data-step="1" aria-label="Step 1: Request received">
  <rect x="48" y="128" width="200" height="104" rx="8" fill="#f5f5f5"/>
  <text x="148" y="172" text-anchor="middle">Request</text>
</g>

<g data-motion-item data-step="2" aria-label="Step 2: Policy passed">
  <rect x="356" y="128" width="200" height="104" rx="8" fill="rgba(235,108,54,0.08)"/>
  <text x="456" y="168" text-anchor="middle">Policy</text>
</g>

Add Playback Controls (Optional)

For step and loop modes, include the control container:

<div data-motion-controls role="group" aria-label="Diagram playback controls">
  <button type="button" data-motion-action="prev">Previous</button>
  <button type="button" data-motion-action="play" aria-pressed="false">Play</button>
  <button type="button" data-motion-action="pause" aria-pressed="true">Pause</button>
  <button type="button" data-motion-action="next">Next</button>
  <button type="button" data-motion-action="replay">Replay</button>
</div>

<span data-motion-status role="status" aria-live="polite" aria-atomic="true"></span>
<noscript>
  <p>Animation controls require JavaScript. The complete diagram is shown above.</p>
</noscript>

Working with the Canonical Template

The most critical requirement for enabling animation is using the controller from skills/diagram-design/assets/template-motion.html. The inline script must be copied verbatim into your HTML file:

<!-- Inline controller – copy verbatim from template-motion.html -->
<script data-diagram-controls>
  /* Controller script handling prefers-reduced-motion, URL parameters,
     and deterministic timing guarantees. Do not modify. */
</script>

The controller reads URL parameters (?motion=static, ?motion=step, ?motion=reveal) to allow external systems to override the default behavior. It also manages the prefers-reduced-motion media query, automatically switching to data-static-frame="complete" when users have requested reduced motion.

Complete Working Example

Here is a minimal implementation showing a step‑by‑step request evaluation diagram:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Request Evaluation</title>
  <link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
  <style>
    /* Copy the complete <style> block from template-motion.html */
  </style>
</head>
<body>
  <main data-motion-root
        data-motion-mode="step"
        data-step-count="5"
        data-step-current="0"
        data-frame="static"
        data-static-frame="complete">
    
    <svg viewBox="0 0 960 480" role="img" aria-labelledby="title desc">
      <title id="title">Request Evaluation Process</title>
      <desc id="desc">A request passes through policy verification and queuing.</desc>
      
      <g data-motion-item data-step="1">
        <rect x="48" y="128" width="200" height="104" rx="8" fill="#f5f5f5" stroke="#2d3142"/>
        <text x="148" y="172" text-anchor="middle" font-family="Geist" font-size="16">Request</text>
      </g>
      
      <g data-motion-item data-step="2">
        <rect x="356" y="128" width="200" height="104" rx="8" fill="rgba(235,108,54,0.08)" stroke="#eb6c36"/>
        <text x="456" y="168" text-anchor="middle" font-family="Geist" font-size="16">Policy</text>
      </g>
    </svg>

    <div data-motion-controls role="group" aria-label="Diagram playback controls">
      <button type="button" data-motion-action="prev">Previous</button>
      <button type="button" data-motion-action="play">Play</button>
      <button type="button" data-motion-action="next">Next</button>
    </div>
  </main>

  <script data-diagram-controls>
    /* Verbatim controller from template-motion.html */
  </script>
</body>
</html>

Runtime Behavior and URL Overrides

As implemented in skills/diagram-design/assets/example-policy-trace-animated.html (lines 81‑84), the runtime system respects several URL parameters:

• ?motion=static – Forces static rendering regardless of mode attributes.
• ?motion=step – Activates step mode for debugging or bookmarking.
• ?motion=reveal – Triggers single autoplay suitable for presentations.

The system queries window.matchMedia('(prefers-reduced-motion: reduce)') before initializing any transitions. When this preference is active, the controller ignores data-motion-mode and immediately renders the frame specified in data-static-frame, ensuring compliance with accessibility standards.

Summary

To enable animation and motion in diagram‑design:

• Select a motion mode (step, reveal, or loop) and set data-motion-mode on the root <main> element.
• Copy the canonical controller verbatim from skills/diagram-design/assets/template-motion.html to ensure verification compliance.
• Annotate SVG elements with data-motion-item and data-step attributes to define animation sequences.
• Respect accessibility by including aria-label attributes, providing noscript fallbacks, and honoring prefers-reduced-motion.
• Reference the skill documentation in skills/diagram-design/references/animation.md for motion budget limits and deterministic timing requirements.

Frequently Asked Questions

What happens if I modify the JavaScript controller from template-motion.html?

Modifying the inline script causes the diagram-design verifier to reject the diagram. The controller contains cryptographic checksums or strict validation logic that ensures deterministic behavior across all animated diagrams. Always copy the script verbatim from skills/diagram-design/assets/template-motion.html.

How do I support users who prefer reduced motion?

The animation system automatically detects prefers-reduced-motion: reduce and falls back to the static frame specified in data-static-frame. You do not need to write additional JavaScript; simply ensure your markup includes data-frame="static" and data-static-frame="complete" (or the appropriate frame identifier) on the root element.

Can I use autoplay animations in diagram-design?

Only the reveal mode supports autoplay, and it runs exactly once as a single deterministic autoplay before stopping on the final frame. Continuous autoplay loops violate the motion budget constraints defined in skills/diagram-design/references/animation.md. If you need looping content, use data-motion-mode="loop" with explicit user controls.

Where is the animation reference documentation loaded in the skill system?

According to skills/diagram-design/SKILL.md (line 79), the system loads [references/animation.md] on demand only when a diagram is created with motion enabled. This lazy-loading architecture keeps standard diagram generation lightweight while providing comprehensive motion documentation when needed.

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