How to Use Animation Modes in Archify: Enabling Trace Motion for Dynamic Diagrams

Set "animation": "trace" in your diagram's meta object to enable trace motion, which animates edges with flowing dashes and pulses nodes to show data flow across your diagram.

Archify's renderer supports animated diagram elements that visualize the flow of data or control-flow through a system. This trace motion feature is controlled through a single JSON property, making it easy to add professional animations to workflow, architecture, and other diagram types. This guide explains how to enable animation modes in Archify using the trace effect, based on the tt-a1i/archify source code.

Understanding the Animation Schema

Archify defines animation options at the schema level. In archify/schemas/architecture.schema.json, the meta.animation property is defined as an enumeration with two values:

"animation": {
  "enum": ["trace", "none"]
}

• trace – Activates trace motion. Edges display moving dashes (archify-edge-flow) and nodes pulse (archify-node-pulse).
• none – Default behavior. Renders a static SVG with no animation.

The schema validation ensures only these values are accepted, preventing invalid animation configurations.

How the Renderer Implements Trace Motion

When you enable trace animation, three components work together to produce the visual effect.

1. SVG Root Attribute Injection

In archify/renderers/shared/cli.mjs, the svgRootAttrs function checks meta.animation and injects data-animation="trace" on the root <svg> element when the flag is set:

// cli.mjs L45-L46
if (meta.animation === 'trace') {
  attrs['data-animation'] = 'trace';
}

2. Per-Element Animation Attributes

The same file uses animateAttr to add data-animate attributes with step offsets to individual elements:

// cli.mjs L64-L71
const animateAttr = (type, step) => {
  return meta.animation === 'trace' 
    ? { 'data-animate': type, 'data-step': step }
    : {};
};

This staggers animations so edges and nodes animate in sequence rather than simultaneously.

3. CSS Keyframes and Styling

The bundled template at archify/assets/template.html contains the actual animation definitions:

• @keyframes archify-edge-flow – Creates the moving dashed line effect on edges
• @keyframes archify-node-pulse – Produces the pulsating highlight on nodes

These keyframes are scoped to [data-animation="trace"] selectors, so animations only run when explicitly enabled.

Enabling Trace Animation in Your Diagram

Add the animation property to your diagram's meta object:

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "meta": {
    "title": "Data Processing Pipeline",
    "animation": "trace",
    "visual_preset": "classic"
  },
  "nodes": [
    { "id": "input", "type": "start" },
    { "id": "process", "type": "task" },
    { "id": "output", "type": "end" }
  ],
  "edges": [
    { "from": "input", "to": "process" },
    { "from": "process", "to": "output" }
  ]
}

The example archify/examples/agent-tool-call.workflow.json demonstrates this pattern in practice, with animation enabled in lines 5-8.

Rendering Animated Diagrams

Use the CLI renderer to generate HTML with embedded animations:

node render-workflow.mjs path/to/your-diagram.json

The loadDiagram function in cli.mjs (lines 14-22) handles the full pipeline: reading JSON, validating against the schema, and passing the meta object to the renderer. Output is a self-contained HTML file with the animated SVG.

Disabling Animation

To produce static output, either omit the animation property or set it explicitly:

{
  "meta": {
    "title": "Static Architecture Diagram",
    "animation": "none"
  }
}

This prevents the data-animation attribute from appearing on the SVG, and no keyframe animations are applied.

Accessibility: Reduced Motion Support

Archify respects prefers-reduced-motion settings. In archify/assets/template.html (lines 998-1005), the "Motion Governor" block forces animations to none when users disable motion:

@media (prefers-reduced-motion: reduce) {
  [data-animation="trace"] * {
    animation: none !important;
  }
}

This ensures diagrams remain accessible without requiring JSON changes.

Summary

• Set "animation": "trace" in meta to enable edge and node animations
• The renderer in cli.mjs adds data-animation and data-animate attributes to SVG elements
• CSS keyframes in template.html drive the visual effects when the flag is present
• Reduced motion preferences automatically disable animations for accessibility
• Schema validation in architecture.schema.json restricts values to "trace" or "none"

Frequently Asked Questions

What diagram types support trace animation?

All diagram types that include the meta.animation schema field support trace motion. This includes workflow and architecture diagrams as defined in archify/schemas/architecture.schema.json. Check your specific diagram type's schema to confirm the field is available.

Can I customize the animation speed or colors?

The current tt-a1i/archify implementation uses fixed CSS keyframes in archify/assets/template.html. The animation timing and colors are determined by the archify-edge-flow and archify-node-pulse keyframes. To customize, you would need to modify the template or override the CSS after generation.

Does trace animation work in exported PNG or PDF files?

No. Trace animation requires the CSS keyframes and JavaScript runtime present in the HTML output. Static exports like PNG or PDF capture only the initial frame. For animated documentation, use the HTML format or embed the SVG with its accompanying styles.

How do I test that animation is correctly enabled?

The repository includes archify/test/animation.test.mjs, which validates that data-animation="trace" appears only when meta.animation is set to "trace". You can run this test suite or inspect the generated HTML source to verify the attribute is present on the root <svg> element.

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