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

> Learn to enable animation and motion in Diagram-Design using its optional presentation layer. This guide provides a complete implementation walkthrough for adding dynamic visuals to your diagrams.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`:

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

```

For automatic playback without controls, use `reveal`:

```html
<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).

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

```html
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/template-motion.html). The inline script **must be copied verbatim** into your HTML file:

```html
<!-- 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:

```html
<!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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.