How to Use Optional Animation Modes in diagram-design: A Complete Guide

Use the --animation-mode flag (or -a short form) on the export-diagram command to control animation behavior, with supported modes including none, linear, ease-in, ease-out, and ease-in-out.

The diagram-design repository by cathrynlavery provides CLI and programmatic interfaces for exporting diagrams with optional animation modes. These modes control how diagram elements move during export, enabling everything from static renders to smooth motion graphics. This guide covers the available animation modes, their implementation, and practical usage examples based on the source code.

Supported Animation Modes in diagram-design

The diagram-design library implements five distinct animation modes. Each mode applies a different easing function to control element motion:

Mode	Description
none	No animation—exports a static image (default behavior)
linear	Elements move at constant speed from start to end positions
ease-in	Animation starts slowly and accelerates toward the end
ease-out	Animation starts quickly and decelerates toward the end
ease-in-out	Combines ease-in and ease-out for smooth start and finish

When omitted, the system defaults to none, producing static output. The mode selection directly influences how the rendering engine constructs frame sequences during export.

CLI Usage: The --animation-mode Flag

The export-diagram command exposes animation control through the --animation-mode flag. This is documented in commands/export-diagram.md and implemented in the CLI parser.

Basic Static Export (Default)

export-diagram my-diagram.mmd --output diagram.png

No animation flag required—the default none mode applies automatically.

Linear Animation with Custom Duration

export-diagram my-diagram.mmd -a linear --duration 5 --output diagram.gif

The -a short form accepts linear for constant-speed motion across a 5-second loop.

Ease-in-out with Frame Rate Control

export-diagram my-diagram.mmd --animation-mode ease-in-out \
    --frame-rate 30 --output animated-diagram.mp4

Full flag name --animation-mode used here with ease-in-out for professional smooth motion at 30fps.

Programmatic API Usage

For JavaScript/TypeScript projects, the exportDiagram function from @diagram-design/core accepts an animationMode parameter:

import { exportDiagram } from '@diagram-design/core';

await exportDiagram({
  source: 'graph.mmd',
  output: 'graph.gif',
  animationMode: 'ease-out',   // optional, defaults to 'none'
  duration: 4,                 // seconds
  frameRate: 24,
});

The programmatic interface mirrors CLI behavior: omit animationMode or set explicitly to 'none' for static output.

Where Animation Modes Are Implemented

Understanding the source structure helps when customizing or debugging animation behavior:

• commands/export-diagram.md — Documents the --animation-mode flag syntax and supported values
• prompts/export-diagram.md — Prompt template generating command snippets with animation options
• scripts/verify-motion.py — Validation script testing motion-related options including mode parsing

The CLI passes parsed flags to the diagram-design SDK's animation utilities, which map mode strings to easing function implementations in the rendering pipeline.

Animation Mode Selection Guidelines

Choose your mode based on export purpose:

• Documentation/static sites — Use none (default) for crisp, predictable images
• Technical tutorials — linear provides consistent, easy-to-follow motion
• Marketing/presentations — ease-in-out delivers polished, professional aesthetics
• Attention-directing — ease-out draws focus with quick-start-then-settle behavior

Summary

• diagram-design supports five animation modes: none, linear, ease-in, ease-out, and ease-in-out
• Control via --animation-mode flag or -a short form in CLI; animationMode parameter in JavaScript API
• Default mode is none, producing static output when no flag is specified
• Mode selection determines easing function applied by the rendering engine
• Source documentation in commands/export-diagram.md and validation in scripts/verify-motion.py

Frequently Asked Questions

What happens if I don't specify an animation mode?

The system defaults to none. Your diagram exports as a static image without motion, regardless of output format. This ensures predictable, fast exports when animation isn't required.

Can I combine animation modes in a single export?

No. Each export accepts exactly one animation mode. The rendering engine applies a single easing function across all animated elements. For complex multi-phase animations, export separate sequences and composite externally.

Which output formats support animation?

GIF and MP4 formats preserve animation. PNG and static image formats automatically disable animation regardless of mode selection. The CLI warns when mode conflicts with output format, falling back to none for incompatible combinations.

How does the frame rate interact with animation mode?

Frame rate (--frame-rate or frameRate option) determines sampling density. Higher rates (30fps+) produce smoother motion, especially noticeable with ease-in and ease-out modes where acceleration changes are subtle. linear mode tolerates lower rates due to constant velocity.

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